S2OPC OPCUA Toolkit
Functions
sopc_raw_sockets.h File Reference

A platform independent API to use sockets. More...

#include <stdbool.h>
#include <stdint.h>
#include "sopc_enums.h"
#include "p_sopc_sockets.h"

Go to the source code of this file.

Functions

SOPC_ReturnStatus SOPC_Socket_Network_Enable_Keepalive (Socket sock, unsigned int firstProbeDelay, unsigned int interval, unsigned int counter)
 Activate the keep alive mechanism. According to RFC1122, this mechanism shall be used with care: deactivated by default, ability to enable or disable it run time for each connection at runtime. More...
 
SOPC_ReturnStatus SOPC_Socket_Network_Disable_Keepalive (Socket sock)
 Deactivate the keep alive mechanism. More...
 
bool SOPC_Socket_Network_Initialize (void)
 Initialize the network communication allowing to use sockets. More...
 
bool SOPC_Socket_Network_Clear (void)
 Clear the network communication when sockets not used anymore. More...
 
SOPC_ReturnStatus SOPC_Socket_AddrInfo_Get (char *hostname, char *port, SOPC_Socket_AddressInfo **addrs)
 Provide a linked list of socket addressing information for establishing TCP connections over IPV4 and IPV6 using the hostname and/or port if provided. More...
 
SOPC_Socket_AddressInfoSOPC_Socket_AddrInfo_IterNext (SOPC_Socket_AddressInfo *addr)
 Given a socket addressing information element of a linked list, provides the next addressing information or NULL if no more are available. More...
 
uint8_t SOPC_Socket_AddrInfo_IsIPV6 (const SOPC_Socket_AddressInfo *addr)
 Given a socket addressing information element, returns 0 if address is not IPV6 and not 0 value otherwise. More...
 
void SOPC_Socket_AddrInfoDelete (SOPC_Socket_AddressInfo **addrs)
 Deallocate a linked list of socket addressing information. More...
 
SOPC_Socket_AddressSOPC_Socket_GetPeerAddress (Socket sock)
 Given a socket get the address information associated to the peer connected to the socket. More...
 
SOPC_Socket_AddressSOPC_Socket_CopyAddress (SOPC_Socket_AddressInfo *addr)
 Copy the socket address from a socket address information. More...
 
SOPC_ReturnStatus SOPC_SocketAddress_GetNameInfo (const SOPC_Socket_Address *addr, char **host, char **service)
 Get address information as C strings from the given socket address. More...
 
void SOPC_SocketAddress_Delete (SOPC_Socket_Address **addr)
 Deallocate a socket address obtained with SOPC_Socket_GetPeerAddress or SOPC_Socket_CopyAddress. More...
 
void SOPC_Socket_Clear (Socket *sock)
 Clear socket state to an invalid socket. More...
 
SOPC_ReturnStatus SOPC_Socket_CreateNew (SOPC_Socket_AddressInfo *addr, bool setReuseAddr, bool setNonBlocking, Socket *sock)
 Create a new socket using the addressing information provided. More...
 
SOPC_ReturnStatus SOPC_Socket_Listen (Socket sock, SOPC_Socket_AddressInfo *addr)
 Configure the socket to listen connections using the given addressing information Connection on a listening socket is detected when receiving a read event on the socket. More...
 
SOPC_ReturnStatus SOPC_Socket_Accept (Socket listeningSock, bool setNonBlocking, Socket *acceptedSock)
 Operation to accept a connection on a listening socket Connection on a listening socket is detected when receiving a read event on the socket. More...
 
SOPC_ReturnStatus SOPC_Socket_Connect (Socket sock, SOPC_Socket_AddressInfo *addr)
 Operation to establish a connection using the given socket and addressing information Connection establishment result must be detected when receiving a read event on the socket and then by calling the SOPC_Socket_CheckAckConnect operation. More...
 
