Secure Sockets Interface. More...

#include <stdint.h>
#include <stddef.h>
#include "iot_secure_sockets_config.h"
#include "iot_secure_sockets_config_defaults.h"
#include "iot_secure_sockets_wrapper_metrics.h"
#include "iot_lib_init.h"

Data Structures
struct	SocketsSockaddr_t
	Socket address. More...

Macros
#define	Socklen_t uint32_t
	The "size_t" of secure sockets. More...

#define	SOCKETS_INVALID_SOCKET ( ( Socket_t ) ~0U )
	Assigned to an Socket_t variable when the socket is not valid.

#define	securesocketsMAX_DNS_NAME_LENGTH ( 253 )
	Maximum length of an ASCII DNS name.

#define	securesocketsDEFAULT_TLS_DESTINATION_PORT 443
	Well-known port numbers.

#define	socketsAWS_IOT_ALPN_MQTT "x-amzn-mqtt-ca"
	AWS IoT ALPN protocol name for MQTT over TLS on server port 443.

#define	SOCKETS_htonl(usIn) ( ( uint32_t ) ( usIn ) )
	Convert an unsigned thirty-two-bit value from host endianness to network endianness. More...

#define	SOCKETS_ntohl(usIn) SOCKETS_htonl( usIn )
	Convert an unsigned thirty-two-bit value from network endianness to host endianness. More...

#define	SOCKETS_htons(usIn) ( ( uint16_t ) ( usIn ) )
	Convert an unsigned sixteen-bit value from host endianness to network endianness. More...

#define	SOCKETS_ntohs(usIn) SOCKETS_htons( usIn )
	Convert an unsigned sixteen-bit value from network endianness to host endianness. More...

#define	SOCKETS_inet_addr_quick(ucOctet0, ucOctet1, ucOctet2, ucOctet3)
	Convert an IP address expressed as four separate numeric octets into a an IP address expressed as a 32-bit number in network byte order (for example 192, 168, 0, 100) More...

#define	SOCKETS_inet_ntoa(ulIPAddress, pucBuffer)
	Convert an IP address expressed as a 32-bit number in network byte order to a string in decimal dot notation. (for example "192.168.0.100") More...

SocketsErrors
Error codes returned by the SOCKETS API. Note that SOCKETS API may also propagate port-specific error codes when they are more descriptive. See your port's error codes for more details. PORT_SPECIFIC_LINK
#define	SOCKETS_ERROR_NONE ( 0 )

#define	SOCKETS_SOCKET_ERROR ( -1 )

#define	SOCKETS_EWOULDBLOCK ( -11 )

#define	SOCKETS_ENOMEM ( -12 )

#define	SOCKETS_EINVAL ( -22 )

#define	SOCKETS_ENOPROTOOPT ( -109 )

#define	SOCKETS_ENOTCONN ( -126 )

#define	SOCKETS_EISCONN ( -127 )

#define	SOCKETS_ECLOSED ( -128 )

#define	SOCKETS_TLS_INIT_ERROR ( -1001 )

#define	SOCKETS_TLS_HANDSHAKE_ERROR ( -1002 )

#define	SOCKETS_TLS_SERVER_UNVERIFIED ( -1003 )

#define	SOCKETS_TLS_RECV_ERROR ( -1004 )

#define	SOCKETS_TLS_SEND_ERROR ( -1005 )

#define	SOCKETS_PERIPHERAL_RESET ( -1006 )

SocketDomains
Options for the lDomain parameter of SOCKETS_Socket() function. These select the protocol family to be used for communication.
#define	SOCKETS_AF_INET ( 2 )

#define	SOCKETS_PF_INET SOCKETS_AF_INET

#define	SOCKETS_AF_INET6 ( 10 )

SocketTypes
Options for the lType parameter of SOCKETS_Socket() function. These specify the communication semantics.
#define	SOCKETS_SOCK_DGRAM ( 2 )

#define	SOCKETS_SOCK_STREAM ( 1 )

