Sidebar
k24:k24.1:k24.1.1:start
Table of Contents
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.
k24/k24.1/k24.1.1/start.txt · Last modified: 18.06.2022 (external edit)
Page Tools
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Noncommercial 3.0 Unported
