2.12.4Class TCPSocket

Provides full TCP connectivity.

Class TCPSocket from \
                 Socket( )
Raise
NetError on underlying network error.

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
closeCloses the socket.
closeReadCloses a socket read side.
closeWriteCloses a socket write side.
connectConnects this socket to a remote host.
isConnectedCheck if this TCPSocket is currently connected with a remote host.
recvReads incoming data.
sendSend data on the network connection.
Properties inherited from class Socket
lastError Numeric value of system level error that has occoured on the socket.
timedout True if the last operation has timed out.
Methods inherited from class Socket
disposeCloses a socket and frees system resources associated with it.
getHostGets the host associated with this socket.
getPortGets the port associated with this socket.
getServiceReturns the service name (port description) associated with this socket
getTimeoutReturns the default timeout for this socket.
readAvailableChecks if there is available data to be read on this socket.
setTimeoutSets the default timeout for lengthy operations.
writeAvailableWaits for the socket to be ready to write data.

Methods

close

Closes the socket.

TCPSocket.close()
ReturnFalse if timed out, true if succesful
Raise
NetError in case of underlying connection error during the closing phase.

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.

closeRead

Closes a socket read side.

TCPSocket.closeRead()
ReturnFalse if timed out, true if succesful
Raise
NetError in case of underlying connection error during the closing phase.

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.

closeWrite

Closes a socket write side.

TCPSocket.closeWrite()
ReturnFalse if timed out, true if succesful
Raise
NetError in case of underlying connection error during the closing phase.

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.

connect

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.
ReturnFalse if timed out, true if succesful
Raise
NetError in case of underlying connection error during the closing phase.

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.

isConnected

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

TCPSocket.isConnected()
ReturnTrue if the socket is currently connected, false otherwise.

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

See also: TCPSocket.

recv

Reads incoming data.

TCPSocket.recv( buffer, [size] )
buffer A pre-allocated buffer to fill.
size Maximum size in bytes to be read.
ReturnAmount of bytes actually read.
Raise
NetError on network error.

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.

See also: Socket.

send

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).
ReturnNumber of bytes actually sent through the network layer.
Raise
NetError on network error,

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.

See also: Socket.

Made with http://www.falconpl.org