Protocols
Options for the lProtocol parameter of SOCKETS_Socket() function.
#define	SOCKETS_IPPROTO_UDP ( 17 )

#define	SOCKETS_IPPROTO_TCP ( 6 )

SetSockOptOptions
Options for lOptionName in SOCKETS_SetSockOpt().
#define	SOCKETS_SO_RCVTIMEO ( 0 )

#define	SOCKETS_SO_SNDTIMEO ( 1 )

#define	SOCKETS_SO_SNDBUF ( 4 )

#define	SOCKETS_SO_RCVBUF ( 5 )

#define	SOCKETS_SO_SERVER_NAME_INDICATION ( 6 )

#define	SOCKETS_SO_TRUSTED_SERVER_CERTIFICATE ( 7 )

#define	SOCKETS_SO_REQUIRE_TLS ( 8 )

#define	SOCKETS_SO_NONBLOCK ( 9 )

#define	SOCKETS_SO_ALPN_PROTOCOLS ( 10 )

#define	SOCKETS_SO_WAKEUP_CALLBACK ( 17 )

#define	SOCKETS_SO_TCPKEEPALIVE ( 18 )

#define	SOCKETS_SO_TCPKEEPALIVE_INTERVAL ( 19 )

#define	SOCKETS_SO_TCPKEEPALIVE_COUNT ( 20 )

#define	SOCKETS_SO_TCPKEEPALIVE_IDLE_TIME ( 21 )

ShutdownFlags
Options for the ulHow parameter in SOCKETS_Shutdown().
#define	SOCKETS_SHUT_RD ( 0 )

#define	SOCKETS_SHUT_WR ( 1 )

#define	SOCKETS_SHUT_RDWR ( 2 )

Typedefs
typedef struct xSOCKET *	Socket_t
	Socket handle data type.

Functions
BaseType_t	SOCKETS_Init (void)
	Secure Sockets library initialization function. More...

Socket_t	SOCKETS_Socket (int32_t lDomain, int32_t lType, int32_t lProtocol)
	Creates a TCP socket. More...

int32_t	SOCKETS_Bind (Socket_t xSocket, SocketsSockaddr_t *pxAddress, Socklen_t xAddressLength)
	Bind a TCP socket. More...

int32_t	SOCKETS_Connect (Socket_t xSocket, SocketsSockaddr_t *pxAddress, Socklen_t xAddressLength)
	Connects the socket to the specified IP address and port. More...

int32_t	SOCKETS_Recv (Socket_t xSocket, void *pvBuffer, size_t xBufferLength, uint32_t ulFlags)
	Receive data from a TCP socket. More...

int32_t	SOCKETS_Send (Socket_t xSocket, const void *pvBuffer, size_t xDataLength, uint32_t ulFlags)
	Transmit data to the remote socket. More...

int32_t	SOCKETS_Shutdown (Socket_t xSocket, uint32_t ulHow)
	Closes all or part of a full-duplex connection on the socket. More...

int32_t	SOCKETS_Close (Socket_t xSocket)
	Closes the socket and frees the related resources. More...

int32_t	SOCKETS_SetSockOpt (Socket_t xSocket, int32_t lLevel, int32_t lOptionName, const void *pvOptionValue, size_t xOptionLength)
	Manipulates the options for the socket. More...

uint32_t	SOCKETS_GetHostByName (const char *pcHostName)
	Resolve a host name using Domain Name Service. More...

Detailed Description

Secure Sockets Interface.

Secure sockets is a portable layer for establishing a TCP/IP connection, with the option of using TLS.

Secure sockets is based on the Berkeley sockets API. A few difference general differences between Berkeley and SOCKETS are:

SOCKETS has additional socket options to enable TLS, server name indication, and per-socket root of trust server certificates. See SOCKETS_SetSockOpt() for more information.
SOCKETS API return an error code, rather than returning -1 and setting a global errno value.

Macro Definition Documentation

◆ Socklen_t

#define Socklen_t uint32_t

The "size_t" of secure sockets.

This type is used for compatibility with the expected Berkeley sockets naming.

◆ SOCKETS_ERROR_NONE

