Module network.socket

Description

load network.socket

This module provides the Network.Socket abstraction for protocol-specific socket implementations and the helper value objects used to configure them.

Packages

• Network

Enums

Network.Socket.IOStatus

This enum describes the status of an I/O operation.

| Constant | Value | Description ||----------|-------|-------------|

| IOClosed | 2 | The I/O operation was performed on a closed device. | | IOError | 3 | The I/O operation has failed. | | IOSuccess | 0 | The I/O operation has succeed. | | IOWouldBlock | 1 | The I/O operation would block. |

Network.Socket.State

This enum describes the different states in which a socket can be.

| Constant | Value | Description ||----------|-------|-------------|

| Bound | 2 | The socket is bound to an address and port. | | Closed | 7 | The socket was closed. | | Closing | 6 | The socket is about to close (data may still be waiting to be written). | | Connected | 4 | A connection is established. | | Connecting | 3 | The socket has started establishing a connection. | | Error | 8 | The socket entered an invalid state. | | Listening | 5 | The socket is ready to receive connection requests. | | Open | 1 | The socket is open. | | Unknown | 0 | The socket is not initialized. |

Network.SocketOption

This enum describes the options of a socket. The effective value of the option code can depend on the current system.

| Constant | Value | Description ||----------|-------|-------------|

