IPC

Detailed Description

Provides functionality for inter-process communication.

Typedefs
typedef struct dwSocketClientObject *	dwSocketClientHandle_t
	Handle representing the a network socket client. More...
typedef struct dwSocketConnectionObject *	dwSocketConnectionHandle_t
	Handle representing the a bi-directional client-server network socket connection. More...
typedef struct dwSocketServerObject *	dwSocketServerHandle_t
	Handle representing the a network socket server. More...

Functions
DW_API_PUBLIC dwStatus	dwSocketClient_broadcast (const uint8_t *buffer, size_t buffer_size, dwSocketClientHandle_t client)
	Broadcasts a message to all connected sockets of the pool. More...
DW_API_PUBLIC dwStatus	dwSocketClient_connect (dwSocketConnectionHandle_t *connection, const char *server_ip, uint16_t port, dwTime_t timeout_us, dwSocketClientHandle_t client)
	Connects a socket connection to a listening socket server. More...
DW_API_PUBLIC dwStatus	dwSocketClient_initialize (dwSocketClientHandle_t *client, size_t connection_pool_size, dwContextHandle_t context)
	Creates and initializes a socket client. More...
DW_API_PUBLIC dwStatus	dwSocketClient_release (dwSocketClientHandle_t *client)
	Terminate a socket client. More...
DW_API_PUBLIC dwStatus	dwSocketConnection_peek (uint8_t *buffer, size_t *buffer_size, dwSocketConnectionHandle_t connection)
	Peek at a message of a given length from the network connection (blocking). More...
DW_API_PUBLIC dwStatus	dwSocketConnection_peekNonBlock (uint8_t *buffer, size_t *buffer_size, dwSocketConnectionHandle_t connection)
	Peek at a message of a given length from the network connection (non-blocking). More...
DW_API_PUBLIC dwStatus	dwSocketConnection_recv (uint8_t *buffer, size_t *buffer_size, dwSocketConnectionHandle_t connection)
	Receive a message of a given length from the network connection (blocking). More...
DW_API_PUBLIC dwStatus	dwSocketConnection_recvNonBlock (uint8_t *buffer, size_t *buffer_size, dwSocketConnectionHandle_t connection)
	Receive a message of a given length from the network connection if data is available (non-blocking). More...
DW_API_PUBLIC dwStatus	dwSocketConnection_release (dwSocketConnectionHandle_t *connection)
	Terminate a socket connection. More...
DW_API_PUBLIC dwStatus	dwSocketConnection_send (const uint8_t *buffer, size_t *buffer_size, dwSocketConnectionHandle_t connection)
	Send a message of a given length through the socket connection. More...
DW_API_PUBLIC dwStatus	dwSocketServer_accept (dwSocketConnectionHandle_t *connection, dwTime_t timeout_us, dwSocketServerHandle_t server)
	Accepts an incoming connection at a socket server. More...
DW_API_PUBLIC dwStatus	dwSocketServer_broadcast (const uint8_t *buffer, size_t buffer_size, dwSocketServerHandle_t server)
	Broadcasts a message to all connected sockets of the pool. More...
DW_API_PUBLIC dwStatus	dwSocketServer_initialize (dwSocketServerHandle_t *server, uint16_t port, size_t connection_pool_size, dwContextHandle_t context)
	Creates and initializes a socket server accepting incoming client connections. More...
DW_API_PUBLIC dwStatus	dwSocketServer_release (dwSocketServerHandle_t *server)
	Terminate a socket server. More...

Typedef Documentation

dwSocketClientHandle_t

typedef struct dwSocketClientObject* dwSocketClientHandle_t

Handle representing the a network socket client.

Definition at line 63 of file SocketClientServer.h.

dwSocketConnectionHandle_t

typedef struct dwSocketConnectionObject* dwSocketConnectionHandle_t

Handle representing the a bi-directional client-server network socket connection.

Definition at line 66 of file SocketClientServer.h.

dwSocketServerHandle_t

typedef struct dwSocketServerObject* dwSocketServerHandle_t

Handle representing the a network socket server.

Definition at line 60 of file SocketClientServer.h.

Function Documentation

dwSocketClient_broadcast()

DW_API_PUBLIC dwStatus dwSocketClient_broadcast	(	const uint8_t *	buffer,
		size_t	buffer_size,
		dwSocketClientHandle_t	client
	)

Broadcasts a message to all connected sockets of the pool.

