API Documentation

Socket

The Socket API allows users to configure and connect directly to an Ethernet socket in order to read and write packets of data.

Synchronous IO operations, such as polling-timeouts or multiplexing, can be achieved through the use of the standard select() system call mechanisms performed on the ps_socket.fd file descriptor.

Usage #include <polysync_socket.h>

Macros

PSYNC_SOCKET_FD_INVALID

Value Type Description
-1 int Represents an invalid ps_socket.fd file descriptor.

PSYNC_SOCKET_PORT_ANY

Value Type Description
0 int Specifies that the Operating System should pick the appropriate socket port number.

PSYNC_SOCKET_ADDRESS_ANY

Value Type Description
NULL void * Specifies that that any address is acceptable for the socket.

Functions

psync_socket_bind ( … )

This will bind a socket to its address.

The ps_socket address data is used in the assignment.

Parameters
in/out type name description
in ps_socket *const sock A pointer to ps_socket that receives the configuration.
Returns
  • DTC code:
    • DTC_NONE - (Zero) if success
    • DTC_USAGE - If argument is invalid
    • DTC_CONFIG - If socket is invalid or configuration is not supported
    • DTC_INTR - If bind call was interrupted by the system
    • DTC_INPROGRESS - If socket is set to non-blocking IO and operation would block

Diagnostic trouble code reference

psync_socket_bind_by_name ( … )

This will bind a socket to a symbolic name.

psync_socket_bind_by_name will bind this socket to a symbolic device name like “eth0,” instead of using psync_socket_bind to bind it to an internal address.

Parameters
in/out type name description
in ps_socket *const sock A pointer to ps_socket that receives the configuration.
in const char *const name A pointer to a char buffer that specifies the device name value.
in const size_t name_len The length of the provided name.
Returns
  • DTC code:

Diagnostic trouble code reference

psync_socket_connect ( … )

This will connect a socket to its address.

The socket’s address data is used to initiate a connection.

Parameters
in/out type name description
in ps_socket *const sock A pointer to ps_socket that receives the configuration.
Returns
  • DTC code:
    • DTC_NONE - (Zero) if success
    • DTC_USAGE - If argument is invalid
    • DTC_CONFIG - If socket is invalid or configuration is not supported
    • DTC_INTR - If connect call was interrupted by the system
    • DTC_INPROGRESS - If socket is set to non-blocking IO and operation would block

Diagnostic trouble code reference

psync_socket_init ( … )

This will initialize a socket endpoint for communications.

psync_socket_init will establish an endpoint for communications using the PolySync time domain.

Parameters
in/out type name description
in ps_socket *const sock A pointer to ps_socket that receives the configuration.
in const int domain Communications domain. See ps_socket::domain for details.
in const int type Communications type. See ps_socket::type for details.
in const int protocol Communications protocol. See ps_socket::protocol for details.
Returns
  • DTC code:

Diagnostic trouble code reference

psync_socket_recv ( … )

This will receive data from a socket connection.

Parameters
in/out type name description
in const ps_socket *const sock A pointer to ps_socket that holds the configuration.
out unsigned char *const buffer A pointer to an unsigned char buffer that receives the data read.
in const size_t buffer_len The length of a provided buffer.
out unsigned long *const bytes_read A pointer to an unsigned long that receives the count value.
out ps_timestamp *const timestamp A pointer to ps_timestamp that receives the receive timestamp value.
Returns

Diagnostic trouble code reference

psync_socket_recv_from ( … )

This will receive data from a connection or connection-less socket.

psync_socket_recv_from will use the internal source address to receive data. The address can be configured with psync_socket_set_address prior to using this call.

Parameters
in/out type name description
in const ps_socket *const sock A pointer to ps_socket that holds the configuration.
out unsigned char *const buffer A pointer to an unsigned char buffer that receives the data read.
in const size_t buffer_len The length of a provided buffer.
out unsigned long *const bytes_read A pointer to an unsigned long that receives the count value.
out ps_timestamp *const timestamp A pointer to ps_timestamp that receives the receive timestamp value.
Returns

Diagnostic trouble code reference

psync_socket_release ( … )

This will release a socket.

psync_socket_release will close a communications endpoint.

Parameters
in/out type name description
in ps_socket *const sock A pointer to ps_socket that gets released.
Returns

Diagnostic trouble code reference

psync_socket_send ( … )

