Socket Functions

The Socket functions supply an easy way to interact with other nodes on a computer network, including the ability to send and receive binary data and UTF-8 strings.

Handles

The handle is a native data type used to interact with an external resource, including sockets. With a native data type, the AeroScript compiler can supply a well-defined interface for socket operations with improved type-checking. For more information, refer to Fundamental Handle Data Type on the Data Types and Variables page.

Open and Close a Socket

You must open a handle before you can use it to communicate with a socket. After you open the handle, you can pass it to other socket operation functions to do many supported operations.

The controller supports sockets that use the Transmission Control Protocol (TCP). These are the main features of TCP:

Data that is lost in the network is sent again.
Data is received from the network in the same order that it was sent.

You can use the TCP socket types that follow:

TCP server: Waits for one or more TCP clients to connect.
TCP client: Connects to a TCP server that is waiting for TCP clients to connect.

Open a TCP Server Socket

Use the function that follows to create a TCP server socket.

function SocketTcpServerCreate($port as integer) as handle

Creates a TCP server socket that listens on the specified port.

Arguments

$port The port on which to listen for incoming connections. Must be between 0 and 65535.

Returns

A socket handle representing a TCP server.

After you create a TCP server socket, one or more TCP clients can connect to the TCP server. TCP clients that connect are put into a backlog. Use the function that follows to find if a TCP server socket has one or more TCP clients in the backlog.

function SocketTcpServerIsClientPending($socket as handle) as integer

Checks if there are any client connections pending on the specified server.

Arguments

$socket The socket on which to check for pending clients. Must be a TCP server socket.

Returns

Returns 1 if there are pending connections, 0 otherwise.

Use the function that follows to accept a TCP client from the backlog and create a TCP client socket to communicate with the TCP client.

function SocketTcpServerAccept($socket as handle) as handle

Accepts a pending TCP client connection as a new socket connection.

Arguments

$socket The socket from which to accept a pending TCP client. Must be a TCP server socket.

Returns

A socket handle representing the accepted TCP client.

Program Example

var $serverSocket as handle
var $clientSocket as handle

$serverSocket = SocketTcpServerCreate(8080)

while true
    if SocketTcpServerIsClientPending($serverSocket)
        $clientSocket = SocketTcpServerAccept($serverSocket)
        
        // Communicate with the TCP client.
    end
end

Open a TCP Client Socket

Use the function that follows to connect to a TCP server and create a TCP client socket that you can use for communication with the server. You can specify a hostname, an IPv4 address, or an IPv6 address for the $host argument. For example, "google.com", "192.168.2.2", or "2001:db8:3333:4444:5555:6666:7777:8888". You can specify "localhost", "127.0.0.1", or "::1" for the $host argument to connect to a TCP server that is listening on the same host as the controller.

function SocketTcpClientCreate($host as string, $port as integer, $timeout as integer) as handle

Creates a TCP client connection to the specified TCP server using the specified host and port.

Arguments

$host The address that will be used to connect to the TCP server.

$port The port through which to connect to the TCP server, represented as an integer between 0 and 65535.

$timeout The maximum number of milliseconds to wait for a connection to succeed. A value of zero represents an infinite timeout.

Returns

A socket handle representing a TCP client.

Use the function that follows to determine if a TCP client socket is still connected to another host.

function SocketTcpClientIsConnected($socket as handle) as integer

Checks if the specified socket connection is active.

Arguments

$socket The socket on which to check the connection. Must be a TCP client socket.

Returns

Returns 1 if connected, 0 otherwise.

Program Example

var $clientSocket as handle

$clientSocket = SocketTcpClientCreate ("192.168.50.2", 8080, 1000)
if SocketTcpClientIsConnected ($clientSocket)
	// the client is still connected.
end

Close a Socket

Use the function that follows to close a TCP server socket or TCP client socket. The controller automatically closes all sockets that you created on a task when the task stops or a task error occurs.

function SocketClose($socket as handle)

Closes the specified socket, shutting down any active connections.

Arguments

$socket The socket to close.

Reading and Writing

Read and Write Buffers

Sockets have a buffer so that you can immediately read and write data. Use the functions that follow to find the number of bytes that you can read from a socket or write to a socket without waiting.

