Class TCPSocket[in Socket]

Provides full TCP connectivity.

class TCPSocket \ from Socket

more...

Summary

Inherited properties

Inherited methods

class TCPSocket \ from Socket

Provides full TCP connectivity.

This class is derived from the Socket class, but it also provides methods that can be used to open connection towards remote hosts.

The constructor reserves system resources for the socket. If the needed system resources are not available, a NetError is Raised.

Methods

close()

Closes the socket.

TCPSocket.close( )

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.

closeRead()

Closes a socket read side.

TCPSocket.closeRead( )

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.

closeWrite()

Closes a socket write side.

TCPSocket.closeWrite( )

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.

connect()

Connects this socket to a remote host.

TCPSocket.connect( host, service )

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.

isConnected()

Check if this TCPSocket is currently connected with a remote host.

TCPSocket.isConnected( )

This method checks if this TCPSocket is currently connected with a remote host.

recv()

Reads incoming data.

TCPSocket.recv( buffer, [size] )

The buffer parameter is a buffer to be filled: a MemBuf or a an empty string (for example, a string created with strBuffer).

If the size parameter is provided, it is used to define how many bytes can be read and stored in the buffer.

If the buffer parameter is a string, it is automatically resized to fit the incoming data. On a successful read, it's size will be trimmed to the amount of read data, but the internal buffer will be retained; successive reads will reuse the already available data buffer. For example:

 str = ""
while mySocket.recv( str, 1024 ) > 0
   > "Read: ", str.len()
   ... do something with str ...
end

This allocates 1024 bytes in str, which is trimmed each time to the amount of data really received, but is never re-allocated during this loop. However, this is more efficient as you spare a parameter in each call, but it makes less evident how much data you want to receive:

 str = strBuffer( 1024 )

while mySocket.recv( str ) > 0
   > "Read: ", str.len()
   ... do something with str ...
end

If the buffer parameter is a MemBuf, the read data will be placed at MemBuf.position. After a succesful read, up to MemBuf.limit bytes are filled, and MemBuf.position is advanced. To start processing the data in the buffer, use MamBuf.flip().

In case of system error, a NetError is raised.

send()

Send data on the network connection.

TCPSocket.send( buffer, [size], [start] )

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.

When using a MemBuf item type, the function will try to send the data between MemBuf.position and MemBuf.limit. After a correct write, the position is moved forward accordingly to the amount of bytes sent.

If a 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 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.

Note: The start and count parameters are ignored when using a memory buffer.

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 successful send has sent all the data.

In case of error, a NetError is raised.