k24:k24.1:k24.1.1:start

24.1.1 Socket (gb.net)
24.1.1.1 Properties
24.1.1.2 Methods
24.1.1.3 Events

24.1.1 Socket (gb.net)

From the perspective of a Gambas application, a socket is an access point to the network and encapsulates the details of network communication. The methods of the Socket class provide both the functions for establishing connections and for communication between at least two network participants. TCP, UDP and local (Unix sockets) connections are implemented.

Note: A separate chapter is dedicated to Unix sockets in '24.1.4 UnixSocket'.

This class performs its work asynchronously. Programs are not stopped when connecting, sending or receiving data. This class is derived from the class Stream, so you can use its standard methods to send and receive data and to close the socket.

To create a new socket:

Dim hSocket As Socket
hSocket = New Socket() As "EventName"

24.1.1.1 Properties

The Socket class has these properties:

Property	Data type	Description
Host	String	The host to which the client wants to connect (IP address or host name).
LocalHost	String	Once a TCP connection to a server has been established, this property reflects the local IP address used by that connection.
LocalPort	Integer	Once a TCP connection to a server has been established, this property reflects the local port (1-65535) used by that connection.
Port	Integer	The port to connect to on the remote host
RemoteHost	String	Once a TCP connection to a server has been established, this property reflects the remote IP address used by that connection.
RemotePort	Integer	Once a TCP connection to a server has been established, this property reflects the remote port (1-65535) used by that connection.
Server	ServerSocket	If a socket was created with the Accept() method of a server socket, a ServerSocket object is returned with this property. Otherwise, NULL is returned.
Status	Integer	Reflects the current status of a Socket object.
Timeout	Integer	Returns or sets the value for a timeout of the socket in milliseconds.

Table 24.1.1.1 : Properties of the class Socket

Notes on selected values (→ Chapter 24.1.6 Net constants) of the Socket.Status property:

Net.CannotCreateSocket → The system did not allow to create a new socket.
Net.SocketRefused → The server denied the requested connection.
Net.CannotRead → Data cannot be read, connection interrupted.
Net.CannotWrite → Data cannot be written, connection interrupted.
Net.Searching → An attempt is made to resolve the host name to the IP address.
Net.Connecting → An attempt is made to connect to a remote server.
Net.Connecting → Connected to the remote server, ready to send and receive.
Net.Inactive → Socket closed.

24.1.1.2 Methods

The Socket class provides the following methods:

Method	Description
Begin ( )	Begin buffering the data written to the stream in the socket buffer so that everything is sent when the Send() method is called.
Send ( )	Sends all data buffered in the socket buffer since the last call to Begin() method in one go.
Drop ( )	Deletes all data buffered in the socket buffer since the last call to Begin() method.
Peek ( ) As String	With this function you can receive data from the socket. It may only be used when the connection is active (Status = Net.Connected), otherwise an error will be triggered.
ReadLine ( [ Escape As String ] ) As String	Reads a text line from the data stream, as with the instruction LINE INPUT.
Watch ( Mode As Integer, Watch As Boolean )	Allows to control the monitoring of the stream file descriptor for reading or writing after it has been opened.

Table 24.1.1.2.1 : Methods of the Socket class.

Notes:

Peek(): The string is not cleared from the socket buffer. So the next time you receive data, you will receive the same string, supplemented by new data that has arrived in the socket.

ReadLine(…): If an 'escape' character is specified, then line breaks between two escape characters are ignored. This method is very useful when reading CSV files.

Watch(): 'Mode' is the monitoring type: set gb.Read to watch reading and gb.Write to watch writing. Watch = True enables monitoring and Watch = False disables monitoring.

24.1.1.3 Events

The Socket class has these events:

Event	Description
Closed ( )	This event occurs after the remote side of the socket has closed the connection. The status property is set to the value Net.Inactive.
Error ( )	This event occurs when instructions have failed. For example, when the remote server has refused the connection. The status property becomes a negative value reflecting the error type and the socket is automatically closed.
Found ( )	For connections via TCP sockets, the first step is to resolve the host name to the host IP address or confirm the IP address. This event is triggered when the host name has been successfully resolved to the host IP address or the IP address has been confirmed.
Ready ( )	This event is triggered after a connection between the client and server has been successfully established. The status property is set to the value Net.Connected.
Read ( )	This event is triggered when data from the communication partner on the other side of the IP connection has arrived in the socket.
Write ( )	This event is triggered when the internal socket send buffers can hold more data.

Table 24.1.1.3.1 : Events of the class Socket

Notice:

Write(): This event is most useful when you want to send a large file. The Write event does not fire continuously because a socket is almost always ready to receive data. You need to signal to Gambas that you have some data to write by performing an initial write to the socket.
After the initial write, the Write() event will fire continuously as long as you continue to write more data within the Write event handling routine.

Table of Contents

24.1.1 Socket (gb.net)

24.1.1.1 Properties

24.1.1.2 Methods

24.1.1.3 Events