Provides full TCP connectivity.
Class TCPSocket from \
Socket( )
| Raise |
|
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. |
| 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. |
| 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 | |
| dispose | Closes a socket and frees system resources associated with it. |
| getHost | Gets the host associated with this socket. |
| getPort | Gets the port associated with this socket. |
| getService | Returns the service name (port description) associated with this socket |
| getTimeout | Returns the default timeout for this socket. |
| readAvailable | Checks if there is available data to be read on this socket. |
| setTimeout | Sets the default timeout for lengthy operations. |
| writeAvailable | Waits for the socket to be ready to write data. |
Closes the socket.
TCPSocket.close()
| Return | False if timed out, true if succesful | ||
| Raise |
|
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.
Closes a socket read side.
TCPSocket.closeRead()
| Return | False if timed out, true if succesful | ||
| Raise |
|
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.
Closes a socket write side.
TCPSocket.closeWrite()
| Return | False if timed out, true if succesful | ||
| Raise |
|
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.
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. | ||
| Return | False if timed out, true if succesful | ||
| Raise |
|
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.
Check if this TCPSocket is currently connected with a remote host.
TCPSocket.isConnected()
| Return | 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.
Reads incoming data.
TCPSocket.recv( buffer, [size] )
| buffer | A pre-allocated buffer to fill. | ||
| size | Maximum size in bytes to be read. | ||
| Return | Amount of bytes actually read. | ||
| Raise |
|
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 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). | ||
| Return | Number of bytes actually sent through the network layer. | ||
| Raise |
|
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.