Collaboration diagram for Interface to the TCP/IP stack (abstract socket layer):

Typedefs
typedef struct sServerSocket *	ServerSocket

typedef struct sUdpSocket *	UdpSocket

typedef struct sSocket *	Socket

typedef struct sHandleSet *	HandleSet

Enumerations
enum	SocketState { SOCKET_STATE_CONNECTING = 0 , SOCKET_STATE_FAILED = 1 , SOCKET_STATE_CONNECTED = 2 }

Functions
PAL_API HandleSet	Handleset_new (void)
	Create a new connection handle set (HandleSet) More...

PAL_API void	Handleset_reset (HandleSet self)
	Reset the handle set for reuse.

PAL_API void	Handleset_addSocket (HandleSet self, const Socket sock)
	add a socket to an existing handle set More...

void	Handleset_removeSocket (HandleSet self, const Socket sock)
	remove a socket from an existing handle set

PAL_API int	Handleset_waitReady (HandleSet self, unsigned int timeoutMs)
	wait for a socket to become ready More...

PAL_API void	Handleset_destroy (HandleSet self)
	destroy the HandleSet instance More...

PAL_API ServerSocket	TcpServerSocket_create (const char *address, int port)
	Create a new TcpServerSocket instance. More...

PAL_API UdpSocket	UdpSocket_create (void)

PAL_API bool	UdpSocket_bind (UdpSocket self, const char *address, int port)

PAL_API bool	UdpSocket_sendTo (UdpSocket self, const char address, int port, uint8_t msg, int msgSize)

