WebSocket API (client and server) More...

#include <stdlib.h>
#include "core/net.h"
#include "web_socket/web_socket.h"
#include "web_socket/web_socket_auth.h"
#include "web_socket/web_socket_frame.h"
#include "web_socket/web_socket_transport.h"
#include "web_socket/web_socket_misc.h"
#include "str.h"
#include "encoding/base64.h"
#include "debug.h"

Macros
#define	TRACE_LEVEL WEB_SOCKET_TRACE_LEVEL

Functions
error_t	webSocketInit (void)
	WebSocket related initialization. More...

error_t	webSocketRegisterRandCallback (WebSocketRandCallback callback)
	Register RNG callback function. More...

WebSocket *	webSocketOpen (void)
	Create a WebSocket. More...

WebSocket *	webSocketUpgradeSocket (Socket *socket)
	Upgrade a socket to a WebSocket. More...

WebSocket *	webSocketUpgradeSecureSocket (Socket socket, TlsContext tlsContext)
	Upgrade a secure socket to a secure WebSocket. More...

error_t	webSocketRegisterTlsInitCallback (WebSocket *webSocket, WebSocketTlsInitCallback callback)
	Register TLS initialization callback function. More...

error_t	webSocketSetTimeout (WebSocket *webSocket, systime_t timeout)
	Set timeout value for blocking operations. More...

error_t	webSocketSetHost (WebSocket webSocket, const char_t host)
	Set the domain name of the server (for virtual hosting) More...

error_t	webSocketSetOrigin (WebSocket webSocket, const char_t origin)
	Set the origin header field. More...

error_t	webSocketSetSubProtocol (WebSocket webSocket, const char_t subProtocol)
	Set the sub-protocol header field. More...

error_t	webSocketSetAuthInfo (WebSocket webSocket, const char_t username, const char_t *password, uint_t allowedAuthModes)
	Set authentication information. More...

error_t	webSocketBindToInterface (WebSocket webSocket, NetInterface interface)
	Bind the WebSocket to a particular network interface. More...

error_t	webSocketConnect (WebSocket webSocket, const IpAddr serverIpAddr, uint16_t serverPort, const char_t *uri)
	Establish a WebSocket connection. More...

error_t	webSocketSetClientKey (WebSocket webSocket, const char_t clientKey)
	Set client's key. More...

error_t	webSocketParseClientHandshake (WebSocket *webSocket)
	Parse client's handshake. More...

error_t	webSocketSendServerHandshake (WebSocket *webSocket)
	Send server's handshake. More...

error_t	webSocketSendErrorResponse (WebSocket webSocket, uint_t statusCode, const char_t message)
	Send HTTP error response to the client. More...

error_t	webSocketSend (WebSocket webSocket, const void data, size_t length, WebSocketFrameType type, size_t *written)
	Transmit data over the WebSocket connection. More...

error_t	webSocketSendEx (WebSocket webSocket, const void data, size_t length, WebSocketFrameType type, size_t *written, bool_t firstFrag, bool_t lastFrag)
	Transmit data over the WebSocket connection. More...

error_t	webSocketReceive (WebSocket webSocket, void data, size_t size, WebSocketFrameType type, size_t received)
	Receive data from a WebSocket connection. More...

error_t	webSocketReceiveEx (WebSocket webSocket, void data, size_t size, WebSocketFrameType type, size_t received, bool_t firstFrag, bool_t lastFrag)
	Receive data from a WebSocket connection. More...

bool_t	webSocketIsRxReady (WebSocket *webSocket)
	Check whether some data is available in the receive buffer. More...

error_t	webSocketShutdown (WebSocket *webSocket)
	Gracefully close a WebSocket connection. More...

void	webSocketClose (WebSocket *webSocket)
	Close a WebSocket connection. More...

Variables
WebSocket	webSocketTable [WEB_SOCKET_MAX_COUNT]

WebSocketRandCallback	webSockRandCallback

Detailed Description

WebSocket API (client and server)

License

SPDX-License-Identifier: GPL-2.0-or-later

This file is part of CycloneTCP Open.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Author: Oryx Embedded SARL (www.oryx-embedded.com)

Version: 2.4.0

Definition in file web_socket.c.

Macro Definition Documentation

◆ TRACE_LEVEL

#define TRACE_LEVEL WEB_SOCKET_TRACE_LEVEL

Definition at line 32 of file web_socket.c.

Function Documentation

◆ webSocketBindToInterface()

error_t webSocketBindToInterface	(	WebSocket *	webSocket,
		NetInterface *	interface
	)

Bind the WebSocket to a particular network interface.

Parameters

[in]	webSocket	Handle to a WebSocket
[in]	interface	Network interface to be used

Returns: Error code

Definition at line 398 of file web_socket.c.

◆ webSocketClose()

void webSocketClose ( WebSocket * webSocket )

Close a WebSocket connection.

Parameters

[in] webSocket Handle identifying the WebSocket to close

Definition at line 1590 of file web_socket.c.

◆ webSocketConnect()