#define SOCKETS_ERROR_NONE ( 0 )

No error.

◆ SOCKETS_SOCKET_ERROR

#define SOCKETS_SOCKET_ERROR ( -1 )

Catch-all sockets error code.

◆ SOCKETS_EWOULDBLOCK

#define SOCKETS_EWOULDBLOCK ( -11 )

A resource is temporarily unavailable.

◆ SOCKETS_ENOMEM

#define SOCKETS_ENOMEM ( -12 )

Memory allocation failed.

◆ SOCKETS_EINVAL

#define SOCKETS_EINVAL ( -22 )

Invalid argument.

◆ SOCKETS_ENOPROTOOPT

#define SOCKETS_ENOPROTOOPT ( -109 )

A bad option was specified .

◆ SOCKETS_ENOTCONN

#define SOCKETS_ENOTCONN ( -126 )

The supplied socket is not connected.

◆ SOCKETS_EISCONN

#define SOCKETS_EISCONN ( -127 )

The supplied socket is already connected.

◆ SOCKETS_ECLOSED

#define SOCKETS_ECLOSED ( -128 )

The supplied socket has already been closed.

◆ SOCKETS_TLS_INIT_ERROR

#define SOCKETS_TLS_INIT_ERROR ( -1001 )

TLS initialization failed.

◆ SOCKETS_TLS_HANDSHAKE_ERROR

#define SOCKETS_TLS_HANDSHAKE_ERROR ( -1002 )

TLS handshake failed.

◆ SOCKETS_TLS_SERVER_UNVERIFIED

#define SOCKETS_TLS_SERVER_UNVERIFIED ( -1003 )

A connection was made but the server could not be verified. It is recommended that the socket be closed.

◆ SOCKETS_TLS_RECV_ERROR

#define SOCKETS_TLS_RECV_ERROR ( -1004 )

TLS receive operation failed.

◆ SOCKETS_TLS_SEND_ERROR

#define SOCKETS_TLS_SEND_ERROR ( -1005 )

TLS send operation failed.

◆ SOCKETS_PERIPHERAL_RESET

#define SOCKETS_PERIPHERAL_RESET ( -1006 )

Communications peripheral has been reset.

◆ SOCKETS_AF_INET

#define SOCKETS_AF_INET ( 2 )

IPv4 Internet Protocols.

◆ SOCKETS_PF_INET

#define SOCKETS_PF_INET SOCKETS_AF_INET

IPv4 Internet Protocol.

◆ SOCKETS_AF_INET6

#define SOCKETS_AF_INET6 ( 10 )

IPv6 Internet Protocols. This option is currently not supported.

◆ SOCKETS_SOCK_DGRAM

#define SOCKETS_SOCK_DGRAM ( 2 )

Datagram.

◆ SOCKETS_SOCK_STREAM

#define SOCKETS_SOCK_STREAM ( 1 )

Byte-stream.

◆ SOCKETS_IPPROTO_UDP

#define SOCKETS_IPPROTO_UDP ( 17 )

UDP. This option is currently not supported.

◆ SOCKETS_IPPROTO_TCP

#define SOCKETS_IPPROTO_TCP ( 6 )

TCP.

◆ SOCKETS_SO_RCVTIMEO

#define SOCKETS_SO_RCVTIMEO ( 0 )

Set the receive timeout.

◆ SOCKETS_SO_SNDTIMEO

#define SOCKETS_SO_SNDTIMEO ( 1 )

Set the send timeout.

◆ SOCKETS_SO_SNDBUF

#define SOCKETS_SO_SNDBUF ( 4 )

Set the size of the send buffer (TCP only).

◆ SOCKETS_SO_RCVBUF

#define SOCKETS_SO_RCVBUF ( 5 )

Set the size of the receive buffer (TCP only).

◆ SOCKETS_SO_SERVER_NAME_INDICATION

#define SOCKETS_SO_SERVER_NAME_INDICATION ( 6 )

Toggle client use of TLS SNI.