PAL_API int	UdpSocket_receiveFrom (UdpSocket self, char address, int maxAddrSize, uint8_t msg, int msgSize)
	Receive data from UDP socket (store data and (optionally) the IP address of the sender. More...

PAL_API void	ServerSocket_listen (ServerSocket self)

PAL_API Socket	ServerSocket_accept (ServerSocket self)
	accept a new incoming connection (non-blocking) More...

PAL_API void	Socket_activateTcpKeepAlive (Socket self, int idleTime, int interval, int count)
	active TCP keep alive for socket and set keep alive parameters More...

PAL_API void	ServerSocket_setBacklog (ServerSocket self, int backlog)
	set the maximum number of pending connections in the queue More...

PAL_API void	ServerSocket_destroy (ServerSocket self)
	destroy a server socket instance More...

PAL_API Socket	TcpSocket_create (void)
	create a TCP client socket More...

PAL_API void	Socket_setConnectTimeout (Socket self, uint32_t timeoutInMs)
	set the timeout to establish a new connection More...

PAL_API bool	Socket_bind (Socket self, const char *srcAddress, int srcPort)
	bind a socket to a particular IP address and port (for TcpSocket) More...

PAL_API bool	Socket_connect (Socket self, const char *address, int port)
	connect to a server More...

PAL_API bool	Socket_connectAsync (Socket self, const char *address, int port)

PAL_API SocketState	Socket_checkAsyncConnectState (Socket self)

PAL_API int	Socket_read (Socket self, uint8_t *buf, int size)
	read from socket to local buffer (non-blocking) More...

PAL_API int	Socket_write (Socket self, uint8_t *buf, int size)
	send a message through the socket More...

PAL_API char *	Socket_getLocalAddress (Socket self)

PAL_API char *	Socket_getPeerAddress (Socket self)
	Get the address of the peer application (IP address and port number) More...

PAL_API char *	Socket_getPeerAddressStatic (Socket self, char *peerAddressString)
	Get the address of the peer application (IP address and port number) More...

PAL_API void	Socket_destroy (Socket self)
	destroy a socket (close the socket if a connection is established) More...

Detailed Description

Thread and Socket abstraction layer. This functions have to be implemented to port lib60870 to a new hardware/OS platform when TCP/IP is required.

Typedef Documentation

◆ HandleSet

typedef struct sHandleSet* HandleSet

Opaque reference for a set of server and socket handles

◆ ServerSocket

typedef struct sServerSocket* ServerSocket

Opaque reference for a server socket instance

◆ Socket

typedef struct sSocket* Socket

Opaque reference for a client or connection socket instance

Enumeration Type Documentation

◆ SocketState

enum SocketState

State of an asynchronous connect

Function Documentation

◆ Handleset_addSocket()

PAL_API void Handleset_addSocket	(	HandleSet	self,
		const Socket	sock
	)

add a socket to an existing handle set

Parameters

self	the HandleSet instance
sock	the socket to add

◆ Handleset_destroy()

PAL_API void Handleset_destroy ( HandleSet self )

destroy the HandleSet instance

Parameters

self	the HandleSet instance to destroy

◆ Handleset_new()

PAL_API HandleSet Handleset_new ( void )

Create a new connection handle set (HandleSet)

Returns: new HandleSet instance

◆ Handleset_waitReady()

PAL_API int Handleset_waitReady	(	HandleSet	self,
		unsigned int	timeoutMs
	)

wait for a socket to become ready

This function is corresponding to the BSD socket select function. It returns the number of sockets on which data is pending or 0 if no data is pending on any of the monitored connections. The function will return after "timeout" ms if no data is pending. The function shall return -1 if a socket error occures.

Parameters

self	the HandleSet instance
timeout	in milliseconds (ms)

Returns: It returns the number of sockets on which data is pending or 0 if no data is pending on any of the monitored connections. The function shall return -1 if a socket error occures.

◆ ServerSocket_accept()

PAL_API Socket ServerSocket_accept ( ServerSocket self )

accept a new incoming connection (non-blocking)

This function shall accept a new incoming connection. It is non-blocking and has to return NULL if no new connection is pending.

Implementation of this function is MANDATORY if server functionality is required.

NOTE: The behaviour of this function changed with version 0.8!

Parameters

self	server socket instance

Returns: handle of the new connection socket or NULL if no new connection is available

◆ ServerSocket_destroy()

PAL_API void ServerSocket_destroy ( ServerSocket self )

destroy a server socket instance

Free all resources allocated by this server socket instance.

Implementation of this function is MANDATORY if server functionality is required.

Parameters

self	server socket instance

◆ ServerSocket_setBacklog()

PAL_API void ServerSocket_setBacklog	(	ServerSocket	self,
		int	backlog
	)

set the maximum number of pending connections in the queue

Implementation of this function is OPTIONAL.

Parameters

self	the server socket instance
backlog	the number of pending connections in the queue

◆ Socket_activateTcpKeepAlive()

PAL_API void Socket_activateTcpKeepAlive	(	Socket	self,
		int	idleTime,
		int	interval,
		int	count
	)

active TCP keep alive for socket and set keep alive parameters

NOTE: implementation is mandatory for IEC 61850 MMS

Parameters

self	server socket instance
idleTime	time (in s) between last received message and first keep alive message
interval	time (in s) between subsequent keep alive messages if no ACK received
count	number of not missing keep alive ACKs until socket is considered dead

◆ Socket_bind()

PAL_API bool Socket_bind	(	Socket	self,
		const char *	srcAddress,
		int	srcPort
	)

bind a socket to a particular IP address and port (for TcpSocket)

NOTE: Don't use the socket when this functions returns false!

Parameters

self	the client socket instance
srcAddress	the local IP address or hostname as C string
srcPort	the local TCP port to use. When < 1 the OS will chose the TCP port to use.

Returns: true in case of success, false otherwise

◆ Socket_connect()

PAL_API bool Socket_connect	(	Socket	self,
		const char *	address,
		int	port
	)

connect to a server

Connect to a server application identified by the address and port parameter.

The "address" parameter may either be a hostname or an IP address. The IP address has to be provided as a C string (e.g. "10.0.2.1").

Implementation of this function is MANDATORY if client functionality is required.

NOTE: return type changed from int to bool with version 0.8

Parameters

self	the client socket instance
address	the IP address or hostname as C string
port	the TCP port of the application to connect to

Returns: true if the connection was established successfully, false otherwise

◆ Socket_destroy()

PAL_API void Socket_destroy ( Socket self )

destroy a socket (close the socket if a connection is established)

This function shall close the connection (if one is established) and free all resources allocated by the socket.

Implementation of this function is MANDATORY

Parameters

self	the client, connection or server socket instance

◆ Socket_getPeerAddress()

PAL_API char* Socket_getPeerAddress ( Socket self )

Get the address of the peer application (IP address and port number)

The peer address has to be returned as null terminated string

Implementation of this function is MANDATORY (libiec61850)

Parameters

self	the client, connection or server socket instance

Returns: the IP address and port number as strings separated by the ':' character.

◆ Socket_getPeerAddressStatic()

PAL_API char* Socket_getPeerAddressStatic	(	Socket	self,
		char *	peerAddressString
	)

Get the address of the peer application (IP address and port number)

The peer address has to be returned as null terminated string

Implementation of this function is MANDATORY (lib60870 and libiec61850)

Parameters

self	the client, connection or server socket instance
peerAddressString	a string to store the peer address (the string should have space for at least 60 characters)

Returns: the IP address and port number as strings separated by the ':' character. If the address is an IPv6 address the IP part is encapsulated in square brackets.

◆ Socket_read()

PAL_API int Socket_read	(	Socket	self,
		uint8_t *	buf,
		int	size
	)

read from socket to local buffer (non-blocking)

The function shall return immediately if no data is available. In this case the function returns 0. If an error happens the function shall return -1.

Implementation of this function is MANDATORY

NOTE: The behaviour of this function changed with version 0.8!

Parameters

self	the client, connection or server socket instance
buf	the buffer where the read bytes are copied to
size	the maximum number of bytes to read (size of the provided buffer)

Returns: the number of bytes read or -1 if an error occurred

◆ Socket_setConnectTimeout()

PAL_API void Socket_setConnectTimeout	(	Socket	self,
		uint32_t	timeoutInMs
	)

set the timeout to establish a new connection

Parameters

self	the client socket instance
timeoutInMs	the timeout in ms

◆ Socket_write()

PAL_API int Socket_write	(	Socket	self,
		uint8_t *	buf,
		int	size
	)

send a message through the socket

Implementation of this function is MANDATORY

Parameters

self	client, connection or server socket instance

Returns: number of bytes transmitted of -1 in case of an error

◆ TcpServerSocket_create()

PAL_API ServerSocket TcpServerSocket_create	(	const char *	address,
		int	port
	)

Create a new TcpServerSocket instance.

Implementation of this function is MANDATORY if server functionality is required.

Parameters

address	ip address or hostname to listen on
port	the TCP port to listen on

Returns: the newly create TcpServerSocket instance

◆ TcpSocket_create()

PAL_API Socket TcpSocket_create ( void )

create a TCP client socket

Implementation of this function is MANDATORY if client functionality is required.

Returns: a new client socket instance.

◆ UdpSocket_receiveFrom()

PAL_API int UdpSocket_receiveFrom	(	UdpSocket	self,
		char *	address,
		int	maxAddrSize,
		uint8_t *	msg,
		int	msgSize
	)

Receive data from UDP socket (store data and (optionally) the IP address of the sender.

Parameters

self	UDP socket instance
address	(optional) buffer to store the IP address as string
maxAddrSize	(optional) size of the provided buffer to store the IP address
msg	buffer to store the UDP message data
msgSize	the maximum size of the message to receive

Returns: number of received bytes or -1 in case of an error

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ HandleSet

◆ ServerSocket

◆ Socket

Enumeration Type Documentation

◆ SocketState

Function Documentation

◆ Handleset_addSocket()

◆ Handleset_destroy()

◆ Handleset_new()

◆ Handleset_waitReady()

◆ ServerSocket_accept()

◆ ServerSocket_destroy()

◆ ServerSocket_setBacklog()

◆ Socket_activateTcpKeepAlive()

◆ Socket_bind()

◆ Socket_connect()

◆ Socket_destroy()

◆ Socket_getPeerAddress()

◆ Socket_getPeerAddressStatic()

◆ Socket_read()

◆ Socket_setConnectTimeout()

◆ Socket_write()

◆ TcpServerSocket_create()

◆ TcpSocket_create()

◆ UdpSocket_receiveFrom()