SOPC_ReturnStatus SOPC_Socket_ConnectToLocal (Socket from, Socket to)
 Operation to establish a connection using the given socket to the given local socket. Both sockets shall have been created with same addressing information protocol. The address to connected to is extracted from the target socket. More...
 
SOPC_ReturnStatus SOPC_Socket_CheckAckConnect (Socket sock)
 Operation to check connection establishment result on a connecting socket After using SOPC_Socket_Connect on a socket and receiving a write event on the socket this operation returns the failure or success of the connection. More...
 
void SOPC_SocketSet_Add (Socket sock, SOPC_SocketSet *sockSet)
 Add a socket to the given socket set. More...
 
bool SOPC_SocketSet_IsPresent (Socket sock, SOPC_SocketSet *sockSet)
 Returns if a socket is present in the given socket set. More...
 
void SOPC_SocketSet_Clear (SOPC_SocketSet *sockSet)
 Clear a socket set. More...
 
int32_t SOPC_Socket_WaitSocketEvents (SOPC_SocketSet *readSet, SOPC_SocketSet *writeSet, SOPC_SocketSet *exceptSet, uint32_t waitMs)
 Wait for events (read, write and exception) on the sockets in the given sets for a given duration. If events are received on sockets or waiting reached timeout it returns and the socket sets contain only the sockets on which events occurred. More...
 
SOPC_ReturnStatus SOPC_Socket_Write (Socket sock, const uint8_t *data, uint32_t count, uint32_t *sentBytes)
 Write data through the socket. More...
 
SOPC_ReturnStatus SOPC_Socket_Read (Socket sock, uint8_t *data, uint32_t dataSize, uint32_t *readCount)
 Read data through the socket. More...
 
SOPC_ReturnStatus SOPC_Socket_BytesToRead (Socket sock, uint32_t *bytesToRead)
 Retrieve number of bytes available to read on the socket. More...
 
void SOPC_Socket_Close (Socket *sock)
 Close the socket connection and/or clear the socket. More...
 

Detailed Description

A platform independent API to use sockets.

Function Documentation

◆ SOPC_Socket_Network_Enable_Keepalive()

SOPC_ReturnStatus SOPC_Socket_Network_Enable_Keepalive ( Socket  sock,
unsigned int  firstProbeDelay,
unsigned int  interval,
unsigned int  counter 
)

Activate the keep alive mechanism. According to RFC1122, this mechanism shall be used with care: deactivated by default, ability to enable or disable it run time for each connection at runtime.

The platform-specific implementation of "p_sockets.h" shall provide the actual definition of:

  • Socket type (e.g. int for LINUX)
  • SOPC_Socket_AddressInfo for Network Address definition structure (e.g. struct addrinfo for LINUX)
  • SOPC_Socket_Address for Socket Address definition structure (e.g. struct addrinfo for LINUX)
  • SOPC_SocketSet type for socket sets (e.g. fd_set for LINUX)
    Parameters
    sockThe socket to activate keep alive probes
    firstProbeDelayThe time (in seconds) the connection needs to remain idle before TCP starts sendingkeepalive probes
    intervalThe time (in seconds) between individual keepalive probes
    counterThe maximum number of keepalive probes TCP should send before dropping the connection
    Returns
    SOPC_STATUS_OK if operation succeeded, SOPC_INVALID_PARAMETERS if parameters are not valid SOPC_STATUS_NOK otherwise.

◆ SOPC_Socket_Network_Disable_Keepalive()

SOPC_ReturnStatus SOPC_Socket_Network_Disable_Keepalive ( Socket  sock)

Deactivate the keep alive mechanism.

Parameters
sockThe socket to activate keep alive probes
Returns
SOPC_STATUS_OK if operation succeeded, SOPC_INVALID_PARAMETERS if parameters are not valid SOPC_STATUS_NOK otherwise.

◆ SOPC_Socket_Network_Initialize()

bool SOPC_Socket_Network_Initialize ( void  )

Initialize the network communication allowing to use sockets.

