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.The pool is created in the initialization of the SocketClient. 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.The pool is created in the initialization of the SocketClient.

And the sockets which is sent message to are saved by dwSocketClient_connect.

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.

API Group

Init: Yes
Runtime: Yes
De-Init: Yes

◆ 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.

And it will add the connection to the client connection pool if the operation is successful. If it can't connect to the server in the timeout value, it will return.

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.

API Group

Init: Yes
Runtime: No
De-Init: No

◆ 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.

Create a connectionPool to save all clients sockets.

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.

API Group

Init: Yes
Runtime: No
De-Init: No

◆ dwSocketClient_release()

DW_API_PUBLIC dwStatus dwSocketClient_release ( dwSocketClientHandle_t const client )

Terminate a socket client.

It will release the memory of the SocketClient object, close and shutdown the socket.

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.

API Group

Init: Yes
Runtime: No
De-Init: Yes

◆ 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).

It will not delete the message content in the protocol stack.(difference from dwSocketConnection_read)

Parameters

[in,out]	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.

API Group

Init: Yes
Runtime: Yes
De-Init: Yes

◆ 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. It will delete the message content in the protocol stack.(difference from dwSocketConnection_peek)

Parameters

[in,out]	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.

API Group

Init: Yes
Runtime: Yes
De-Init: Yes

◆ dwSocketConnection_release()

DW_API_PUBLIC dwStatus dwSocketConnection_release ( dwSocketConnectionHandle_t const connection )

Terminate a socket connection.

It will release the memory of the SocketConnection object, close and shutdown the socket in the 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.

API Group

Init: Yes
Runtime: No
De-Init: Yes

◆ 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.

API Group

Init: Yes
Runtime: Yes
De-Init: Yes

◆ 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.

It will wait for connections from clients in a timeout ms. If there are connections from clients, it will return directly.

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.

API Group

Init: Yes
Runtime: Yes
De-Init: Yes

◆ 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.

The pool is created in the initialization of the SocketServer. And the sockets which is sent message to are saved by dwSocketServer_accept.

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.

API Group

Init: Yes
Runtime: Yes
De-Init: Yes

◆ 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.

Create a connectionPool to save all client connections of the socket server.

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.

API Group

Init: Yes
Runtime: No
De-Init: No

◆ dwSocketServer_release()

DW_API_PUBLIC dwStatus dwSocketServer_release ( dwSocketServerHandle_t const server )

Terminate a socket server.

It will release the memory of the SocketServer object, close and shutdown the socket.

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.

API Group

Init: Yes
Runtime: No
De-Init: Yes

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()