◆ SOCKETS_SO_TRUSTED_SERVER_CERTIFICATE

#define SOCKETS_SO_TRUSTED_SERVER_CERTIFICATE ( 7 )

Override default TLS server certificate trust. Must be PEM encoded and length must include null terminator.

◆ SOCKETS_SO_REQUIRE_TLS

#define SOCKETS_SO_REQUIRE_TLS ( 8 )

Toggle client enforcement of TLS.

◆ SOCKETS_SO_NONBLOCK

#define SOCKETS_SO_NONBLOCK ( 9 )

Socket is nonblocking.

◆ SOCKETS_SO_ALPN_PROTOCOLS

#define SOCKETS_SO_ALPN_PROTOCOLS ( 10 )

Application protocol list to be included in TLS ClientHello.

◆ SOCKETS_SO_WAKEUP_CALLBACK

#define SOCKETS_SO_WAKEUP_CALLBACK ( 17 )

Set the callback to be called whenever there is data available on the socket for reading.

◆ SOCKETS_SO_TCPKEEPALIVE

#define SOCKETS_SO_TCPKEEPALIVE ( 18 )

Enable or Disable TCP keep-alive functionality.

◆ SOCKETS_SO_TCPKEEPALIVE_INTERVAL

#define SOCKETS_SO_TCPKEEPALIVE_INTERVAL ( 19 )

Set the time in seconds between individual TCP keep-alive probes.

◆ SOCKETS_SO_TCPKEEPALIVE_COUNT

#define SOCKETS_SO_TCPKEEPALIVE_COUNT ( 20 )

Set the maximum number of keep-alive probes TCP should send before dropping the connection.

◆ SOCKETS_SO_TCPKEEPALIVE_IDLE_TIME

#define SOCKETS_SO_TCPKEEPALIVE_IDLE_TIME ( 21 )

Set the time in seconds for which the connection needs to remain idle before TCP starts sending keep-alive probes.

◆ SOCKETS_SHUT_RD

#define SOCKETS_SHUT_RD ( 0 )

No further receives.

◆ SOCKETS_SHUT_WR

#define SOCKETS_SHUT_WR ( 1 )

No further sends.

◆ SOCKETS_SHUT_RDWR

#define SOCKETS_SHUT_RDWR ( 2 )

No further send or receive.

◆ SOCKETS_htonl

#define SOCKETS_htonl ( usIn ) ( ( uint32_t ) ( usIn ) )

Convert an unsigned thirty-two-bit value from host endianness to network endianness.

Parameters

[in] usIn The unsigned thirty-two-bit value to convert.

◆ SOCKETS_ntohl

#define SOCKETS_ntohl ( usIn ) SOCKETS_htonl( usIn )

Convert an unsigned thirty-two-bit value from network endianness to host endianness.

Parameters

[in] usIn The unsigned thirty-two-bit value to convert.

◆ SOCKETS_htons

#define SOCKETS_htons ( usIn ) ( ( uint16_t ) ( usIn ) )

Convert an unsigned sixteen-bit value from host endianness to network endianness.

Parameters

[in] usIn The unsigned sixteen-bit value to convert.

◆ SOCKETS_ntohs

#define SOCKETS_ntohs ( usIn ) SOCKETS_htons( usIn )

Convert an unsigned sixteen-bit value from network endianness to host endianness.

Parameters

[in] usIn The unsigned sixteen-bit value to convert.

◆ SOCKETS_inet_addr_quick

#define SOCKETS_inet_addr_quick	(	ucOctet0,
		ucOctet1,
		ucOctet2,
		ucOctet3
	)

Value:

( ( ( ( uint32_t ) ( ucOctet0 ) ) << 24UL ) |                             \
      ( ( ( uint32_t ) ( ucOctet1 ) ) << 16UL ) |                             \
      ( ( ( uint32_t ) ( ucOctet2 ) ) << 8UL ) |                              \
      ( ( uint32_t ) ( ucOctet3 ) ) )

Convert an IP address expressed as four separate numeric octets into a an IP address expressed as a 32-bit number in network byte order (for example 192, 168, 0, 100)

