Detailed Description

Provides functionality for inter-process communication (IPC).

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 (uint8_t const *const buffer, size_t const bufferSize, dwSocketClientHandle_t const client)
	Broadcasts a message to all connected sockets of the pool. More...

DW_API_PUBLIC dwStatus	dwSocketClient_connect (dwSocketConnectionHandle_t const connection, char8_t const const host, uint16_t const port, dwTime_t const timeoutUs, dwSocketClientHandle_t const client)
	Connects a socket connection to a listening socket server. More...

DW_API_PUBLIC dwStatus	dwSocketClient_initialize (dwSocketClientHandle_t *const client, size_t const connectionPoolSize, dwConstContextHandle_t const context)
	Creates and initializes a socket client. More...

DW_API_PUBLIC dwStatus	dwSocketClient_release (dwSocketClientHandle_t const client)
	Terminate a socket client. More...

DW_API_PUBLIC dwStatus	dwSocketConnection_peek (uint8_t const buffer, size_t const bufferSize, dwTime_t const timeoutUs, dwSocketConnectionHandle_t const connection)
	Peek at a message of a given length from the network connection (blocking within timeout period). More...

DW_API_PUBLIC dwStatus	dwSocketConnection_read (void const buffer, size_t const bufferSize, dwTime_t const timeoutUs, dwSocketConnectionHandle_t const connection)
	Receive a message of a given length from the network connection. More...

DW_API_PUBLIC dwStatus	dwSocketConnection_release (dwSocketConnectionHandle_t const connection)
	Terminate a socket connection. More...

DW_API_PUBLIC dwStatus	dwSocketConnection_write (const void const buffer, size_t const bufferSize, dwTime_t const timeoutUs, dwSocketConnectionHandle_t const connection)
	Send a message of a given length through the socket connection with a timeout. More...

DW_API_PUBLIC dwStatus	dwSocketServer_accept (dwSocketConnectionHandle_t *const connection, dwTime_t const timeoutUs, dwSocketServerHandle_t const server)
	Accepts an incoming connection at a socket server. More...

DW_API_PUBLIC dwStatus	dwSocketServer_broadcast (uint8_t const *const buffer, size_t const bufferSize, dwSocketServerHandle_t const server)
	Broadcasts a message to all connected sockets of the pool. More...

DW_API_PUBLIC dwStatus	dwSocketServer_initialize (dwSocketServerHandle_t *const server, uint16_t const port, size_t const connectionPoolSize, dwConstContextHandle_t const context)
	Creates and initializes a socket server accepting incoming client connections. More...

DW_API_PUBLIC dwStatus	dwSocketServer_release (dwSocketServerHandle_t const 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	(	uint8_t const *const	buffer,
		size_t const	bufferSize,
		dwSocketClientHandle_t const	client
	)

Broadcasts a message to all connected sockets of the pool.

Parameters

[in]	buffer	A pointer to the data to be send.
[in]	bufferSize	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, i.e. null or of wrong type
DW_FAILURE - if a single message was not send successfully to all connections.
DW_SUCCESS - if all messages to all connections were send successfully.

◆ dwSocketClient_connect()

DW_API_PUBLIC dwStatus dwSocketClient_connect	(	dwSocketConnectionHandle_t *const	connection,
		char8_t const *const	host,
		uint16_t const	port,
		dwTime_t const	timeoutUs,
		dwSocketClientHandle_t const	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]	host	A pointer to string representation of the the server's IP address or hostname.
[in]	port	The network port the server is listening on.
[in]	timeoutUs	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/hostname 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 *const	client,
		size_t const	connectionPoolSize,
		dwConstContextHandle_t const	context
	)

Creates and initializes a socket client.

Parameters

[out]	client	A pointer to the client handle will be returned here.
[in]	connectionPoolSize	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, i.e. null or of wrong type
DW_SUCCESS - when client was created successfully.

◆ dwSocketClient_release()

DW_API_PUBLIC dwStatus dwSocketClient_release ( dwSocketClientHandle_t const 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 *const	buffer,
		size_t *const	bufferSize,
		dwTime_t const	timeoutUs,
		dwSocketConnectionHandle_t const	connection
	)

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

Parameters

