Class

SocketCore


Description

The base class for TCPSocket and UDPSocket. The SSLSocket class is derived from TCPSocket. SocketCore is an abstract class and cannot be instantiated directly.

Methods

Name

Parameters

Returns

Shared

Close

Connect

Poll

Purge

Events

Name

Parameters

Returns

DataAvailable

Error

e As RuntimeException

SendComplete

userAborted As Boolean

Property descriptions


SocketCore.Handle

Handle As Integer

This is the socket's internal descriptor and it can be used with Declare statements.

This property is read-only.

  • On Windows, Handle is a Socket, suitable for use in Declares on Windows.

  • On macOS and Linux, Handle is a UNIX socket descriptor.

The descriptor is platform-specific. If Handle is less than zero, the descriptor is not available.


SocketCore.IsConnected

IsConnected As Boolean

Indicates whether the socket is currently connected.

This property is read-only.

For TCPSockets, a connection means you can send and receive data and are connected to a remote machine. For UDPSockets, this means that you are bound to the port and are able to send, receive, join or leave multicast groups, or set socket options.

If EasyUDPSocket1.IsConnected Then
  ' proceed using the connection
Else
  MessageBox("Connection failed!")
End If

SocketCore.LocalAddress

LocalAddress As String

The local IP address of the computer.

This property is read-only.

Var localIP As String = Socket1.LocalAddress

SocketCore.NetworkInterface

NetworkInterface As NetworkInterface

Specifies which network interface the socket should use when binding.

You can get the network interface(s) of the user's computer by calling the GetNetworkInterface method of the System module.

Leaving this property set to Nil will use the currently selected interface. In the case of UDPSockets, if you assign a non-Nil value, the socket may not be able to receive broadcast messages. The behavior is OS-dependent; it appears to work on Windows but not on other supported operating systems. If you wish to send broadcast packets out, then you should not bind to a specific interface because the behavior is undefined.

This example specifies that the TCPSocket will use the first Network Interface on the user's computer.

TCPSocket1.NetworkInterface = System.NetworkInterface(0)

SocketCore.Port

Port As Integer

The port to bind on or connect to.

On most operating systems, attempting to bind to a port less than 1024 causes a Error event to fire with an error number 107 unless the application is running with administrative permissions. This is due to security features built into the underlying OS.

You need to set the port property explicitly before any call to Listen or Connect as the Port property will be modified to reflect what the actual bound port is during the various stages of operation.

For instance, if you listen on port 8080 and a connection comes in, you can check the Port property to ensure that you're still listening on port 8080 (that the port hasn't been hijacked). Or, if you connect to a socket on port 8080, once the connection occurs, you can check to see what port the OS has bound you to. This will be a random-seeming port number.

This trick can be very useful when you do things like Listen on port 0. In that case, the OS will pick a port for you and listen on it. Then you can check the Port property to see which port the OS picked. This functionality is used for various protocols, such as FTP.

This example sets the Port to 8080.

TCPSocket1.Port = 8080

Method descriptions


SocketCore.Close

Close

Closes the socket's connection, closes any connections the socket may have, and resets the socket.

The only information that is retained after calling Close is the socket's port, address (in the case of TCPSockets), and data left in the socket's receive buffer. All other information is discarded.

This example closes the EasyTCPSockets that were open. The sockets were added to the main window.

Connector.Close
Listener.Close

SocketCore.Connect

Connect

Attempts to connect.

For TCPSockets, the address and port properties must be set. For UDPSockets, the port property must be set. The Connect method binds a socket to a port. After calling Connect, the Port property will report the actual port you are bound to.


SocketCore.Poll

Poll

Polls the socket manually, which allows a socket to be used synchronously.

The EasyTCPSocket "Listener" has been added to the window.

Listener.Poll

SocketCore.Purge

Purge

Removes all data from the socket's internal receive buffer. It does not affect the socket's internal send buffer.

Listener.Purge

Event descriptions


SocketCore.DataAvailable

DataAvailable

Occurs when additional data has come into the internal receive buffer.


SocketCore.Error

Error(e As RuntimeException)

Occurs when an error occurs with the socket.

These error codes provide you with key information about your socket, and it is not advisable to ignore them.

When an error occurs, the RuntimeException property will likely contain one of the following error codes:

Error Code

Description

0

No error occurred.

100

There was an error opening and initializing the drivers.

101

This error code is no longer used.

102

This code means that you lost your connection.

103

The socket was unable to resolve the address that was specified.

104

This error code is no longer used.

105

The address is currently in use.

106

This is an invalid state error, which means that the socket is not in the proper state to be doing a certain operation.

107

This error means that the port you specified is invalid.

108

This error indicates that your application has run out of memory.

These are not the only errors that are returned. For Windows, additional error codes are usually positive numbers in the range [10004, 11004]. For Windows error codes, see WinSock.h. MacOS and Linux use POSIX error codes. For a description of macOS and Linux error codes, see http://www.ioplex.com/~miallen/errcmp.html.

e.g. error 64 is for "host is down".

The following example in the Error event handler displays the error code.

MessageBox(Me.e.ErrorNumber.ToString)

SocketCore.SendComplete

SendComplete(userAborted As Boolean)

Occurs when a send has completed.

Use this to determine when all your data has been sent. userAborted will be True if the user aborted the send by returning True from the SendProgress event. You can use this information to update different status variables or to inform user about the success or failure of the transfer. If the send was completed, this value is False. UserAborted will always be False for UDP sockets.

Notes

There are some instances where you would like the system to pick a port for you. These needs can range from needing a port for passive FTP file transfers, or perhaps you wrote a class to auto-discover other applications on the network and you would like to negotiate a port to connect over using TCP/IP. If you specify a Port of 0 and then call TCPSocket or UDPSocket.Connect, a random port will be picked for you. Most often, these ports will be in the range of 49512 to 65535 (inclusive).

If you use this method to obtain an open port, then you probably need to use the following procedure to determine which port was chosen. After calling the Connect method or the Listen method of the TCPSocket class, you can check the Port property to see which port was assigned. This means that the port number will change from 0 to the port number that you are bound to.

There's another benefit checking the Port property. There is a hacking technique called port hijacking where the hacker steals a port out from under you. If this happens, checking the Port property will tell you if someone has hijacked the port. It can be a good idea (though paranoid) to periodically check to make sure the Port property returns a port that you expect to see. For instance, if you were listening on port 80 for HTTP connections, but the Port property says you're listening on port 2113, then something may be wrong.

The SendComplete event's parameter lets you know whether the transfer has completed or has been cancelled by returning True from the SendProgress event of the TCPSocket class. You can use this information to update different status variables, or alert the user of transfer success or failure. If the user aborted, this parameter is True, and if the send was completed, this value is False. The SendComplete event's parameter is always False for UDPSockets since there is not a SendProgress event for that class.


Endianness

There are two different endian standards. Intel, Apple and ARM CPUs use "little" endianness. Sockets work with streams of data and do not change the endianness of the data you are transferring. This is fine in most cases, but if you are transferring binary data, such as from a BinaryStream or a MemoryBlock, you will want to ensure that the endianness matches from server to client regardless of what platform you are on. You can do this by setting the LittleEndian property on MemoryBlocks or BinaryStreams to the same value for your client and your server. Failure to ensure that the endianness is consistent will result in a possible byte-order conflict in your application. You can use the TargetBigEndian and TargetLittleEndian constants to determine the endian standard for the platform on which your app is running.

Compatibility

All project types on all supported operating systems.

See also

Object parent class; Datagram, ServerSocket, TCPSocket, UDPSocket classes.