function SocketGetReadBytesAvailable($socket as handle) as integer

Gets the number of bytes that can immediately be read from the specified socket.

Arguments

$socket The socket on which to check the number of available bytes. Must be a TCP client socket.

Returns

Returns the number of bytes that are available to be read.

function SocketGetWriteBytesAvailable($socket as handle) as integer

Gets the number of bytes that can immediately be written to the specified socket.

Arguments

$socket The socket on which to check the number of bytes that can be written. Must be a TCP client socket.

Returns

Returns the number of bytes that can be written.

The controller automatically updates the buffers for reading and writing data. This operation does not execute in real time. The time that it takes for this operation to execute is different for different networks.

Use the functions that follow to configure timeout values for socket read and write operations. The controller generates a task error if you try to read from a socket or write to a socket and the specified operation does not complete before the period specified by the timeout value. By default, read and write operations on a socket are configured to use an infinite timeout value.

function SocketSetDataReadTimeout($socket as handle, $timeout as integer)

Configures the timeout to use when reading data from the specified socket.

Arguments

$socket The socket on which to configure the timeout for read operations. Must be a TCP client socket.

$timeout The maximum number of milliseconds to wait for a read operation to succeed. A value of zero represents an infinite timeout.

function SocketSetDataWriteTimeout($socket as handle, $timeout as integer)

Configures the timeout to use when writing data to the specified socket.

Arguments

$socket The socket on which to configure the timeout for write operations. Must be a TCP client socket.

$timeout The maximum number of milliseconds to wait for a write operation to succeed. A value of zero represents an infinite timeout.

Binary Data

When you operate on binary data from a socket, you must determine how the raw bytes of the data are to be interpreted. AeroScript supplies individual functions to access the current socket data stream location based on the specified underlying data type. And, you can use the array-based functions to access contiguous sequences of the socket data.

Supported data types:

Float32 - IEEE 754 single-precision floating point
Float64 - IEEE 754 double-precision floating point
Int8 - signed 8-bit integer
Int16 - signed 16-bit integer
Int32 - signed 32-bit integer
Int64 - signed 64-bit integer
Uint8 - unsigned 8-bit integer
Uint16 - unsigned 16-bit integer
Uint32 - unsigned 32-bit integer

Byte Order of Binary Data

Use the function that follows to configure the order of the bytes (little endian or big endian) of the binary data that you read or write with a socket. By default, data that you read or write with a socket uses the little endian byte order.

function SocketSetDataByteOrder($socket as handle, $byteOrder as SocketByteOrder)

Configures the byte order to use when reading data or writing data on the specified socket.

Arguments

$socket The socket on which to configure the byte order of the data. Must be a TCP client socket.

$byteOrder The byte order to configure for the data of the socket.

Refer to the SocketByteOrder enumeration that follows.

enum SocketByteOrder
LittleEndian = 0
BigEndian = 1
end

Reading Binary Data

Use the functions that follow to read binary data from a socket.

function SocketReadFloat32($socket as handle) as real

Reads the next 4 bytes interpreted as a 32-bit floating-point value from the specified socket, blocking until the required bytes are available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

Returns

The 32-bit floating-point value.

function SocketReadFloat64($socket as handle) as real

Reads the next 8 bytes interpreted as a 64-bit floating-point value from the specified socket, blocking until the required bytes are available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

Returns

The 64-bit floating-point value.

function SocketReadInt8($socket as handle) as integer

Reads the next byte interpreted as an 8-bit signed integer from the specified socket, blocking until the required bytes are available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

Returns

The 8-bit signed integer value.

function SocketReadInt16($socket as handle) as integer

Reads the next 2 bytes interpreted as a 16-bit signed integer from the specified socket, blocking until the required bytes are available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

Returns

The 16-bit signed integer value.

function SocketReadInt32($socket as handle) as integer

Reads the next 4 bytes interpreted as a 32-bit signed integer from the specified socket, blocking until the required bytes are available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

Returns

The 32-bit signed integer value.

function SocketReadInt64($socket as handle) as integer

Reads the next 8 bytes interpreted as a 64-bit signed integer from the specified socket, blocking until the required bytes are available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