[in]	buffer	A pointer to the memory location data is written to.
[in,out]	bufferSize	A pointer to the number of bytes to receive, and the actual number of bytes received on success.
[in]	timeoutUs	Timeout to block this call. Specify 0 for non-blocking behavior. Specify DW_TIMEOUT_INFINITE for infinitely blocking behavior until data is available.
[in]	connection	A handle to the network socket connection.

Returns: DW_INVALID_HANDLE - if buffer or socket handle is invalid,i.e. null or of wrong type
DW_END_OF_STREAM - if the connection ended.
DW_TIME_OUT - if no data is available to be received before the timeout.
DW_FAILURE - if data could not be received or timeout could not be set.
DW_SUCCESS - if data could be received.

◆ dwSocketConnection_read()

DW_API_PUBLIC dwStatus dwSocketConnection_read	(	void *const	buffer,
		size_t *const	bufferSize,
		dwTime_t const	timeoutUs,
		dwSocketConnectionHandle_t const	connection
	)

Receive a message of a given length from the network connection.

The method blocks for the provided amount of time to receive the data.

Parameters

[in]	buffer	A pointer to the memory location data is written to.
[in,out]	bufferSize	A pointer to the number of bytes to receive, and the actual number of bytes received.
[in]	timeoutUs	Time to wait to receive the content. Can be 0 for non-blocking and DW_TIMEOUT_INFINITE for blocking mode
[in]	connection	A handle to the network socket connection.

Returns: DW_INVALID_HANDLE - if buffer or socket handle is invalid,i.e. null or of wrong type
DW_END_OF_STREAM - if the connection ended.
DW_TIME_OUT - if timed out before any data could 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 const 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_write()

DW_API_PUBLIC dwStatus dwSocketConnection_write	(	const void *const	buffer,
		size_t *const	bufferSize,
		dwTime_t const	timeoutUs,
		dwSocketConnectionHandle_t const	connection
	)

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

While sending has not timedout, the buffer will be retried to be sent as long as possible.

Parameters

[in]	buffer	A pointer to the data to be send.
[in,out]	bufferSize	A pointer to the number of bytes to send, and the actual number of bytes sent.
[in]	timeoutUs	Amount of time to try to send the data
[in]	connection	A handle to the network socket connection.

Returns: DW_INVALID_HANDLE - if buffer or socket handle is invalid,i.e. null or of wrong type
DW_END_OF_STREAM - if the connection ended.
DW_FAILURE - if data could not be transmitted.
DW_TIME_OUT - if no data could be transmitted within the requested timeout time.
DW_SUCCESS - if data could be send.

Note: Even if the method times out, at least partially the data could have been sent.

◆ dwSocketServer_accept()

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

Accepts an incoming connection at a socket server.

Parameters

[out]	connection	A pointer to the socket connection handle will be returned here.
[in]	timeoutUs	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	(	uint8_t const *const	buffer,
		size_t const	bufferSize,
		dwSocketServerHandle_t const	server
	)

Broadcasts a message to all connected sockets of the pool.

Parameters

[in]	buffer	A pointer to the data to be send.
[in]	bufferSize	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,i.e. null or of wrong type
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 *const	server,
		uint16_t const	port,
		size_t const	connectionPoolSize,
		dwConstContextHandle_t const	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]	connectionPoolSize	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,i.e. null or of wrong type
DW_SUCCESS - if server is created successfully.

◆ dwSocketServer_release()

DW_API_PUBLIC dwStatus dwSocketServer_release ( dwSocketServerHandle_t const 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.

Detailed Description

Typedefs

Functions

Typedef Documentation

◆ dwSocketClientHandle_t

◆ dwSocketConnectionHandle_t

◆ dwSocketServerHandle_t

Function Documentation

◆ dwSocketClient_broadcast()

◆ dwSocketClient_connect()

◆ dwSocketClient_initialize()

◆ dwSocketClient_release()

◆ dwSocketConnection_peek()

◆ dwSocketConnection_read()

◆ dwSocketConnection_release()

◆ dwSocketConnection_write()

◆ dwSocketServer_accept()

◆ dwSocketServer_broadcast()

◆ dwSocketServer_initialize()

◆ dwSocketServer_release()