Main index | | | Module description | | | Classes | | | Enums | | | Functions |
class
TCPSocket
from
\
Socket
Provides full TCP connectivity. more...
Constructor | |
init | Allocate system resources for TCP/IP Connectivity. |
Methods | |
close | Closes the socket. |
closeRead | Closes a socket read side. |
closeWrite | Closes a socket write side. |
connect | Connects this socket to a remote host. |
isConnected | Check if this TCPSocket is currently connected with a remote host. |
recv | Reads incoming data. |
send | Send data on the network connection. |
This class is derived from the Socket class, but it also provides methods that can be used to open connection towards remote hosts.
Allocate system resources for TCP/IP Connectivity.
TCPSocket.init( ) | |||
Raises: |
|
The constructor reserves system resources for the socket. If the needed system resources are not available, a NetError is Raised.
Closes the socket.
TCPSocket.close( ) | |||
Returns: | False if timed out, true if succesful | ||
Raises: |
|
Closes the socket, discarding incoming messages and notifying the remote side about the event. The close message must be acknowledged by the remote host, so the function may actually fail, block and/or timeout - see setTimeout() .
In case of error, a NetError is raised, while in case of timeout false is returned. On successful completion true is returned.
See also Socket.setTimeout.
Closes a socket read side.
TCPSocket.closeRead( ) | |||
Returns: | False if timed out, true if succesful | ||
Raises: |
|
Closes the socket read side, discarding incominig messages and notifying the remote side about the event. The close message must be acknowledged by the remote host, so the function may actually fail, block and/or timeout.
After the call, the socket can still be used to write (i.e. to finish writing pending data). This informs the remote side we're not going to read anymore, and so if the application on the remote host tries to write, it will receive an error.
In case of error, a NetError is raised, while in case of timeout false is returned. On successful completion, true is returned.
See also Socket.setTimeout.
Closes a socket write side.
TCPSocket.closeWrite( ) | |||
Returns: | False if timed out, true if succesful | ||
Raises: |
|
Closes the socket write side, discarding incoming messages and notifying the remote side about the event. The close message must be acknowledged by the remote host, so the function may actually fail, block and/or timeout.
After the call, the socket can still be used to read (i.e. to finish reading informations incoming from the remote host). This informs the remote side we're not going to write anymore, and so if the application on the remote host tries to read, it will receive an error.
In case of error, a NetError is raised, while in case of timeout false is returned. On successful completion, true is returned.
See also Socket.setTimeout.
Connects this socket to a remote host.
TCPSocket.connect( host, service ) | |||
host | Remote host to be connected to. | ||
service | Port or service name to be connected to. | ||
Returns: | False if timed out, true if succesful | ||
Raises: |
|
Connects with a remote listening TCP host. The operation may fail for a system error, in which case a NetError is raised.
The connection attempt may timeout if it takes more than the time specified in Socket.setTimeout method. In that case, the TCPSocket.isConnected method may check if the connection has been established at a later moment. So, it is possible to set the socket timeout to 0, and then check periodically for connection success without never blocking the VM.
The host name may be a name to be resolved by the system resoluter or it may be an already resolved dot-quad IP, or it may be an IPV6 address.
See also Socket.setTimeout.
Check if this TCPSocket is currently connected with a remote host.
TCPSocket.isConnected( ) | |
Returns: | True if the socket is currently connected, false otherwise. |
This method checks if this TCPSocket is currently connected with a remote host.
See also TCPSocket.connect.
Reads incoming data.
TCPSocket.recv( bufOrSize, [size] ) | |||
bufOrSize | A pre-allocated buffer to fill, or a maximum size in bytes to be read. | ||
size | Maximum size in bytes to be read. | ||
Returns: | If bufOrSize is a size, returns a filled string buffer, otherwise it returns the amount of bytes actually read. | ||
Raises: |
|
When the bufOrSize parameter is a buffer to be filled (i.e. a MemBuf or a string created with strBuffer), the buffer may be repeatedly used, sparing memory and allocation time. If the size parameter is not provided, the maximum amount of bytes that can be stored in the buffer will be used as read size limit,
This size won't change between call, even if the actual length of the data stored in the buffer changes.
If the size parameter is provided, it is used to define the maximum possible size of data stored in the buffer. If it is not great enough to store the data, it is resized.
When a target buffer is specified in the bufOrSize parameter, the method returns number of bytes that has been actually read. The size may be zero if the opposite side closed the connection, or if the timeout has elapsed. The returned size will presumably be smaller than the maximum, and it will be at maximum the size of a TCP packet that can travel on the current connection.
When a maximum size is specified in the bufOrSize parameter, the method returns a newly allocated buffer on success, and nil on failure.
In case of system error, a NetError is raised.
See also Socket.setTimeout.
Send data on the network connection.
TCPSocket.send( buffer, [size], [start] ) | |||
buffer | The buffer containing the data to be sent. | ||
size | Amount of bytes to be sent. | ||
start | Begin position in the buffer (in bytes). | ||
Returns: | Number of bytes actually sent through the network layer. | ||
Raises: |
|
The buffer may be a byte-only string or a byte-wide MemBuf; it is possible to send also multibyte strings (i.e. strings containing international characters) or multi-byte memory buffers, but in that case the sent data may get corrupted as a transmission may deliver only part of a character or of a number stored in a memory buffer.
If a (undefined) size parameter is not specified, the method will try to send the whole content of the buffer, otherwise it will send at maximum size bytes. If a (undefined) start parameter is specified, then the data sent will be taken starting from that position in the buffer (counting in bytes from the start).
This is useful when sending big buffers in several steps, so that it is not necessary to create substrings for each send, sparing both CPU and memory.
The returned value may be 0 in case of timeout, otherwise it will be a number between 1 and the requested size. Programs should never assume that a succesful send has sent all the data.
In case of error, a NetError is raised.
See also Socket.setTimeout.
Main index | | | Module description | | | Classes | | | Enums | | | Functions |