Returns

The 64-bit signed integer value.

function SocketReadUInt8($socket as handle) as integer

Reads the next byte interpreted as an 8-bit unsigned integer from the specified socket, blocking until the required bytes are available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

Returns

The 8-bit unsigned integer value.

function SocketReadUInt16($socket as handle) as integer

Reads the next 2 bytes interpreted as an 16-bit unsigned integer from the specified socket, blocking until the required bytes are available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

Returns

The 16-bit unsigned integer value.

function SocketReadUInt32($socket as handle) as integer

Reads the next 4 bytes interpreted as an 32-bit unsigned integer from the specified socket, blocking until the required bytes are available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

Returns

The 32-bit unsigned integer value.

function SocketReadFloat32Array($socket as handle, ref $values[] as real, $numElements as integer)

Reads the specified number of 32-bit floating-point values from the specified socket into the provided array, blocking until the required bytes are available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

ref $values The array into which values will be read.

$numElements The number of values to read from the socket.

function SocketReadFloat64Array($socket as handle, ref $values[] as real, $numElements as integer)

Reads the specified number of 64-bit floating-point values from the specified socket into the provided array, blocking until the required bytes are available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

ref $values The array into which values will be read.

$numElements The number of values to read from the socket.

function SocketReadInt8Array($socket as handle, ref $values[] as integer, $numElements as integer)

Reads the specified number of 8-bit signed integers from the specified socket into the provided array, blocking until the required bytes are available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

ref $values The array into which values will be read.

$numElements The number of values to read from the socket.

function SocketReadInt16Array($socket as handle, ref $values[] as integer, $numElements as integer)

Reads the specified number of 16-bit signed integers from the specified socket into the provided array, blocking until the required bytes are available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

ref $values The array into which values will be read.

$numElements The number of values to read from the socket.

function SocketReadInt32Array($socket as handle, ref $values[] as integer, $numElements as integer)

Reads the specified number of 32-bit signed integers from the specified socket into the provided array, blocking until the required bytes are available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

ref $values The array into which values will be read.

$numElements The number of values to read from the socket.

function SocketReadInt64Array($socket as handle, ref $values[] as integer, $numElements as integer)

Reads the specified number of 64-bit signed integers from the specified socket into the provided array, blocking until the required bytes are available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

ref $values The array into which values will be read.

$numElements The number of values to read from the socket.

function SocketReadUInt8Array($socket as handle, ref $values[] as integer, $numElements as integer)

Reads the specified number of 8-bit unsigned integers from the specified socket into the provided array, blocking until the required bytes are available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

ref $values The array into which values will be read.

$numElements The number of values to read from the socket.

function SocketReadUInt16Array($socket as handle, ref $values[] as integer, $numElements as integer)

Reads the specified number of 16-bit unsigned integers from the specified socket into the provided array, blocking until the required bytes are available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

ref $values The array into which values will be read.

$numElements The number of values to read from the socket.

function SocketReadUInt32Array($socket as handle, ref $values[] as integer, $numElements as integer)

Reads the specified number of 32-bit unsigned integers from the specified socket into the provided array, blocking until the required bytes are available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

ref $values The array into which values will be read.

$numElements The number of values to read from the socket.

To determine if the floating-point values returned by some of these functions are valid, specify the values to the RealIsInfinity() or the RealIsNan() functions.

Writing Binary Data

Use the functions that follow to write binary data to a socket.

function SocketWriteFloat32($socket as handle, $value as real)

Converts the specified value to its 32-bit floating-point binary representation and writes it to the specified socket, blocking until the required buffer space is available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

$value The value to write to the socket.

function SocketWriteFloat64($socket as handle, $value as real)

Converts the specified value to its 64-bit floating-point binary representation and writes it to the specified socket, blocking until the required buffer space is available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

$value The value to write to the socket.

function SocketWriteInt8($socket as handle, $value as integer)

Converts the specified value to its 8-bit signed integer binary representation and writes it to the specified socket, blocking until the required buffer space is available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

$value The value to write to the socket.

function SocketWriteInt16($socket as handle, $value as integer)