| BROADCAST | 0 | Permit sending of broadcast datagrams (boolean). | | DEBUG | 1 | Enable debug tracing (boolean). | | DONTROUTE | 2 | Bypass routing table lookup (boolean). | | ERROR | 3 | Get pending error and clear (Network.SocketOption.Exception.SocketError, read... | | KEEPALIVE | 4 | Periodically test if connection still alive (boolean). | | LINGER | 5 | Linger on close if data to send (Network.SocketOption.Network.SocketLinger). | | OOBINLINE | 6 | Leave received out-of-band data inline (boolean). | | RCVBUF | 7 | Receive buffer size (number). | | RCVLOWAT | 9 | Receive buffer low-water mark (number). | | RCVTIMEO | 11 | Receive timeout (Network.SocketOption.Network.SocketTime). | | REUSEADDR | 13 | Allow local address reuse (boolean). | | REUSEPORT | 14 | Allow local port reuse (boolean). | | SNDBUF | 8 | Send buffer size (number). | | SNDLOWAT | 10 | Send buffer low-water mark (number). | | SNDTIMEO | 12 | Send timeout (Network.SocketOption.Network.SocketTime). | | TYPE | 15 | Get socket type (number, read only). | | USELOOPBACK | 16 | Routing socket gets copy of what it sends (boolean). |

Classes

Network.AsyncSocket

Wrapper class used to associate a socket with its scheduler. This class is used internally by the asynchronous operations to access the socket's scheduler and handle.

Public members

Modifiers	Member	Description
const	close	Asynchronously closes the socket. If the socket is currently connected, this ...
const	getEndpoint	Returns the endpoint associated with the object.
const	getHandle	Returns the socket's handle as an instance of mint::handle_t or none if the s...
const	getScheduler	Returns the scheduler associated with the socket.
const	getSocket	Returns the underlying socket object.
const	getSocketOption	Returns the value of the socket option described by option. The option parame...
const	getState	Returns the current state of the socket as a value of Network.AsyncSocket.Net...
const	isBound	Returns true if the socket is bound; otherwise returns false.
const	isNonBlocking	Returns true if the socket performs I/O operations without blocking; otherwis...
const	isOpen	Returns true if the socket is open; otherwise returns false.
const	new	Creates a new wrapper for socket associated with scheduler.
const	setNonBlocking	Sets the non blocking mode of the socket to enabled. Returns true if the mode...
const	setSocketOption	Sets the value of the socket option described by option to value. The option ...

Package members

Modifiers	Member	Description
const	setEndpoint	Sets the endpoint associated with the object to endpoint.
const	setHandle	Sets the socket's handle to handle. If the socket already had a handle, the p...
const	setState	Updates the current socket state. The state parameter must be a value from the ``...

Private members

Modifiers	Member	Description
@ const	g_lib	Global library handle.
final	scheduler	Internal scheduler object.
final	socket	Internal socket object.

Network.Socket

Base class representing a network communication socket (layers 4 of the OSI model).

A socket encapsulates a network connection and provides both synchronous and asynchronous operations for connecting, sending and receiving data.

Asynchronous operations integrate with Runtime.Scheduler and use Mint coroutines to suspend execution until the underlying socket becomes ready for the requested operation.

Concrete implementations such as TCP/IP sockets must implement the low-level synchronous methods while the asynchronous variants are implemented using Runtime.Operation.

Public members

Modifiers	Member	Description
enum	IOStatus	This enum describes the status of an I/O operation.
enum	State	This enum describes the different states in which a socket can be.
const	close	Closes the communication with the peer if the socket was in the Network.Socke...
const	delete	Cleanup the socket.
const	getEndpoint	Returns the endpoint associated with the object.
const	getHandle	Returns the socket's handle as an instance of mint::handle_t or none if the s...
const	getSocketOption	Returns the value of the socket option described by option. The option parame...
const	getState	Returns the current state of the socket as a value of Network.Socket.Network....
const	isBound	Returns true if the socket is bound; otherwise returns false.
const	isNonBlocking	Returns true if the end point performs I/O operations without blocking (i.e. ``...
const	isOpen	Returns true if the socket is open; otherwise returns false.
const	new	Creates a new socket.
	onState	Handles socket state transitions. This method can be overridden by subclasses...
const	setNonBlocking	Sets the non blocking mode of the socket to enabled. Returns true if the mode...
const	setSocketOption	Sets the value of the socket option described by option to value. The option ...

Package members

Modifiers	Member	Description
const	overrideNonBlockingFlag	Sets the non blocking mode of the socket to enabled without changing the handle.
const	releaseHandle	Resets the socket's handle without closing it.
const	setEndpoint	Sets the endpoint associated with the object to endpoint.
const	setHandle	Sets the socket's handle to handle. If the socket already had a handle, the p...
const	setState	Updates the current socket state. The state parameter must be a value from the ``...

Private members

Modifiers	Member	Description
final	endpoint	Internal endpoint object.
@ const	g_lib	Global library handle.
final	handle	Internal handle.
final	nonBlocking	Internal non blocking state.
final %	state	Internal socket's state.

Network.SocketLinger

This class maintains information about a specific socket that specifies how that socket should behave when data is queued to be sent and Network.Socket.close is called on the socket.

Public members

Modifiers	Member	Description
const	getLingerTime	Specifies how long to remain open after closed to enable queued data to be se...
const	isEnabled	Returns true if enabled; otherwise returns false. This attribute specifies wh...
const	new	Creates a new linger object for the given data. The data parameter can be an ...
const	setEnabled	Specifies whether a socket should remain open for a specified amount of time ...
const	setLingerTime	Sets the linger time in seconds. This attribute specifies how long to remain ...

Package members

Modifiers	Member	Description
const	to_linger	Returns the pointer to the internal struct linger instance.

Private members

Modifiers	Member	Description
final	d_ptr	Object data.
@ const	g_lib	Global library handle.

Network.SocketTime

This class is used to specify a time interval.

Public members

Modifiers	Member	Description
const	getMicroseconds	Returns the time interval, in microseconds. This value is used in combination...
const	getSeconds	Returns the time interval, in seconds.
const	new	Creates a new time interval object for the given data. The data parameter can...
const	setMicroseconds	Specifies the time interval in microseconds. This value is used in combinatio...
const	setSeconds	Specifies the time interval in seconds.

Package members

Modifiers	Member	Description
const	to_timeval	Returns the pointer to the internal struct timeval instance.

Private members

Modifiers	Member	Description
final	d_ptr	Object data.
@ const	g_lib	Global library handle.

Descriptions

Network.AsyncSocket.close

def (self)

Asynchronously closes the socket.

If the socket is currently connected, this operation terminates the communication with the peer. If the socket is listening, it stops accepting new connections.

Returns true if the socket was successfully closed.

The socket will enter the Network.Socket.State.Closed state on success or Network.Socket.State.Error on error.

Network.AsyncSocket.g_lib

lib ('libmint-network')

Global library handle.

Network.AsyncSocket.getEndpoint

def (const self)

Returns the endpoint associated with the object.

Network.AsyncSocket.getHandle

def (const self)

Returns the socket's handle as an instance of mint::handle_t or none if the socket has no handle.

Network.AsyncSocket.getScheduler

def (const self)

Returns the scheduler associated with the socket.

Network.AsyncSocket.getSocket

def (const self)

Returns the underlying socket object.

Network.AsyncSocket.getSocketOption

def (self, % option)

Returns the value of the socket option described by option. The option parameter must be a value of the Network.SocketOption enum.

An instance of Exception.SocketError is raised on error.

Network.AsyncSocket.getState

def (const self)

Returns the current state of the socket as a value of Network.Socket.State.

Network.AsyncSocket.isBound

def (const self)

Returns true if the socket is bound; otherwise returns false.

Network.AsyncSocket.isNonBlocking

def (const self)

Returns true if the socket performs I/O operations without blocking; otherwise returns false.

Network.AsyncSocket.isOpen

def (const self)

Returns true if the socket is open; otherwise returns false.

Network.AsyncSocket.new

def (self, socket, scheduler)

Creates a new wrapper for socket associated with scheduler.

Network.AsyncSocket.scheduler

null

Internal scheduler object.

Network.AsyncSocket.setEndpoint

def (self, endpoint)

Sets the endpoint associated with the object to endpoint.

Network.AsyncSocket.setHandle

def (self, handle)

Sets the socket's handle to handle. If the socket already had a handle, the previous handle is closed and replaced.

Network.AsyncSocket.setNonBlocking

def (self, enabled)

Sets the non blocking mode of the socket to enabled. Returns true if the mode was successfully changed; otherwise returns false.

Network.AsyncSocket.setSocketOption

def (self, % option, value)

Sets the value of the socket option described by option to value. The option parameter must be a value of the Network.SocketOption enum.

An instance of Exception.SocketError is raised on error.

Network.AsyncSocket.setState

def (self, % state)

Updates the current socket state.

The state parameter must be a value from the Network.Socket.State enumeration.

If the state differs from the current one, the onState callback is invoked before the internal state is updated.

Implementations may override onState to react to state transitions.

Network.AsyncSocket.socket

null

Internal socket object.

Network.Socket.IOStatus.IOClosed

2

The I/O operation was performed on a closed device.

Network.Socket.IOStatus.IOError

3

The I/O operation has failed.

Network.Socket.IOStatus.IOSuccess

0

The I/O operation has succeed.

Network.Socket.IOStatus.IOWouldBlock

1

The I/O operation would block.

Network.Socket.State.Bound

2

The socket is bound to an address and port.

Network.Socket.State.Closed

7

The socket was closed.

Network.Socket.State.Closing

6

The socket is about to close (data may still be waiting to be written).

Network.Socket.State.Connected

4

A connection is established.

Network.Socket.State.Connecting

3

The socket has started establishing a connection.

Network.Socket.State.Error

8

The socket entered an invalid state.

Network.Socket.State.Listening

5

The socket is ready to receive connection requests.

Network.Socket.State.Open

1

The socket is open.

Network.Socket.State.Unknown

0

The socket is not initialized.

Network.Socket.close

def (self)

Closes the communication with the peer if the socket was in the Network.Socket.State.Connected state or stops listening if the socket was in the Network.Socket.State.Listening state.

On success, the socket enter the Network.Socket.State.Closed state.

An instance of Exception.SocketError is raised on error.

Network.Socket.delete

def (self)

Cleanup the socket.

Network.Socket.endpoint

none

Internal endpoint object.

Network.Socket.g_lib

lib ('libmint-network')

Global library handle.

Network.Socket.getEndpoint

def (const self)

Returns the endpoint associated with the object.

Network.Socket.getHandle

def (const self)

Returns the socket's handle as an instance of mint::handle_t or none if the socket has no handle.

Network.Socket.getSocketOption

def (self, % option)

Returns the value of the socket option described by option. The option parameter must be a value of the Network.SocketOption enum.

An instance of Exception.SocketError is raised on error.

Network.Socket.getState

def (const self)

Returns the current state of the socket as a value of Network.Socket.State.

Network.Socket.handle

none

Internal handle.

Network.Socket.isBound

def (const self)

Returns true if the socket is bound; otherwise returns false.

Network.Socket.isNonBlocking

def (const self)

Returns true if the end point performs I/O operations without blocking (i.e. Network.Socket.read or Network.Socket.write returns immediately without waiting for I/O completion); otherwise returns false.

Network.Socket.isOpen

def (const self)

Returns true if the socket is open; otherwise returns false.

Network.Socket.new

def (self)

Creates a new socket.

This method initialize the internal socket's state and must be called in the implementation class constructor.

Network.Socket.nonBlocking

none

Internal non blocking state.

Network.Socket.onState

def (self, % state)

Handles socket state transitions.

This method can be overridden by subclasses to react to state changes.

The state parameter represents the new state that will be applied to the socket. The previous state can still be retrieved using getState during the execution of this method.

[!WARNING] Calling setState from within this method may cause an infinite recursion and should generally be avoided.

Network.Socket.overrideNonBlockingFlag

def (self, enabled)

Sets the non blocking mode of the socket to enabled without changing the handle.

Network.Socket.releaseHandle

def (self)

Resets the socket's handle without closing it.

Network.Socket.setEndpoint

def (self, endpoint)

Sets the endpoint associated with the object to endpoint.

Network.Socket.setHandle

def (self, handle)

Sets the socket's handle to handle. If the socket already had a handle, the previous handle is closed and replaced by the new one.

Network.Socket.setNonBlocking

def (self, enabled)

Sets the non blocking mode of the socket to enabled. Returns true if the mode was successfully changed; otherwise returns false.

Network.Socket.setSocketOption

def (self, % option, value)

Sets the value of the socket option described by option to value. The option parameter must be a value of the Network.SocketOption enum.

An instance of Exception.SocketError is raised on error.

Network.Socket.setState

def (self, % state)

Updates the current socket state.

The state parameter must be a value from the Network.Socket.State enumeration.

If the state differs from the current one, the onState callback is invoked before the internal state is updated.

Implementations may override onState to react to state transitions.

Network.Socket.state

null

Internal socket's state.

Network.SocketLinger.d_ptr

null

Object data.

Network.SocketLinger.g_lib

lib ('libmint-network')

Global library handle.

Network.SocketLinger.getLingerTime

def (const self)

Specifies how long to remain open after closed to enable queued data to be sent. This attribute is only applicable if enabled.

Network.SocketLinger.isEnabled

def (const self)

Returns true if enabled; otherwise returns false. This attribute specifies whether a socket should remain open for a specified amount of time after closed to enable queued data to be sent.

Network.SocketLinger.new

def (self, data)

Creates a new linger object for the given data. The data parameter can be an instance of Network.SocketLinger, in this case the object is returned as the new instance, or an instance of the linger C struct. The parameter can also provide a toSocketLinger method that will be used to create the object.

def (self, const enable, const linger_time)

Creates a new linger object. The enable parameter must be a boolean value used to specifies whether a socket should remain open for a specified amount of time after closed to enable queued data to be sent. The linger_time parameter must be a number used, if enabled, to sets the linger time in seconds. This value specifies how long to remain open after a closesocket function call to enable queued data to be sent.

Network.SocketLinger.setEnabled

def (self, const enabled)

Specifies whether a socket should remain open for a specified amount of time after closed to enable queued data to be sent.

Network.SocketLinger.setLingerTime

def (self, const linger_time)

Sets the linger time in seconds. This attribute specifies how long to remain open after closed to enable queued data to be sent. It is only applicable if enabled.

Network.SocketLinger.to_linger

def (const self)

Returns the pointer to the internal struct linger instance.

Network.SocketOption.BROADCAST

0

Permit sending of broadcast datagrams (boolean).

Network.SocketOption.DEBUG

1

Enable debug tracing (boolean).

Network.SocketOption.DONTROUTE

2

Bypass routing table lookup (boolean).

Network.SocketOption.ERROR

3

Get pending error and clear (Exception.SocketError, read only).

Network.SocketOption.KEEPALIVE

4

Periodically test if connection still alive (boolean).

Network.SocketOption.LINGER

5

Linger on close if data to send (Network.SocketLinger).

Network.SocketOption.OOBINLINE

6

Leave received out-of-band data inline (boolean).

Network.SocketOption.RCVBUF

7

Receive buffer size (number).

Network.SocketOption.RCVLOWAT

9

Receive buffer low-water mark (number).

Network.SocketOption.RCVTIMEO

11

Receive timeout (Network.SocketTime).

Network.SocketOption.REUSEADDR

13

Allow local address reuse (boolean).

Network.SocketOption.REUSEPORT

14

Allow local port reuse (boolean).

Network.SocketOption.SNDBUF

8

Send buffer size (number).

Network.SocketOption.SNDLOWAT

10

Send buffer low-water mark (number).

Network.SocketOption.SNDTIMEO

12

Send timeout (Network.SocketTime).

Network.SocketOption.TYPE

15

Get socket type (number, read only).

Network.SocketOption.USELOOPBACK

16

Routing socket gets copy of what it sends (boolean).

Network.SocketTime.d_ptr

null

Object data.

Network.SocketTime.g_lib

lib ('libmint-network')

Global library handle.

Network.SocketTime.getMicroseconds

def (const self)

Returns the time interval, in microseconds. This value is used in combination with the value of getSeconds to represent time interval values that are not a multiple of seconds.

Network.SocketTime.getSeconds

def (const self)

Returns the time interval, in seconds.

Network.SocketTime.new

def (self, data)

Creates a new time interval object for the given data. The data parameter can be an instance of Network.SocketTime, in this case the object is returned as the new instance, or an instance of the timeval C struct. The parameter can also provide a toTime method that will be used to create the object.

def (self, const sec, const usec)

Creates a new time interval object. The sec parameter must be a number used to specifies the time interval in seconds. The usec parameter must be a number used to specifies the time interval, in microseconds. This parameter is used in combination with the sec parameter to represent time interval values that are not a multiple of seconds.

Network.SocketTime.setMicroseconds

def (self, const usec)

Specifies the time interval in microseconds. This value is used in combination with the value passed to setSeconds to represent time interval values that are not a multiple of seconds.

Network.SocketTime.setSeconds

def (self, const sec)

Specifies the time interval in seconds.

Network.SocketTime.to_timeval

def (const self)

Returns the pointer to the internal struct timeval instance.