This will send data on a socket connection.

Parameters
in/out type name description
in const ps_socket *const sock A pointer to ps_socket that holds the configuration.
in unsigned char *const buffer A pointer to an unsigned char buffer that specifies the data to be sent.
in const size_t buffer_len Length of a provided buffer.
out unsigned long *const bytes_sent A pointer to an unsigned long that receives the count value.
Returns

Diagnostic trouble code reference

psync_socket_send_to ( … )

This will send data on a connection-mode socket.

psync_socket_send_to will use the internal source address to send data. The address can be configured with psync_socket_set_address prior to using this call.

Parameters
in/out type name description
in ps_socket *const sock A pointer to ps_socket that holds the configuration.
in unsigned char *const buffer A pointer to an unsigned char buffer that specifies the data to be sent.
in const size_t buffer_len The length of a provided buffer.
out unsigned long *const bytes_sent A pointer to an unsigned long that receives the count value.
Returns

Diagnostic trouble code reference

psync_socket_set_address ( … )

This will set a socket’s address data.

The address data is used to specify the source address.

Parameters
in/out type name description
in ps_socket *const sock A pointer to ps_socket that receives the configuration.
in const char *const address A pointer to char buffer that specifies the address to use. Value PSYNC_SOCKET_ADDRESS_ANY is allowed.
in const unsigned long port Port number associated with the address. Value PSYNC_SOCKET_PORT_ANY is allowed.
Returns

Diagnostic trouble code reference

psync_socket_set_broadcast_option ( … )

This will set socket broadcast options.

This allows UDP datagram (SOCK_DGRAM) sockets to send and receive packets sent to and from the broadcast address.

Parameters
in/out type name description
in ps_socket *const sock A pointer to ps_socket that receives the configuration.
in const unsigned int enabled If it is not zero, then it enables the option. Otherwise, the option is disabled.
Returns
  • DTC code:

Diagnostic trouble code reference

psync_socket_set_nonblock_option ( … )

This will set a socket non-blocking option.

Parameters
in/out type name description
in ps_socket *const sock A pointer to ps_socket that receives the configuration.
in const unsigned int enabled If it is not zero, then it enables the option. Otherwise, the option is disabled.
Returns
  • DTC code:

Diagnostic trouble code reference

psync_socket_set_reuse_option ( … )

This will set a socket reuse address option.

psync_socket_set_reuse_option will allow other sockets to bind to this port, unless there is an active listening socket bound to the port already.

Parameters
in/out type name description
in ps_socket *const sock A pointer to ps_socket that receives the configuration.
in const unsigned int enabled If it is not zero, it enables the option. Otherwise, the option is disabled.
Returns

Diagnostic trouble code reference

psync_socket_set_rxtimeout_option ( … )

This will set a socket receive timeout option.

This sets the maximum amount of time a read operation is allowed to use.

Parameters
in/out type name description
in ps_socket *const sock A pointer to ps_socket that receives the configuration.
in const ps_timestamp timeout The timeout value to use. If it is zero, then it disables the option. [microseconds]
Returns
  • DTC code:

Diagnostic trouble code reference

psync_socket_set_txtimeout_option ( … )

This will set a socket transmit timeout option.

This sets the maximum amount of time a send operation is allowed to use.

Parameters
in/out type name description
in ps_socket *const sock A pointer to ps_socket that receives the configuration.
in const ps_timestamp timeout The timeout value to use. If it is zero, then it disables the option. [microseconds]
Returns
  • DTC code:

Diagnostic trouble code reference

Typedefs

ps_socket

The PolySync Ethernet socket structure.

typedef struct
{
    //
    //
    int                     fd; // The file descriptor. The value [PSYNC_SOCKET_FD_INVALID](/api-docs/c/socket/#functions) represents an invalid socket.
    //
    //
    int                     domain; // The communications domain. In Linux the standard socket domains i.e. AF_INET, AF_INET6, etc. are allowed.
    //
    //
    int                     type; // The communications type. In Linux standard types i.e. SOCK_STREAM, SOCK_DGRAM, etc. are allowed.
    //
    //
    int                     protocol; // The communications protocol to use. In Linux standard protocols i.e. IPPROTO_UDP, IPPROTO_TCP, etc. are allowed.
    //
    //
    struct sockaddr_in      address; // Socket address, used to store the source address for the socket.
} ps_socket;