Converts the specified value to its 16-bit signed integer binary representation and writes it to the specified socket, blocking until the required buffer space is available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

$value The value to write to the socket.

function SocketWriteInt32($socket as handle, $value as integer)

Converts the specified value to its 32-bit signed integer binary representation and writes it to the specified socket, blocking until the required buffer space is available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

$value The value to write to the socket.

function SocketWriteInt64($socket as handle, $value as integer)

Converts the specified value to its 64-bit signed integer binary representation and writes it to the specified socket, blocking until the required buffer space is available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

$value The value to write to the socket.

function SocketWriteUInt8($socket as handle, $value as integer)

Converts the specified value to its 8-bit unsigned integer binary representation and writes it to the specified socket, blocking until the required buffer space is available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

$value The value to write to the socket.

function SocketWriteUInt16($socket as handle, $value as integer)

Converts the specified value to its 16-bit unsigned integer binary representation and writes it to the specified socket, blocking until the required buffer space is available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

$value The value to write to the socket.

function SocketWriteUInt32($socket as handle, $value as integer)

Converts the specified value to its 32-bit unsigned integer binary representation and writes it to the specified socket, blocking until the required buffer space is available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

$value The value to write to the socket.

function SocketWriteFloat32Array($socket as handle, $values[] as real, $numElements as integer)

Converts the specified array of values to an array of 32-bit floating-point values in binary representation and writes it to the specified socket, blocking until the required buffer space is available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

$values The values to write to the socket.

$numElements The number of values to write to the socket.

function SocketWriteFloat64Array($socket as handle, $values[] as real, $numElements as integer)

Converts the specified array of values to an array of 64-bit floating-point values in binary representation and writes it to the specified socket, blocking until the required buffer space is available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

$values The values to write to the socket.

$numElements The number of values to write to the socket.

function SocketWriteInt8Array($socket as handle, $values[] as integer, $numElements as integer)

Converts the specified array of values to an array of 8-bit signed integer values in binary representation and writes it to the specified socket, blocking until the required buffer space is available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

$values The values to write to the socket.

$numElements The number of values to write to the socket.

function SocketWriteInt16Array($socket as handle, $values[] as integer, $numElements as integer)

Converts the specified array of values to an array of 16-bit signed integer values in binary representation and writes it to the specified socket, blocking until the required buffer space is available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

$values The values to write to the socket.

$numElements The number of values to write to the socket.

function SocketWriteInt32Array($socket as handle, $values[] as integer, $numElements as integer)

Converts the specified array of values to an array of 32-bit signed integer values in binary representation and writes it to the specified socket, blocking until the required buffer space is available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

$values The values to write to the socket.

$numElements The number of values to write to the socket.

function SocketWriteInt64Array($socket as handle, $values[] as integer, $numElements as integer)

Converts the specified array of values to an array of 64-bit signed integer values in binary representation and writes it to the specified socket, blocking until the required buffer space is available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

$values The values to write to the socket.

$numElements The number of values to write to the socket.

function SocketWriteUInt8Array($socket as handle, $values[] as integer, $numElements as integer)

Converts the specified array of values to an array of 8-bit unsigned integer values in binary representation and writes it to the specified socket, blocking until the required buffer space is available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

$values The values to write to the socket.

$numElements The number of values to write to the socket.

function SocketWriteUInt16Array($socket as handle, $values[] as integer, $numElements as integer)

Converts the specified array of values to an array of 16-bit unsigned integer values in binary representation and writes it to the specified socket, blocking until the required buffer space is available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

$values The values to write to the socket.

$numElements The number of values to write to the socket.

function SocketWriteUInt32Array($socket as handle, $values[] as integer, $numElements as integer)

Converts the specified array of values to an array of 32-bit unsigned integer values in binary representation and writes it to the specified socket, blocking until the required buffer space is available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

$values The values to write to the socket.

$numElements The number of values to write to the socket.

To see an example program that sends an array of values, go to Sockets Array.

Strings

Reading Strings

Use the functions that follow to read UTF-8 strings from a socket. To determine if the strings returned by these functions are valid, specify the strings to the StringIsValid() function.

function SocketReadString($socket as handle) as string