◆ SOPC_Socket_Network_Clear()

bool SOPC_Socket_Network_Clear ( void  )

Clear the network communication when sockets not used anymore.

◆ SOPC_Socket_AddrInfo_Get()

SOPC_ReturnStatus SOPC_Socket_AddrInfo_Get ( char *  hostname,
char *  port,
SOPC_Socket_AddressInfo **  addrs 
)

Provide a linked list of socket addressing information for establishing TCP connections over IPV4 and IPV6 using the hostname and/or port if provided.

Parameters
hostnameThe hostname of the machine to connect or used to listen (optional for listening)
portThe port number on which to connect or to listen to (optional for listening if hostname set)
addrsThe addressing information to establish or listen a TCP connection over IPV4 and IPV6
Returns
SOPC_STATUS_OK if operation succeeded, SOPC_INVALID_PARAMETERS if parameters are not valid SOPC_STATUS_NOK otherwise.

◆ SOPC_Socket_AddrInfo_IterNext()

SOPC_Socket_AddressInfo* SOPC_Socket_AddrInfo_IterNext ( SOPC_Socket_AddressInfo addr)

Given a socket addressing information element of a linked list, provides the next addressing information or NULL if no more are available.

Parameters
addrA socket addressing information element
Returns
Next socket addressing information element or NULL if no more are present.

◆ SOPC_Socket_AddrInfo_IsIPV6()

uint8_t SOPC_Socket_AddrInfo_IsIPV6 ( const SOPC_Socket_AddressInfo addr)

Given a socket addressing information element, returns 0 if address is not IPV6 and not 0 value otherwise.

Parameters
addrA socket addressing information element
Returns
0 if address is not IPV6 and not 0 value otherwise.

◆ SOPC_Socket_AddrInfoDelete()

void SOPC_Socket_AddrInfoDelete ( SOPC_Socket_AddressInfo **  addrs)

Deallocate a linked list of socket addressing information.

Parameters
addrs(In/Out) A linked list of socket addressing information to deallocate. Pointer set to NULL after operation.

◆ SOPC_Socket_GetPeerAddress()

SOPC_Socket_Address* SOPC_Socket_GetPeerAddress ( Socket  sock)

Given a socket get the address information associated to the peer connected to the socket.

Parameters
sockThe socket connected to a peer
Returns
The newly allocated peer socket address or NULL in case of error. Caller is responsible to free the result using SOPC_SocketAddress_Delete.

◆ SOPC_Socket_CopyAddress()

SOPC_Socket_Address* SOPC_Socket_CopyAddress ( SOPC_Socket_AddressInfo addr)

Copy the socket address from a socket address information.

Parameters
addrThe socket address information to copy into socket address structure
Returns
The newly allocated socket address created from the addr or NULL in case of failures. Caller is responsible to free the result using SOPC_SocketAddress_Delete.

◆ SOPC_SocketAddress_GetNameInfo()

SOPC_ReturnStatus SOPC_SocketAddress_GetNameInfo ( const SOPC_Socket_Address addr,
char **  host,
char **  service 
)

Get address information as C strings from the given socket address.

Parameters
addrThe socket address to use to get information as C string
[out]host(optional) The host information of the address as C string (i.e. IP)
[out]service(optional) The service information of the address as C string (i.e. port)
Returns
SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS if parameters are invalid (NULL for addr or both NULL for outputs) or SOPC_STATUS_NOK if it failed.

◆ SOPC_SocketAddress_Delete()

void SOPC_SocketAddress_Delete ( SOPC_Socket_Address **  addr)

Deallocate a socket address obtained with SOPC_Socket_GetPeerAddress or SOPC_Socket_CopyAddress.

Parameters
addr(In/Out) An address information to deallocate. Pointer set to NULL after operation.

◆ SOPC_Socket_Clear()

void SOPC_Socket_Clear ( Socket sock)

Clear socket state to an invalid socket.