error_t webSocketConnect	(	WebSocket *	webSocket,
		const IpAddr *	serverIpAddr,
		uint16_t	serverPort,
		const char_t *	uri
	)

Establish a WebSocket connection.

Parameters

[in]	webSocket	Handle to a WebSocket
[in]	serverIpAddr	IP address of the WebSocket server to connect to
[in]	serverPort	TCP port number that will be used to establish the connection
[in]	uri	NULL-terminated string that contains the resource name

Returns: Error code

Definition at line 422 of file web_socket.c.

◆ webSocketInit()

error_t webSocketInit ( void )

WebSocket related initialization.

Returns: Error code

Definition at line 60 of file web_socket.c.

◆ webSocketIsRxReady()

bool_t webSocketIsRxReady ( WebSocket * webSocket )

Check whether some data is available in the receive buffer.

Parameters

[in] webSocket Handle to a WebSocket

Returns: The function returns TRUE if some data is pending and can be read immediately without blocking. Otherwise, FALSE is returned

Definition at line 1445 of file web_socket.c.

◆ webSocketOpen()

WebSocket* webSocketOpen ( void )

Create a WebSocket.

Returns: Handle referencing the new WebSocket

Definition at line 95 of file web_socket.c.

◆ webSocketParseClientHandshake()

error_t webSocketParseClientHandshake ( WebSocket * webSocket )

Parse client's handshake.

Parameters

[in] webSocket Handle that identifies a WebSocket

Returns: Error code

Definition at line 743 of file web_socket.c.

◆ webSocketReceive()

error_t webSocketReceive	(	WebSocket *	webSocket,
		void *	data,
		size_t	size,
		WebSocketFrameType *	type,
		size_t *	received
	)

Receive data from a WebSocket connection.

Parameters

[in]	webSocket	Handle that identifies a WebSocket
[out]	data	Buffer where to store the incoming data
[in]	size	Maximum number of bytes that can be received
[out]	type	Frame type
[out]	received	Number of bytes that have been received

Returns: Error code

Definition at line 1155 of file web_socket.c.

◆ webSocketReceiveEx()

error_t webSocketReceiveEx	(	WebSocket *	webSocket,
		void *	data,
		size_t	size,
		WebSocketFrameType *	type,
		size_t *	received,
		bool_t *	firstFrag,
		bool_t *	lastFrag
	)

Receive data from a WebSocket connection.

Parameters

[in]	webSocket	Handle that identifies a WebSocket
[out]	data	Buffer where to store the incoming data
[in]	size	Maximum number of bytes that can be received
[out]	type	Frame type
[out]	received	Number of bytes that have been received
[out]	firstFrag	First fragment of the message
[out]	lastFrag	Last fragment of the message

Returns: Error code

Definition at line 1178 of file web_socket.c.

◆ webSocketRegisterRandCallback()

error_t webSocketRegisterRandCallback ( WebSocketRandCallback callback )

Register RNG callback function.

Parameters

[in] callback RNG callback function

Returns: Error code

Definition at line 76 of file web_socket.c.

◆ webSocketRegisterTlsInitCallback()

error_t webSocketRegisterTlsInitCallback	(	WebSocket *	webSocket,
		WebSocketTlsInitCallback	callback
	)

Register TLS initialization callback function.

Parameters

[in]	webSocket	Handle that identifies a WebSocket
[in]	callback	TLS initialization callback function

Returns: Error code

Definition at line 233 of file web_socket.c.

◆ webSocketSend()

error_t webSocketSend	(	WebSocket *	webSocket,
		const void *	data,
		size_t	length,
		WebSocketFrameType	type,
		size_t *	written
	)

Transmit data over the WebSocket connection.

Parameters

[in]	webSocket	Handle that identifies a WebSocket
[in]	data	Pointer to a buffer containing the data to be transmitted
[in]	length	Number of data bytes to send
[in]	type	Frame type
[out]	written	Actual number of bytes written (optional parameter)

Returns: Error code

Definition at line 970 of file web_socket.c.

◆ webSocketSendErrorResponse()

error_t webSocketSendErrorResponse	(	WebSocket *	webSocket,
		uint_t	statusCode,
		const char_t *	message
	)

Send HTTP error response to the client.

Parameters

[in]	webSocket	Handle that identifies a WebSocket
[in]	statusCode	HTTP status code
[in]	message	Text message

Returns: Error code

Definition at line 895 of file web_socket.c.

◆ webSocketSendEx()

error_t webSocketSendEx	(	WebSocket *	webSocket,
		const void *	data,
		size_t	length,
		WebSocketFrameType	type,
		size_t *	written,
		bool_t	firstFrag,
		bool_t	lastFrag
	)

Transmit data over the WebSocket connection.

Parameters

[in]	webSocket	Handle that identifies a WebSocket
[in]	data	Pointer to a buffer containing the data to be transmitted
[in]	length	Number of data bytes to send
[in]	type	Frame type
[out]	written	Actual number of bytes written (optional parameter)
[in]	firstFrag	First fragment of the message
[in]	lastFrag	Last fragment of the message