Parameters

[in]	buffer	A pointer to the data to be send.
[in]	buffer_size	The number of bytes to send.
[in]	client	A handle to the socket client.

Returns

DW_INVALID_HANDLE - if buffer or socket handle is invalid.
DW_FAILURE - if a single message was not send succesfully to all connections.
DW_SUCCESS - if all messages to all connections were send succesfully.

dwSocketClient_connect()

DW_API_PUBLIC dwStatus dwSocketClient_connect	(	dwSocketConnectionHandle_t *	connection,
		const char *	server_ip,
		uint16_t	port,
		dwTime_t	timeout_us,
		dwSocketClientHandle_t	client
	)

Connects a socket connection to a listening socket server.

Parameters

[out]	connection	A pointer to the socket connection handle will be returned here.
[in]	server_ip	A pointer to string representation of the the server's IP address.
[in]	port	The network port the server is listening on.
[in]	timeout_us	Timeout to block this call.
[in]	client	A handle to the socket client.

Returns

DW_BUFFER_FULL - if the clients's connection pool is depleted.
DW_CANNOT_CREATE_OBJECT - if the socket can't be created or the server's IP is invalid
DW_TIME_OUT - if no connection could be accepted before the timeout.
DW_INVALID_ARGUMENT - if the client handle is invalid.
DW_SUCCESS - if a socket connection was established.

dwSocketClient_initialize()

DW_API_PUBLIC dwStatus dwSocketClient_initialize	(	dwSocketClientHandle_t *	client,
		size_t	connection_pool_size,
		dwContextHandle_t	context
	)

Creates and initializes a socket client.

Parameters

[out]	client	A pointer to the client handle will be returned here.
[in]	connection_pool_size	The maximal number of concurrently connected connections.
[in]	context	Specifies the handle to the context under which the socket client is created.

Returns

DW_INVALID_HANDLE - if provided context handle is invalid.
DW_SUCCESS - when client was created successfully.

dwSocketClient_release()

DW_API_PUBLIC dwStatus dwSocketClient_release

(

dwSocketClientHandle_t *

client

)

Terminate a socket client.

Parameters

[in]

client

A handle to the socket client.

Returns

DW_FAILURE - if client was not terminated cleanly
DW_SUCCESS - if client was terminated cleanly.

dwSocketConnection_peek()

DW_API_PUBLIC dwStatus dwSocketConnection_peek	(	uint8_t *	buffer,
		size_t *	buffer_size,
		dwSocketConnectionHandle_t	connection
	)

Peek at a message of a given length from the network connection (blocking).

Parameters

[in]	buffer	A pointer to the memory location data is written to.
[in,out]	buffer_size	A pointer to the number of bytes to receive, and the actual number of bytes received on success.
[in]	connection	A handle to the network socket connection.

Returns

DW_INVALID_HANDLE - if buffer or socket handle is invalid.
DW_END_OF_STREAM - if the connection ended.
DW_FAILURE - if data could not be received.
DW_SUCCESS - if data could be received.

dwSocketConnection_peekNonBlock()

DW_API_PUBLIC dwStatus dwSocketConnection_peekNonBlock	(	uint8_t *	buffer,
		size_t *	buffer_size,
		dwSocketConnectionHandle_t	connection
	)

Peek at a message of a given length from the network connection (non-blocking).

Parameters

[in]	buffer	A pointer to the memory location data is written to.
[in,out]	buffer_size	A pointer to the number of bytes to receive, and the actual number of bytes received on success.
[in]	connection	A handle to the network socket connection.

Returns

DW_INVALID_HANDLE - if buffer or socket handle is invalid.
DW_END_OF_STREAM - if the connection ended.
DW_FAILURE - if data could not be received.
DW_SUCCESS - if data could be received.

dwSocketConnection_recv()

DW_API_PUBLIC dwStatus dwSocketConnection_recv	(	uint8_t *	buffer,
		size_t *	buffer_size,
		dwSocketConnectionHandle_t	connection
	)

Receive a message of a given length from the network connection (blocking).

Parameters

[in]	buffer	A pointer to the memory location data is written to.
[in,out]	buffer_size	A pointer to the number of bytes to receive, and the actual number of bytes received on success.
[in]	connection	A handle to the network socket connection.

Returns

DW_INVALID_HANDLE - if buffer or socket handle is invalid.
DW_END_OF_STREAM - if the connection ended.
DW_FAILURE - if data could not be received.
DW_SUCCESS - if data could be received.

