Interface to the TCP/IP stack (abstract socket layer)

Typedefs
typedef struct sServerSocket *	ServerSocket
typedef struct sSocket *	Socket
typedef struct sHandleSet *	HandleSet

Functions
HandleSet	Handleset_new (void)
	Create a new connection handle set (HandleSet) More...
void	Handleset_addSocket (HandleSet self, const Socket sock)
	add a socket to an existing handle set More...
int	Handleset_waitReady (HandleSet self, unsigned int timeoutMs)
	wait for a socket to become ready More...
void	Handleset_destroy (HandleSet self)
	destroy the HandleSet instance More...
ServerSocket	TcpServerSocket_create (const char *address, int port)
	Create a new TcpServerSocket instance. More...
void	ServerSocket_listen (ServerSocket self)
Socket	ServerSocket_accept (ServerSocket self)
	accept a new incoming connection (non-blocking) More...
void	ServerSocket_setBacklog (ServerSocket self, int backlog)
	set the maximum number of pending connection in the queue More...
void	ServerSocket_destroy (ServerSocket self)
	destroy a server socket instance More...
Socket	TcpSocket_create (void)
	create a TCP client socket More...
void	Socket_setConnectTimeout (Socket self, uint32_t timeoutInMs)
	set the timeout to establish a new connection More...
bool	Socket_connect (Socket self, const char *address, int port)
	connect to a server More...
int	Socket_read (Socket self, uint8_t *buf, int size)
	read from socket to local buffer (non-blocking) More...
int	Socket_write (Socket self, uint8_t *buf, int size)
	send a message through the socket More...
char *	Socket_getPeerAddress (Socket self)
	Get the address of the peer application (IP address and port number) More...
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 libIEC61850 to a new hardware/OS platform.

Typedef Documentation

typedef struct sHandleSet* HandleSet

Opaque reference for a set of server and socket handles

typedef struct sServerSocket* ServerSocket

Opaque reference for a server socket instance

typedef struct sSocket* Socket

Opaque reference for a client or connection socket instance

Function Documentation

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

void Handleset_destroy

(

HandleSet

self

)

destroy the HandleSet instance

Parameters

self	the HandleSet instance to destroy

HandleSet Handleset_new

(

void

)

Create a new connection handle set (HandleSet)

Returns

new HandleSet instance

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. The function will return after timeoutMs ms if no data is pending.

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.

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

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

void ServerSocket_listen

(

ServerSocket

self

)

void ServerSocket_setBacklog	(	ServerSocket	self,
		int	backlog
	)

set the maximum number of pending connection in the queue

Implementation of this function is OPTIONAL.

Parameters

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

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

a new client socket instance.

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

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

Implementation of this function is MANDATORY

Parameters

self	the client, connection or server socket instance

Returns

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

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

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

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

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

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.