Definition at line 991 of file web_socket.c.

◆ webSocketSendServerHandshake()

error_t webSocketSendServerHandshake ( WebSocket * webSocket )

Send server's handshake.

Parameters

[in] webSocket Handle that identifies a WebSocket

Returns: Error code

Definition at line 832 of file web_socket.c.

◆ webSocketSetAuthInfo()

error_t webSocketSetAuthInfo	(	WebSocket *	webSocket,
		const char_t *	username,
		const char_t *	password,
		uint_t	allowedAuthModes
	)

Set authentication information.

Parameters

[in]	webSocket	Handle to a WebSocket
[in]	username	NULL-terminated string containing the user name to be used
[in]	password	NULL-terminated string containing the password to be used
[in]	allowedAuthModes	Logic OR of allowed HTTP authentication schemes

Returns: Error code

Definition at line 359 of file web_socket.c.

◆ webSocketSetClientKey()

error_t webSocketSetClientKey	(	WebSocket *	webSocket,
		const char_t *	clientKey
	)

Set client's key.

Parameters

[in]	webSocket	Handle to a WebSocket
[in]	clientKey	NULL-terminated string that holds the client's key

Returns: Error code

Definition at line 677 of file web_socket.c.

◆ webSocketSetHost()

error_t webSocketSetHost	(	WebSocket *	webSocket,
		const char_t *	host
	)

Set the domain name of the server (for virtual hosting)

Parameters

[in]	webSocket	Handle to a WebSocket
[in]	host	NULL-terminated string containing the hostname

Returns: Error code

Definition at line 282 of file web_socket.c.

◆ webSocketSetOrigin()

error_t webSocketSetOrigin	(	WebSocket *	webSocket,
		const char_t *	origin
	)

Set the origin header field.

Parameters

[in]	webSocket	Handle to a WebSocket
[in]	origin	NULL-terminated string containing the origin

Returns: Error code

Definition at line 307 of file web_socket.c.

◆ webSocketSetSubProtocol()

error_t webSocketSetSubProtocol	(	WebSocket *	webSocket,
		const char_t *	subProtocol
	)

Set the sub-protocol header field.

Parameters

[in]	webSocket	Handle to a WebSocket
[in]	subProtocol	NULL-terminated string containing the sub-protocol

Returns: Error code

Definition at line 332 of file web_socket.c.

◆ webSocketSetTimeout()

error_t webSocketSetTimeout	(	WebSocket *	webSocket,
		systime_t	timeout
	)

Set timeout value for blocking operations.

Parameters

[in]	webSocket	Handle to a WebSocket
[in]	timeout	Maximum time to wait

Returns: Error code

Definition at line 257 of file web_socket.c.

◆ webSocketShutdown()

error_t webSocketShutdown ( WebSocket * webSocket )

Gracefully close a WebSocket connection.

Parameters

[in] webSocket Handle to a WebSocket

Definition at line 1470 of file web_socket.c.

◆ webSocketUpgradeSecureSocket()

WebSocket* webSocketUpgradeSecureSocket	(	Socket *	socket,
		TlsContext *	tlsContext
	)

Upgrade a secure socket to a secure WebSocket.

Parameters

[in]	socket	Handle referencing the socket
[in]	tlsContext	Pointer to the TLS context

Returns: Handle referencing the new WebSocket

Definition at line 194 of file web_socket.c.

◆ webSocketUpgradeSocket()

WebSocket* webSocketUpgradeSocket ( Socket * socket )

Upgrade a socket to a WebSocket.

Parameters

[in] socket Handle referencing the socket

Returns: Handle referencing the new WebSocket

Definition at line 155 of file web_socket.c.

Variable Documentation

◆ webSocketTable

WebSocket webSocketTable[WEB_SOCKET_MAX_COUNT]

Definition at line 50 of file web_socket.c.

◆ webSockRandCallback

WebSocketRandCallback webSockRandCallback

Definition at line 52 of file web_socket.c.

Macros

Functions

Variables

Detailed Description

License

Macro Definition Documentation

◆ TRACE_LEVEL

Function Documentation

◆ webSocketBindToInterface()

◆ webSocketClose()

◆ webSocketConnect()

◆ webSocketInit()

◆ webSocketIsRxReady()

◆ webSocketOpen()

◆ webSocketParseClientHandshake()

◆ webSocketReceive()

◆ webSocketReceiveEx()

◆ webSocketRegisterRandCallback()

◆ webSocketRegisterTlsInitCallback()

◆ webSocketSend()

◆ webSocketSendErrorResponse()

◆ webSocketSendEx()

◆ webSocketSendServerHandshake()

◆ webSocketSetAuthInfo()

◆ webSocketSetClientKey()

◆ webSocketSetHost()

◆ webSocketSetOrigin()

◆ webSocketSetSubProtocol()

◆ webSocketSetTimeout()

◆ webSocketShutdown()

◆ webSocketUpgradeSecureSocket()

◆ webSocketUpgradeSocket()

Variable Documentation

◆ webSocketTable

◆ webSockRandCallback