Parameters

[in]	ucOctet0	0th IP Octet
[in]	ucOctet1	1st IP Octet
[in]	ucOctet2	2nd IP Octet
[in]	ucOctet3	3rd IP Octet

◆ SOCKETS_inet_ntoa

#define SOCKETS_inet_ntoa	(	ulIPAddress,
		pucBuffer
	)

Value:

sprintf( ( char * ) ( pucBuffer ), "%u.%u.%u.%u",                 \
             ( ( unsigned ) ( ( ulIPAddress ) >> 24 ) ),              \
             ( ( unsigned ) ( ( ( ulIPAddress ) >> 16 ) & 0xffUL ) ), \
             ( ( unsigned ) ( ( ( ulIPAddress ) >> 8 ) & 0xffUL ) ),  \
             ( ( unsigned ) ( ( ulIPAddress ) & 0xffUL ) ) )

Convert an IP address expressed as a 32-bit number in network byte order to a string in decimal dot notation. (for example "192.168.0.100")

Parameters

[in]	ulIPAddress	An IP address expressed as a 32-bit value in network byte order.
[in]	pucBuffer	A pointer to a buffer into which the IP address will be written in decimal dot notation.

Function Documentation

◆ SOCKETS_Init()

BaseType_t SOCKETS_Init ( void )

Secure Sockets library initialization function.

This function does general initialization and setup. It must be called once and only once before calling any other function.

Returns

pdPASS if everything succeeds
pdFAIL otherwise.

◆ SOCKETS_Socket()

Socket_t SOCKETS_Socket	(	int32_t	lDomain,
		int32_t	lType,
		int32_t	lProtocol
	)

Creates a TCP socket.

See the FreeRTOS+TCP networking tutorial for more information on TCP sockets.

See the Berkeley Sockets API in wikipedia

See also: SOCKETS_Close()

Parameters

[in]	lDomain	Must be set to SOCKETS_AF_INET. See SocketDomains.
[in]	lType	Set to SOCKETS_SOCK_STREAM to create a TCP socket. No other value is valid. See SocketTypes.
[in]	lProtocol	Set to SOCKETS_IPPROTO_TCP to create a TCP socket. No other value is valid. See Protocols.

Returns

If a socket is created successfully, then the socket handle is returned
SOCKETS_INVALID_SOCKET is returned if an error occurred.

◆ SOCKETS_Bind()

int32_t SOCKETS_Bind	(	Socket_t	xSocket,
		SocketsSockaddr_t *	pxAddress,
		Socklen_t	xAddressLength
	)

Bind a TCP socket.

See the FreeRTOS+TCP networking tutorial for more information on TCP sockets.

See the Berkeley Sockets API in wikipedia

See also: SOCKETS_Bind() A pre-configured source port allows customers to bind to the specified local port instead of ephemeral port for security and packet filter reasons.

Limitations:

i. The caller of SOCKETS_Bind() API should make sure the socket address has the correct local IP address for the interface. ii. Some source ports may be unavailable depending on the TCP/IP stack implementation.

NOTE: If the SOCKETS_Bind() API binds to a source port in ephemeral port range, and the caller calls SOCKETS_Bind() API
      before SOCKETS_Connect() API, then a conflict of source port arises as another TCP connection
      may pick the the same chosen port via tcp_new_port() API ( by scanning its internal TCP connection list )

Parameters

[in]	xSocket	The handle of the socket to which specified address to be bound.
[in]	pxAddress	A pointer to a SocketsSockaddr_t structure that contains the address and port to be bound to the socket.
[in]	xAddressLength	Should be set to sizeof( SocketsSockaddr_t ).

Returns

If the bind was successful then SOCKETS_ERROR_NONE is returned.
If an error occurred, a negative value is returned. SocketsErrors

◆ SOCKETS_Connect()

int32_t SOCKETS_Connect	(	Socket_t	xSocket,
		SocketsSockaddr_t *	pxAddress,
		Socklen_t	xAddressLength
	)