Parameters
[out]sockValue pointed is set to invalid socket value

◆ SOPC_Socket_CreateNew()

SOPC_ReturnStatus SOPC_Socket_CreateNew ( SOPC_Socket_AddressInfo addr,
bool  setReuseAddr,
bool  setNonBlocking,
Socket sock 
)

Create a new socket using the addressing information provided.

Parameters
addrThe addressing information used to instantiate a TCP/IP socket
setReuseAddrIf value is not false (0) the socket is configured to be reused
setNonBlockingIf value is not false (0) the socket is configured to be non blocking
[out]sockValue pointed is set with the newly created socket
Returns
SOPC_STATUS_OK if operation succeeded, SOPC_INVALID_PARAMETERS if parameters are not valid SOPC_STATUS_NOK otherwise.

◆ SOPC_Socket_Listen()

SOPC_ReturnStatus SOPC_Socket_Listen ( Socket  sock,
SOPC_Socket_AddressInfo addr 
)

Configure the socket to listen connections using the given addressing information Connection on a listening socket is detected when receiving a read event on the socket.

Parameters
sockThe socket used for binding and listening
addrThe addressing information used to bind the socket for listening (IP and port)
Returns
SOPC_STATUS_OK if operation succeeded, SOPC_INVALID_PARAMETERS if parameters are not valid SOPC_STATUS_NOK otherwise.

◆ SOPC_Socket_Accept()

SOPC_ReturnStatus SOPC_Socket_Accept ( Socket  listeningSock,
bool  setNonBlocking,
Socket acceptedSock 
)

Operation to accept a connection on a listening socket Connection on a listening socket is detected when receiving a read event on the socket.

Parameters
listeningSockThe listening socket on which a read event has been received.
setNonBlockingIf value is not false (0) the connection socket is configured to be non blocking
[out]acceptedSockValue pointed is set with the newly created socket for accepted connection
Returns
SOPC_STATUS_OK if operation succeeded, SOPC_INVALID_PARAMETERS if parameters are not valid SOPC_STATUS_NOK otherwise.

◆ SOPC_Socket_Connect()

SOPC_ReturnStatus SOPC_Socket_Connect ( Socket  sock,
SOPC_Socket_AddressInfo addr 
)

Operation to establish a connection using the given socket and addressing information Connection establishment result must be detected when receiving a read event on the socket and then by calling the SOPC_Socket_CheckAckConnect operation.

Parameters
addrThe addressing information used to establish connection (IP and port)
sockThe socket used for establishing the connection
Returns
SOPC_STATUS_OK if operation succeeded, SOPC_INVALID_PARAMETERS if parameters are not valid SOPC_STATUS_NOK otherwise.

◆ SOPC_Socket_ConnectToLocal()

SOPC_ReturnStatus SOPC_Socket_ConnectToLocal ( Socket  from,
Socket  to 
)

Operation to establish a connection using the given socket to the given local socket. Both sockets shall have been created with same addressing information protocol. The address to connected to is extracted from the target socket.

Parameters
fromThe socket used for establishing the connection
toThe socket to connect to
Returns
SOPC_STATUS_OK if operation succeeded, SOPC_INVALID_PARAMETERS if parameters are not valid SOPC_STATUS_NOK otherwise.

◆ SOPC_Socket_CheckAckConnect()

SOPC_ReturnStatus SOPC_Socket_CheckAckConnect ( Socket  sock)

Operation to check connection establishment result on a connecting socket After using SOPC_Socket_Connect on a socket and receiving a write event on the socket this operation returns the failure or success of the connection.

Parameters
sockThe socket on which the first read event has been received after calling SOPC_Socket_Connect operation.
Returns
SOPC_STATUS_OK if operation succeeded, SOPC_INVALID_PARAMETERS if parameters are not valid SOPC_STATUS_NOK otherwise.

◆ SOPC_SocketSet_Add()

void SOPC_SocketSet_Add ( Socket  sock,
SOPC_SocketSet sockSet 
)