Reads a UTF-8 string from the specified socket, blocking until a null terminator is found.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

Returns

The UTF-8 string. This string will not contain the null terminator.

function SocketReadString($socket as handle, $delimiter as string) as string

Reads a UTF-8 string from the specified socket, blocking until the delimiter is found.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

$delimiter The delimiter used to identify where to stop reading.

Returns

The UTF-8 string. This string will not contain the specified delimiter.

IMPORTANT: When you specify a delimiter to the SocketReadString($socket as handle, $delimiter as string) function, you cannot use an empty delimiter or a delimiter that includes the null-terminator. If you want to use the null-terminator as the delimiter, use the SocketReadString($socket as handle) function overload above.

function SocketReadString($socket as handle, $numBytes as integer) as string

Reads a UTF-8 string of specified length from the specified socket, blocking until the required bytes are available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

$numBytes The length of the resulting string in bytes.

Returns

The UTF-8 string.

Program Example

// Server.ascript
#define SERVER_PORT 8080

var $serverSocket as handle
var $clientSocket as handle

// Open the port for listening.
$serverSocket = SocketTcpServerCreate(SERVER_PORT)

// Accept a client connection to read from.
$clientSocket = SocketTcpServerAccept($serverSocket)
		
// While connected to the client, keep reading strings.
while SocketTcpClientIsConnected($clientSocket)
    // Check to see if there are any bytes to read.
    if SocketGetReadBytesAvailable($clientSocket) > 0
        // Read a string up to the next space character.
        var $substring as string = SocketReadString($clientSocket, " ")
				
        // Check to see if the string is valid.
        if StringIsValid($substring)
            AppMessageDisplay($substring)
        end
    end
end
		
// Close the connection to the client and the server socket.
SocketClose($clientSocket)
SocketClose($serverSocket)

// Client.ascript
#define SERVER_PORT 8080
				
var $clientSocket as handle

// Create a client connection to the server.
$clientSocket = SocketTcpClientCreate("localhost", SERVER_PORT, 10000)
	
// Send a string with delimiters to be parsed on the server.
// Note that the extra space is needed if we want the last substring to be processed.
SocketWriteString($clientSocket, "hello world goodbye world ")
			
// Close the socket connection.
SocketClose($clientSocket)

Writing Strings

Use the function that follows to write a UTF-8 string to a socket. This function does not write a null terminating character. To write a null terminating character, specify 0 for the $value argument of the SocketWriteUInt8() function.

function SocketWriteString($socket as handle, $value as string)

Writes the specified string to the specified socket, blocking until the required buffer space is available.

Arguments

$socket A handle that represents an open socket. Must be a TCP client socket.

$value The UTF-8 string to write to the socket.

Program Example

var $clientSocket as handle

// Create a client connection to the server.
$clientSocket = SocketTcpClientCreate("localhost", 8080, 10000)
	
// Write a string then append the null terminating character.
SocketWriteString($clientSocket, "Hello World!")
SocketWriteUInt8($clientSocket, 0)
			
// Close the socket connection.
SocketClose($clientSocket)

To see an example program that sends an processes a JSON string, go to Sockets String.

Firewall Settings for PC-Based Controllers

If there is an active firewall on the host PC of a PC-based controller, the firewall could block the Socket functions from communicating with client sockets on the network. If you are using a PC-based controller as a socket server, you must configure firewall exceptions before using Socket functions. To configure firewall exceptions for inbound connections, use the steps that follow.

Open the Start menu. Do a search for Windows Defender Firewall, and open it.
Select Advanced settings. Then select Inbound Rules and click on New Rule in the Actions panel. This opens the New Inbound Rule Wizard.
Select Program, and click Next.
Select This Program Path. Click Browse, and navigate to C:\Program Files\Aerotech\Automation1-iSMC\Bin and select Automation1.Services.Callback.exe. Click Next.
Select Allow the connection, and click Next.
Select which connection types that the remote connection is permitted on. Click Next.
Enter a name for the rule. Click Finish.

IMPORTANT: Outbound connections do not usually require firewall exceptions. If you have connection problems after doing the steps above, repeat the steps for outbound connections by selecting Outbound Rules and then New Rule in Step 2.