Connects the socket to the specified IP address and port.

The socket must first have been successfully created by a call to SOCKETS_Socket().

Note: To create a secure socket, SOCKETS_SetSockOpt() should be called with the SOCKETS_SO_REQUIRE_TLS option before SOCKETS_Connect() is called.

If this function returns an error the socket is considered invalid.

Warning: SOCKETS_Connect() is not safe to be called on the same socket from multiple threads simultaneously with SOCKETS_Connect(), SOCKETS_SetSockOpt(), SOCKETS_Shutdown(), SOCKETS_Close().

See the Berkeley Sockets API in wikipedia

Parameters

[in]	xSocket	The handle of the socket to be connected.
[in]	pxAddress	A pointer to a SocketsSockaddr_t structure that contains the the address to connect the socket to.
[in]	xAddressLength	Should be set to sizeof( SocketsSockaddr_t ).

Returns

SOCKETS_ERROR_NONE if a connection is established.
If an error occurred, a negative value is returned. SocketsErrors

◆ SOCKETS_Recv()

int32_t SOCKETS_Recv	(	Socket_t	xSocket,
		void *	pvBuffer,
		size_t	xBufferLength,
		uint32_t	ulFlags
	)

Receive data from a TCP socket.

The socket must have already been created using a call to SOCKETS_Socket() and connected to a remote socket using SOCKETS_Connect().

See the Berkeley Sockets API in wikipedia

Parameters

[in]	xSocket	The handle of the socket from which data is being received.
[out]	pvBuffer	The buffer into which the received data will be placed.
[in]	xBufferLength	The maximum number of bytes which can be received. pvBuffer must be at least xBufferLength bytes long.
[in]	ulFlags	Not currently used. Should be set to 0.

Returns

If the receive was successful then the number of bytes received (placed in the buffer pointed to by pvBuffer) is returned.
If a timeout occurred before data could be received then 0 is returned (timeout is set using SOCKETS_SO_RCVTIMEO).
If an error occurred, a negative value is returned. SocketsErrors

◆ SOCKETS_Send()

int32_t SOCKETS_Send	(	Socket_t	xSocket,
		const void *	pvBuffer,
		size_t	xDataLength,
		uint32_t	ulFlags
	)

Transmit data to the remote socket.

The socket must have already been created using a call to SOCKETS_Socket() and connected to a remote socket using SOCKETS_Connect().

See the Berkeley Sockets API in wikipedia

Parameters

[in]	xSocket	The handle of the sending socket.
[in]	pvBuffer	The buffer containing the data to be sent.
[in]	xDataLength	The length of the data to be sent.
[in]	ulFlags	Not currently used. Should be set to 0.

Returns

On success, the number of bytes actually sent is returned.
If an error occurred, a negative value is returned. SocketsErrors

◆ SOCKETS_Shutdown()

int32_t SOCKETS_Shutdown	(	Socket_t	xSocket,
		uint32_t	ulHow
	)

Closes all or part of a full-duplex connection on the socket.

Disable reads and writes on a connected TCP socket. A connected TCP socket must be gracefully shut down before it can be closed.

See the Berkeley Sockets API in wikipedia

Warning: SOCKETS_Shutdown() is not safe to be called on the same socket from multiple threads simultaneously with SOCKETS_Connect(), SOCKETS_SetSockOpt(), SOCKETS_Shutdown(), SOCKETS_Close().

Parameters

[in]	xSocket	The handle of the socket to shutdown.
[in]	ulHow	SOCKETS_SHUT_RD, SOCKETS_SHUT_WR or SOCKETS_SHUT_RDWR. ShutdownFlags

Returns

If the operation was successful, 0 is returned.
If an error occurred, a negative value is returned. SocketsErrors

◆ SOCKETS_Close()

int32_t SOCKETS_Close ( Socket_t xSocket )

Closes the socket and frees the related resources.

A socket should be shutdown gracefully before it is closed, and cannot be used after it has been closed.

See the Berkeley Sockets API in wikipedia

