sopc_raw_sockets.h File Reference

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

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

Go to the source code of this file.

Macros
#define	SOPC_INVALID_SOCKET   NULL

Typedefs
typedef struct SOPC_Socket_Impl	SOPC_Socket_Impl
	Provides a socket implementation.
typedef SOPC_Socket_Impl *	SOPC_Socket
typedef struct SOPC_Socket_AddressInfo	SOPC_Socket_AddressInfo
	Provides a socket address info implementation.
typedef struct SOPC_Socket_Address	SOPC_Socket_Address
	Provides a socket address implementation.
typedef struct SOPC_SocketSet	SOPC_SocketSet
	Provides a socket set implementation.

Functions
SOPC_ReturnStatus	SOPC_Socket_Network_Enable_Keepalive (SOPC_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.
SOPC_ReturnStatus	SOPC_Socket_Network_Disable_Keepalive (SOPC_Socket sock)
	Deactivate the keep alive mechanism.
bool	SOPC_Socket_Network_Initialize (void)
	Initialize the network communication allowing to use sockets.
bool	SOPC_Socket_Network_Clear (void)
	Clear the network communication when sockets not used anymore.
SOPC_ReturnStatus	SOPC_Socket_AddrInfo_Get (const char *hostname, const 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.
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.
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.
void	SOPC_Socket_AddrInfoDelete (SOPC_Socket_AddressInfo **addrs)
	Deallocate a linked list of socket addressing information.
SOPC_Socket_Address *	SOPC_Socket_GetPeerAddress (SOPC_Socket sock)
	Given a socket get the address information associated to the peer connected to the socket.
SOPC_Socket_Address *	SOPC_Socket_CopyAddress (SOPC_Socket_AddressInfo *addr)
	Copy the socket address from a socket address information.
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.
void	SOPC_SocketAddress_Delete (SOPC_Socket_Address **addr)
	Deallocate a socket address obtained with SOPC_Socket_GetPeerAddress or SOPC_Socket_CopyAddress.
void	SOPC_Socket_Clear (SOPC_Socket *sock)
	Clear socket state to an invalid socket.
SOPC_ReturnStatus	SOPC_Socket_CreateNew (SOPC_Socket_AddressInfo *addr, bool setReuseAddr, bool setNonBlocking, SOPC_Socket *sock)
	Create a new socket using the addressing information provided.
SOPC_ReturnStatus	SOPC_Socket_Listen (SOPC_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.
SOPC_ReturnStatus	SOPC_Socket_Accept (SOPC_Socket listeningSock, bool setNonBlocking, SOPC_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.
SOPC_ReturnStatus	SOPC_Socket_Connect (SOPC_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.
SOPC_ReturnStatus	SOPC_Socket_ConnectToLocal (SOPC_Socket from, SOPC_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.
SOPC_ReturnStatus	SOPC_Socket_CheckAckConnect (SOPC_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.
SOPC_SocketSet *	SOPC_SocketSet_Create (void)
	Create a socket set.
void	SOPC_SocketSet_Delete (SOPC_SocketSet **set)
	Delete the pointed socket set and set the pointer to NULL.
void	SOPC_SocketSet_Add (SOPC_Socket sock, SOPC_SocketSet *sockSet)
	Add a socket to the given socket set.
bool	SOPC_SocketSet_IsPresent (SOPC_Socket sock, SOPC_SocketSet *sockSet)
	Returns if a socket is present in the given socket set.
void	SOPC_SocketSet_Clear (SOPC_SocketSet *sockSet)
	Clear a socket set.
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.
SOPC_ReturnStatus	SOPC_Socket_Write (SOPC_Socket sock, const uint8_t *data, uint32_t count, uint32_t *sentBytes)
	Write data through the socket.
SOPC_ReturnStatus	SOPC_Socket_Read (SOPC_Socket sock, uint8_t *data, uint32_t dataSize, uint32_t *readCount)
	Read data through the socket.
SOPC_ReturnStatus	SOPC_Socket_BytesToRead (SOPC_Socket sock, uint32_t *bytesToRead)
	Retrieve number of bytes available to read on the socket.
void	SOPC_Socket_Close (SOPC_Socket *sock)
	Close the socket connection and/or clear the socket.

Detailed Description

A platform independent API to use sockets.

Macro Definition Documentation

SOPC_INVALID_SOCKET

#define SOPC_INVALID_SOCKET   NULL

Typedef Documentation

SOPC_Socket_Impl

typedef struct SOPC_Socket_Impl SOPC_Socket_Impl

Provides a socket implementation.

Note

Each platform must provide the implementation of SOPC_Socket_Impl and all related functions in sopc_raw_sockets.h

SOPC_Socket

typedef SOPC_Socket_Impl* SOPC_Socket

SOPC_Socket_AddressInfo

typedef struct SOPC_Socket_AddressInfo SOPC_Socket_AddressInfo

Provides a socket address info implementation.

Note

Each platform must provide the implementation of SOPC_Socket_AddressInfo and all related functions in sopc_raw_sockets.h

SOPC_Socket_Address

typedef struct SOPC_Socket_Address SOPC_Socket_Address

Provides a socket address implementation.

Note

Each platform must provide the implementation of SOPC_Socket_Address and all related functions in sopc_raw_sockets.h

SOPC_SocketSet

typedef struct SOPC_SocketSet SOPC_SocketSet

Provides a socket set implementation.

Note

Each platform must provide the implementation of SOPC_SocketSet and all related functions in sopc_raw_sockets.h

Function Documentation

SOPC_Socket_Network_Enable_Keepalive()

SOPC_ReturnStatus SOPC_Socket_Network_Enable_Keepalive	(	SOPC_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.

Parameters

sock	The socket to activate keep alive probes
firstProbeDelay	The time (in seconds) the connection needs to remain idle before TCP starts sendingkeepalive probes
interval	The time (in seconds) between individual keepalive probes
counter	The 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

(

SOPC_Socket

sock

)

Deactivate the keep alive mechanism.

Parameters

sock	The 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	(	const char *	hostname,
		const 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

hostname	The hostname of the machine to connect or used to listen (optional for listening)
port	The port number on which to connect or to listen to (optional for listening if hostname set)
addrs	The 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

addr	A 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

addr	A 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

(

SOPC_Socket

sock

)

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

Parameters

sock	The 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

addr	The 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

	addr	The 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). Must be deallocated by caller (if non-NULL)
[out]	service	(optional) The service information of the address as C string (i.e. port). Must be deallocated by caller (if non-NULL)

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

(

SOPC_Socket *

sock

)

Clear socket state to an invalid socket.

Parameters

[out]

sock

Value pointed is set to invalid socket value

SOPC_Socket_CreateNew()

SOPC_ReturnStatus SOPC_Socket_CreateNew	(	SOPC_Socket_AddressInfo *	addr,
		bool	setReuseAddr,
		bool	setNonBlocking,
		SOPC_Socket *	sock )

Create a new socket using the addressing information provided.

Parameters

	addr	The addressing information used to instantiate a TCP/IP socket
	setReuseAddr	If value is not false (0) the socket is configured to be reused
	setNonBlocking	If value is not false (0) the socket is configured to be non blocking
[out]	sock	Value 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	(	SOPC_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

sock	The socket used for binding and listening
addr	The 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	(	SOPC_Socket	listeningSock,
		bool	setNonBlocking,
		SOPC_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

	listeningSock	The listening socket on which a read event has been received.
	setNonBlocking	If value is not false (0) the connection socket is configured to be non blocking
[out]	acceptedSock	Value 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	(	SOPC_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

addr	The addressing information used to establish connection (IP and port)
sock	The 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	(	SOPC_Socket	from,
		SOPC_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

from	The socket used for establishing the connection
to	The 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

(

SOPC_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

sock	The 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_Create()

SOPC_SocketSet * SOPC_SocketSet_Create

(

void

)

Create a socket set.

Returns

A socket set or NULL in case of failure.

SOPC_SocketSet_Delete()

void SOPC_SocketSet_Delete

(

SOPC_SocketSet **

set

)

Delete the pointed socket set and set the pointer to NULL.

SOPC_SocketSet_Add()

void SOPC_SocketSet_Add	(	SOPC_Socket	sock,
		SOPC_SocketSet *	sockSet )

Add a socket to the given socket set.

Parameters

sock	The socket to add to the set (not NULL)
sockSet	The socket set to use for the operation (not NULL)

SOPC_SocketSet_IsPresent()

bool SOPC_SocketSet_IsPresent	(	SOPC_Socket	sock,
		SOPC_SocketSet *	sockSet )

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

Parameters

sock	The socket to search in the set (not NULL)
sockSet	The 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

sockSet

The 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
waitMs	The 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	(	SOPC_Socket	sock,
		const uint8_t *	data,
		uint32_t	count,
		uint32_t *	sentBytes )

Write data through the socket.

Parameters

sock	The socket on which data must be written
data	The data bytes to write on socket
count	The number of bytes to write
sentBytes	Pointer 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	(	SOPC_Socket	sock,
		uint8_t *	data,
		uint32_t	dataSize,
		uint32_t *	readCount )

Read data through the socket.

Parameters

sock	The socket on which data must be read
data	The data bytes to be set with read bytes
dataSize	The number of bytes that can be set (or expected to be read)
readCount	Pointer 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	(	SOPC_Socket	sock,
		uint32_t *	bytesToRead )

Retrieve number of bytes available to read on the socket.

Parameters

	sock	The socket on which data might be available to read
[out]	bytesToRead	Pointer 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

(

SOPC_Socket *

sock

)

Close the socket connection and/or clear the socket.

Parameters

sock	The socket to disconnect and/or clear