API Documentation

Socket

The PolySync Socket API is a wrapper around a network socket. It is used for network based communication.

Usage #include <PolySyncSocket.hpp>

Socket

The Socket class is intended for performing network communication. The user can access other devices, including both other hosts and sensors, that are available via a network communication protocol. In general, this implies an ethernet connection.

Socket::Socket ( … )

The Socket class constructor will establish an endpoint for network communication based on the PolySync time domain. It will initialize the Socket object based on domain, type, and protocol to be used.

Parameters
in/out type name description
in int domain The communication domain. See ps_socket.domain for details.
in int type The communications type. See ps_socket.type for details.
in int protocol The communications protocol. See ps_socket.protocol for details.
Exceptions
  • Throws PolySync::DTCException on failure:
    • DTC_USAGE - If there is an invalid argument
    • DTC_CONFIG - If device has already been initialized, but is now invalid

Socket::~Socket ( )

The Socket destructor will break down an endpoint by calling the Socket::release () function.

Socket::release ( )

This will release a socket and close a communications endpoint.

Exceptions
  • Throws PolySync::DTCException on failure:
    • DTC_USAGE - If there is an invalid argument

Socket::setAddress ( … )

This will set the internal address for this socket’s address data.

The address data is used to specify the source address for use with the receiveFrom and sendTo functions.

Parameters
in/out type name description
in const std::vector< char > & address The vector reference containing the address to use. Value PSYNC_SOCKET_ADDRESS_ANY is allowed.
in ulong port The port number associated with the address. Value PSYNC_SOCKET_PORT_ANY is allowed.
Exceptions
  • Throws PolySync::DTCException on failure:
    • DTC_USAGE - If there is an invalid argument

Socket::setBroadCast ( … )

This will set the socket broadcast option.

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

Parameters
in/out type name description
in uint enabled If not zero, it enables the option. Otherwise, the option is disabled.
Exceptions
  • Throws PolySync::DTCException on failure:
    • DTC_USAGE - If there is an invalid argument
    • DTC_CONFIG - If the socket is invalid, or otherwise failed to set the option

Socket::setReuse ( … )

This will set the socket reuse address option.

Enabling this option will allow other sockets to bind to this port. Unless there is already an active listening socket bound to the port.

Parameters
in/out type name description
in uint enabled If not zero, it enables the option. Otherwise, the option is disabled.
Exceptions
  • Throws PolySync::DTCException on failure:
    • DTC_USAGE - If there is an invalid argument
    • DTC_CONFIG - If the socket is invalid, or otherwise failed to set the option

Socket::setNonBlock ( … )

This will set the socket to blocking or non-blocking mode.

Setting this option indicates that the send and receive functions will work in synchronous or asynchronous mode. Enabling the non-blocking option puts the Socket into an asynchronous mode, where the send and receive functions return with only the data that may be available.

Parameters
in/out type name description
in uint enabled If not zero, it enables the option. Otherwise, the option is disabled.
Exceptions
  • Throws PolySync::DTCException on failure:
    • DTC_USAGE - If there is an invalid argument
    • DTC_CONFIG - If the socket is invalid, or otherwise failed to set the option

Socket::setRxTimeout ( … )

This will set the maximum amount of time a read operation is allowed to be in use when in blocking mode.

Parameters
in/out type name description
in ps_timestamp timeout Timeout value to use. Zero disables this option. [microseconds]
Exceptions
  • Throws PolySync::DTCException on failure:
    • DTC_USAGE - If there is an invalid argument
    • DTC_CONFIG - If the socket is invalid, or otherwise failed to set the option

Socket::setTxTimeout ( … )

This will set the maximum amount of time a send operation is allowed to use when in blocking mode.

Parameters
in/out type name description
in ps_timestamp timeout Timeout value to use. Zero disables this option. [microseconds]
Exceptions
  • Throws PolySync::DTCException on failure:
    • DTC_USAGE - If there is an invalid argument
    • DTC_CONFIG - If the socket is invalid, or otherwise failed to set the option

Socket::bindByName ( … )

This will bind to a socket based on a symbolic name.

This function will bind a socket to a symbolic device name like “eth0,” instead of using the bind () function exposed in this class. The bind operation substitutes the given name for an internal address.

Parameters
in/out type name description
in const std::string & name A const string reference that specifies the device name value.
Exceptions
  • Throws PolySync::DTCException on failure:
    • DTC_USAGE - If there is an invalid argument
    • DTC_CONFIG - If the socket is invalid, or otherwise failed to set the option