Warning: SOCKETS_Close() is not safe to be called on the same socket from multiple threads simultaneously with SOCKETS_Connect(), SOCKETS_SetSockOpt(), SOCKETS_Shutdown(), SOCKETS_Close().

Parameters

[in] xSocket The handle of the socket to close.

Returns

On success, 0 is returned.
If an error occurred, a negative value is returned. SocketsErrors

◆ SOCKETS_SetSockOpt()

int32_t SOCKETS_SetSockOpt	(	Socket_t	xSocket,
		int32_t	lLevel,
		int32_t	lOptionName,
		const void *	pvOptionValue,
		size_t	xOptionLength
	)

Manipulates the options for the socket.

See the Berkeley Sockets API in wikipedia

Parameters

[in]	xSocket	The handle of the socket to set the option for.
[in]	lLevel	Not currently used. Should be set to 0.
[in]	lOptionName	See SetSockOptOptions.
[in]	pvOptionValue	A buffer containing the value of the option to set.
[in]	xOptionLength	The length of the buffer pointed to by pvOptionValue.

Warning: SOCKETS_Close() is not safe to be called on the same socket from multiple threads simultaneously with SOCKETS_Connect(), SOCKETS_SetSockOpt(), SOCKETS_Shutdown(), SOCKETS_Close().

Note: Socket option support and possible values vary by port. Please see PORT_SPECIFIC_LINK to check the valid options and limitations of your device.

Berkeley Socket Options
- SOCKETS_SO_RCVTIMEO
  - Sets the receive timeout
  - pvOptionValue (TickType_t) is the number of milliseconds that the receive function should wait before timing out.
  - Setting pvOptionValue = 0 causes receive to wait forever.
  - See PORT_SPECIFIC_LINK for device limitations.
- SOCKETS_SO_SNDTIMEO
  - Sets the send timeout
  - pvOptionValue (TickType_t) is the number of milliseconds that the send function should wait before timing out.
  - Setting pvOptionValue = 0 causes send to wait forever.
  - See PORT_SPECIFIC_LINK for device limitations.
Non-Standard Options
- SOCKETS_SO_NONBLOCK
  - Makes a socket non-blocking.
  - Non-blocking connect is not supported - socket option should be called after connect.
  - pvOptionValue is ignored for this option.
- SOCKETS_SO_WAKEUP_CALLBACK
  - Set the callback to be called whenever there is data available on the socket for reading
  - This option provides an asynchronous way to handle received data
  - pvOptionValue is a pointer to the callback function
  - See PORT_SPECIFIC_LINK for device limitations.
Security Sockets Options
- SOCKETS_SO_REQUIRE_TLS
  - Use TLS for all connect, send, and receive on this socket.
  - This socket options MUST be set for TLS to be used, even if other secure socket options are set.
  - This socket option should be set before SOCKETS_Connect() is called.
  - pvOptionValue is ignored for this option.
- SOCKETS_SO_TRUSTED_SERVER_CERTIFICATE
  - Set the root of trust server certificate for the socket.
  - This socket option only takes effect if SOCKETS_SO_REQUIRE_TLS is also set. If SOCKETS_SO_REQUIRE_TLS is not set, this option will be ignored.
  - pvOptionValue is a pointer to the formatted server certificate. TODO: Link to description of how to format certificates with
  - xOptionLength (BaseType_t) is the length of the certificate in bytes.
- SOCKETS_SO_SERVER_NAME_INDICATION
  - Use Server Name Indication (SNI)
  - This socket option only takes effect if SOCKETS_SO_REQUIRE_TLS is also set. If SOCKETS_SO_REQUIRE_TLS is not set, this option will be ignored.
  - pvOptionValue is a pointer to a string containing the hostname
  - xOptionLength is the length of the hostname string in bytes.
- SOCKETS_SO_ALPN_PROTOCOLS
  - Negotiate an application protocol along with TLS.
  - The ALPN list is expressed as an array of NULL-terminated ANSI strings.
  - xOptionLength is the number of items in the array.