dwSocketConnection_recvNonBlock()

DW_API_PUBLIC dwStatus dwSocketConnection_recvNonBlock	(	uint8_t *	buffer,
		size_t *	buffer_size,
		dwSocketConnectionHandle_t	connection
	)

Receive a message of a given length from the network connection if data is available (non-blocking).

Parameters

[in]	buffer	A pointer to the memory location data is written to.
[in,out]	buffer_size	The number of bytes to receive, and actual number of bytes received on success.
[in]	connection	A handle to the network socket connection.

Returns

DW_INVALID_HANDLE - if buffer or socket handle is invalid.
DW_END_OF_STREAM - if the connection ended.
DW_TIME_OUT - if not sufficient data is available to be received.
DW_FAILURE - if data could not be received.
DW_SUCCESS - if data could be received.

dwSocketConnection_release()

DW_API_PUBLIC dwStatus dwSocketConnection_release

(

dwSocketConnectionHandle_t *

connection

)

Terminate a socket connection.

Parameters

[in]

connection

A handle to the socket connection.

Returns

DW_FAILURE - if connection was not terminated cleanly
DW_SUCCESS - if connection was terminated cleanly.

dwSocketConnection_send()

DW_API_PUBLIC dwStatus dwSocketConnection_send	(	const uint8_t *	buffer,
		size_t *	buffer_size,
		dwSocketConnectionHandle_t	connection
	)

Send a message of a given length through the socket connection.

Parameters

[in]	buffer	A pointer to the data to be send.
[in,out]	buffer_size	A pointer to the number of bytes to send, and the actual number of bytes send on success.
[in]	connection	A handle to the network socket connection.

Returns

DW_INVALID_HANDLE - if buffer or socket handle is invalid.
DW_END_OF_STREAM - if the connection ended.
DW_FAILURE - if data could not be transmitted.
DW_SUCCESS - if data could be send.

dwSocketServer_accept()

DW_API_PUBLIC dwStatus dwSocketServer_accept	(	dwSocketConnectionHandle_t *	connection,
		dwTime_t	timeout_us,
		dwSocketServerHandle_t	server
	)

Accepts an incoming connection at a socket server.

Parameters

[out]	connection	A pointer to the socket connection handle will be returned here.
[in]	timeout_us	Timeout to block this call.
[in]	server	A handle to the socket server.

Returns

DW_BUFFER_FULL - if the server's connection pool is depleted.
DW_TIME_OUT - if no connection could be accepted before the timeout.
DW_INVALID_ARGUMENT - if the server handle is invalid.
DW_SUCCESS - if a socket connection was established.

dwSocketServer_broadcast()

DW_API_PUBLIC dwStatus dwSocketServer_broadcast	(	const uint8_t *	buffer,
		size_t	buffer_size,
		dwSocketServerHandle_t	server
	)

Broadcasts a message to all connected sockets of the pool.

Parameters

[in]	buffer	A pointer to the data to be send.
[in]	buffer_size	The number of bytes to send.
[in]	server	A handle to the socket server.

Returns

DW_INVALID_HANDLE - if buffer or socket handle is invalid.
DW_FAILURE - if a single message was not send successfully to all connections.
DW_SUCCESS - if all messages to all connections were send successfully.

dwSocketServer_initialize()

DW_API_PUBLIC dwStatus dwSocketServer_initialize	(	dwSocketServerHandle_t *	server,
		uint16_t	port,
		size_t	connection_pool_size,
		dwContextHandle_t	context
	)

Creates and initializes a socket server accepting incoming client connections.

Parameters

[out]	server	A pointer to the server handle will be returned here.
[in]	port	The network port the server is listening on.
[in]	connection_pool_size	The maximal number of concurrently acceptable connections.
[in]	context	Specifies the handle to the context under which the socket server is created.

Returns

DW_CANNOT_CREATE_OBJECT - if socket initialization failed.
DW_INVALID_HANDLE - if provided context handle is invalid.
DW_SUCCESS - if server is created succesfully.

dwSocketServer_release()

DW_API_PUBLIC dwStatus dwSocketServer_release

(

dwSocketServerHandle_t *

server

)

Terminate a socket server.

Parameters

[in]

server

A handle to the socket server.

Returns

DW_FAILURE - if server was not terminated cleanly
DW_SUCCESS - if server was terminated cleanly.