Socket::bind ( )

This will bind a socket to its address.

The socket’s internal address data will be used in the assignment of this Socket class to a specific socket as exposed by the OS.

Exceptions
  • Throws PolySync::DTCException on failure:
    • DTC_USAGE - If there is an invalid argument
    • DTC_CONFIG - If the socket is invalid, failed to flow control, or failed to bind
    • DTC_INTR - If the bind process received an error interrupt
    • DTC_INPROGRESS - If the bind process is still in progress

Socket::connect ( )

This will initiate a connection using the network address data associated with the Socket class.

Exceptions
  • Throws PolySync::DTCException on failure:
    • DTC_USAGE - If there is an invalid argument
    • DTC_CONFIG - If the socket is invalid, failed to flow control, or failed to connect
    • DTC_INTR - If the connect process received an error interrupt
    • DTC_INPROGRESS - If the connect process is still in progress

Socket::receive ( … )

This will receive data from a socket connection.

This function is normally a blocking call that waits for a buffer to fill with data from the network. The size of the buffer defaults to 1024 bytes. The function will return immediately if the non-blocking option is enabled, but will also return after the receive timeout expires.

Parameters
in/out type name description
out std::vector< uchar > & buffer A reference to a vector to receive the data.
out ps_timestamp & timestamp A reference to the ps_timestamp that receives the receive timestamp value.
Returns
  • ulong - The number of bytes received
Exceptions
  • Throws PolySync::DTCException on failure:
    • DTC_USAGE - If there is an invalid argument
    • DTC_CONFIG - If the socket is invalid or failed to receive
    • DTC_INTR - If the receive process received an error interrupt
    • DTC_UNAVAILABLE - If the receive process is unavailable because it is already in process or would block

Socket::receiveFrom ( … )

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

It will use the internal source address to receive data. The address can be configured with setAddress prior to using this call. This function is specifically useful for network communication using UDP, which is a connectionless protocol.

This function is normally a blocking call that waits for a buffer to fill with data from the network. The size of the buffer defaults to 1024 bytes. The function returns immediately if the non-blocking option is enabled, but will also return after the receive timeout expires.

Parameters
in/out type name description
out std::vector< uchar > & buffer A reference to a vector to receive the data.
out ps_timestamp & timestamp A reference to the ps_timestamp that receives the receive timestamp value.
Returns
  • ulong return - The number of bytes received
Exceptions
  • Throws PolySync::DTCException on failure:
    • DTC_USAGE - If there is an invalid argument
    • DTC_CONFIG - If the socket is invalid or failed to receive
    • DTC_INTR - If the receive process received an error interrupt
    • DTC_UNAVAILABLE - If the receive process is unavailable because it is already in process or would block

Socket::send ( … )

This will send a buffer of data over a network connection. The size of the data is indicated by the size of the data in the vector.

This function is normally a blocking call that waits for the entire buffer to be sent before returning. The function returns immediately if the non-blocking option is enabled, but will also return after the transmit timeout expires.

Parameters
in/out type name description
in std::vector< uchar > & buffer A vector reference containing the data to send.
Returns
  • ulong - The number of bytes sent
Exceptions
  • Throws PolySync::DTCException on failure:
    • DTC_USAGE - If there is an invalid argument
    • DTC_CONFIG - If the socket is invalid or failed to send
    • DTC_INTR - If the receive process received an error interrupt
    • DTC_UNAVAILABLE - If the receive process is unavailable because it is already in process or would block

Socket::sendTo ( … )

This will send a buffer of data over a network connection.

The size of the data is indicated by the size of the data in the vector. Specifically, the function will use the internal source address, which can be set prior to this call using the setAddress () function, to send the buffer. It is useful for connectionless protocols, such as UDP.

This function is normally a blocking call that waits for the entire buffer to be sent before returning. The function returns immediately if the non-blocking option is enabled, but will also return after the transmit timeout expires.

Parameters
in/out type name description
in std::vector< [uchar] > & buffer A vector reference containing the data to send.
Returns
  • ulong return - The number of bytes sent
Exceptions
  • Throws PolySync::DTCException on failure:
    • DTC_USAGE - If there is an invalid argument
    • DTC_CONFIG - If the socket is invalid or failed to send
    • DTC_INTR - If the receive process received an error interrupt
    • DTC_UNAVAILABLE - If the receive process is unavailable because it is already in process or would block