- SOCKETS_SO_TCPKEEPALIVE
  - Enable or disable the TCP keep-alive functionality.
  - pvOptionValue is the value to enable or disable Keepalive.
- SOCKETS_SO_TCPKEEPALIVE_INTERVAL
  - Set the time in seconds between individual TCP keep-alive probes.
  - pvOptionValue is the time in seconds.
- SOCKETS_SO_TCPKEEPALIVE_COUNT
  - Set the maximum number of keep-alive probes TCP should send before dropping the connection.
  - pvOptionValue is the maximum number of keep-alive probes.
- SOCKETS_SO_TCPKEEPALIVE_IDLE_TIME
  - Set the time in seconds for which the connection needs to remain idle before TCP starts sending keep-alive probes.
  - pvOptionValue is the time in seconds.

Returns

On success, 0 is returned.
If an error occurred, a negative value is returned. SocketsErrors

◆ SOCKETS_GetHostByName()

uint32_t SOCKETS_GetHostByName ( const char * pcHostName )

Resolve a host name using Domain Name Service.

See the Berkeley Sockets API in wikipedia

Parameters

[in] pcHostName The host name to resolve.

Returns

The IPv4 address of the specified host.
If an error has occurred, 0 is returned.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ Socklen_t

◆ SOCKETS_ERROR_NONE

◆ SOCKETS_SOCKET_ERROR

◆ SOCKETS_EWOULDBLOCK

◆ SOCKETS_ENOMEM

◆ SOCKETS_EINVAL

◆ SOCKETS_ENOPROTOOPT

◆ SOCKETS_ENOTCONN

◆ SOCKETS_EISCONN

◆ SOCKETS_ECLOSED

◆ SOCKETS_TLS_INIT_ERROR

◆ SOCKETS_TLS_HANDSHAKE_ERROR

◆ SOCKETS_TLS_SERVER_UNVERIFIED

◆ SOCKETS_TLS_RECV_ERROR

◆ SOCKETS_TLS_SEND_ERROR

◆ SOCKETS_PERIPHERAL_RESET

◆ SOCKETS_AF_INET

◆ SOCKETS_PF_INET

◆ SOCKETS_AF_INET6

◆ SOCKETS_SOCK_DGRAM

◆ SOCKETS_SOCK_STREAM

◆ SOCKETS_IPPROTO_UDP

◆ SOCKETS_IPPROTO_TCP

◆ SOCKETS_SO_RCVTIMEO

◆ SOCKETS_SO_SNDTIMEO

◆ SOCKETS_SO_SNDBUF

◆ SOCKETS_SO_RCVBUF

◆ SOCKETS_SO_SERVER_NAME_INDICATION

◆ SOCKETS_SO_TRUSTED_SERVER_CERTIFICATE

◆ SOCKETS_SO_REQUIRE_TLS

◆ SOCKETS_SO_NONBLOCK

◆ SOCKETS_SO_ALPN_PROTOCOLS

◆ SOCKETS_SO_WAKEUP_CALLBACK

◆ SOCKETS_SO_TCPKEEPALIVE

◆ SOCKETS_SO_TCPKEEPALIVE_INTERVAL

◆ SOCKETS_SO_TCPKEEPALIVE_COUNT

◆ SOCKETS_SO_TCPKEEPALIVE_IDLE_TIME

◆ SOCKETS_SHUT_RD

◆ SOCKETS_SHUT_WR

◆ SOCKETS_SHUT_RDWR

◆ SOCKETS_htonl

◆ SOCKETS_ntohl

◆ SOCKETS_htons

◆ SOCKETS_ntohs

◆ SOCKETS_inet_addr_quick

◆ SOCKETS_inet_ntoa

Function Documentation

◆ SOCKETS_Init()

◆ SOCKETS_Socket()

◆ SOCKETS_Bind()

◆ SOCKETS_Connect()

◆ SOCKETS_Recv()

◆ SOCKETS_Send()

◆ SOCKETS_Shutdown()

◆ SOCKETS_Close()

◆ SOCKETS_SetSockOpt()

◆ SOCKETS_GetHostByName()