Add a socket to the given socket set.

Parameters
sockThe socket to add to the set (not NULL)
sockSetThe socket set to use for the operation (not NULL)

◆ SOPC_SocketSet_IsPresent()

bool SOPC_SocketSet_IsPresent ( Socket  sock,
SOPC_SocketSet sockSet 
)

Returns if a socket is present in the given socket set.

Parameters
sockThe socket to search in the set (not NULL)
sockSetThe socket set to use for the operation (not NULL)
Returns
true (!= false) if present, false otherwise

◆ SOPC_SocketSet_Clear()

void SOPC_SocketSet_Clear ( SOPC_SocketSet sockSet)

Clear a socket set.

Parameters
sockSetThe socket set to use for the operation (not NULL)

◆ SOPC_Socket_WaitSocketEvents()

int32_t SOPC_Socket_WaitSocketEvents ( SOPC_SocketSet readSet,
SOPC_SocketSet writeSet,
SOPC_SocketSet exceptSet,
uint32_t  waitMs 
)

Wait for events (read, write and exception) on the sockets in the given sets for a given duration. If events are received on sockets or waiting reached timeout it returns and the socket sets contain only the sockets on which events occurred.

Parameters
readSet(In/Out) The set of sockets on which read events are awaited and as a result the set of sockets on which event occurred
writeSet(In/Out) The set of sockets on which write events are awaited and as a result the set of sockets on which event occurred
exceptSet(In/Out) The set of sockets on which exception events are awaited and as a result the set of sockets on which event occurred
waitMsThe maximum duration in milliseconds waiting for events (0 means infinite)
Returns
The number of sockets with events contained by sets or -1 if failed

◆ SOPC_Socket_Write()

SOPC_ReturnStatus SOPC_Socket_Write ( Socket  sock,
const uint8_t *  data,
uint32_t  count,
uint32_t *  sentBytes 
)

Write data through the socket.

Parameters
sockThe socket on which data must be written
dataThe data bytes to write on socket
countThe number of bytes to write
sentBytesPointer to the number of bytes sent on socket after call (only significant when SOPC_STATUS_OK returned)
Returns
SOPC_STATUS_OK if bytes were written, SOPC_STATUS_INVALID_PARAMETERS if parameters are not valid, SOPC_STATUS_WOULD_BLOCK if socket write operation would block, SOPC_STATUS_NOK if it failed

◆ SOPC_Socket_Read()

SOPC_ReturnStatus SOPC_Socket_Read ( Socket  sock,
uint8_t *  data,
uint32_t  dataSize,
uint32_t *  readCount 
)

Read data through the socket.

Parameters
sockThe socket on which data must be read
dataThe data bytes to be set with read bytes
dataSizeThe number of bytes that can be set (or expected to be read)
readCountPointer to the number of bytes actually written on the socket (only significant when SOPC_STATUS_OK returned)
Returns
SOPC_STATUS_OK if operation succeeded, SOPC_STATUS_WOULD_BLOCK if socket read operation would block, SOPC_STATUS_CLOSED in case of disconnection and SOPC_STATUS_NOK otherwise.

◆ SOPC_Socket_BytesToRead()

SOPC_ReturnStatus SOPC_Socket_BytesToRead ( Socket  sock,
uint32_t *  bytesToRead 
)

Retrieve number of bytes available to read on the socket.

Parameters
sockThe socket on which data might be available to read
[out]bytesToReadPointer to the number of bytes available to read on the socket. To be considered only if returned status is SOPC_STATUS_OK
Returns
SOPC_STATUS_OK if operation succeeded, SOPC_STATUS_INVALID_PARAMETERS if parameters are not valid, SOPC_STATUS_NOK otherwise.

◆ SOPC_Socket_Close()

void SOPC_Socket_Close ( Socket sock)

Close the socket connection and/or clear the socket.

Parameters
sockThe socket to disconnect and/or clear