PAL network. This file contains the network APIs and it is a part of the PAL service API. More...

Data Structures
struct	palSocketAddress

struct	palNetInterfaceInfo

Macros
#define	PAL_NET_MAX_ADDR_SIZE 32

#define	PAL_NET_DEFAULT_INTERFACE 0xFFFFFFFF

#define	PAL_IPV4_ADDRESS_SIZE 4

#define	PAL_IPV6_ADDRESS_SIZE 16

#define	PAL_NET_SOCKET_SELECT_MAX_SOCKETS 8

#define	PAL_NET_SOCKET_SELECT_RX_BIT (1)

#define	PAL_NET_SOCKET_SELECT_TX_BIT (2)

#define	PAL_NET_SOCKET_SELECT_ERR_BIT (4)

#define	PAL_NET_SELECT_IS_RX(socketStatus, index) ((socketStatus[index] & PAL_NET_SOCKET_SELECT_RX_BIT) != 0)

#define	PAL_NET_SELECT_IS_TX(socketStatus, index) ((socketStatus[index] & PAL_NET_SOCKET_SELECT_TX_BIT) != 0)

#define	PAL_NET_SELECT_IS_ERR(socketStatus, index) ((socketStatus[index] & PAL_NET_SOCKET_SELECT_ERR_BIT) != 0)

Typedefs
typedef uint32_t	palSocketLength_t
	The length of data. More...

typedef void *	palSocket_t
	PAL socket handle type. More...

typedef struct palSocketAddress	palSocketAddress_t
	Address data structure with enough room to support IPV4 and IPV6. More...

typedef struct palNetInterfaceInfo	palNetInterfaceInfo_t

typedef uint8_t	palIpV4Addr_t[PAL_IPV4_ADDRESS_SIZE]

typedef uint8_t	palIpV6Addr_t[PAL_IPV6_ADDRESS_SIZE]

typedef void(*	connectionStatusCallback) (palNetworkStatus_t status, void *client_arg)

typedef void(*	palAsyncSocketCallback_t) (void *)
	The type of the callback function passed when creating asynchronous sockets. More...

Enumerations
enum	palSocketDomain_t { PAL_AF_UNSPEC = 0, PAL_AF_INET = 2, PAL_AF_INET6 = 10 }
	Network domains supported by PAL. More...

enum	palNetworkStatus_t { PAL_NETWORK_STATUS_DISCONNECTED = 0, PAL_NETWORK_STATUS_CONNECTED = 1 }
	Network status event. More...

enum	palSocketType_t { PAL_SOCK_DGRAM = 2 }
	Socket types supported by PAL. More...

enum	palSocketOptionName_t { PAL_SO_REUSEADDR = 0x0004, PAL_SO_SNDTIMEO = 0x1005, PAL_SO_RCVTIMEO = 0x1006, PAL_SO_IPV6_MULTICAST_HOPS = 0x1007, PAL_SO_IPV6_TRAFFIC_CLASS = 0x1008 }
	Socket options supported by PAL. More...

enum	palSocketOptionLevelName_t { PAL_SOL_SOCKET = 0, PAL_SOL_IPPROTO_IPV6 = 1 }
	Socket protocol level options supported by PAL. More...

Functions
palStatus_t	pal_registerNetworkInterface (void networkInterfaceContext, uint32_t interfaceIndex)
	Register a network interface for use with PAL sockets. More...

palStatus_t	pal_unregisterNetworkInterface (uint32_t interfaceIndex)
	Unregister a network interface. More...

palStatus_t	pal_setSockAddrPort (palSocketAddress_t *address, uint16_t port)
	Set a port to an address data structure. More...

palStatus_t	pal_setSockAddrIPV4Addr (palSocketAddress_t *address, palIpV4Addr_t ipV4Addr)
	Set an IPv4 address to an address data structure and set `addressType` as IPv4. More...

palStatus_t	pal_getSockAddrIPV4Addr (const palSocketAddress_t *address, palIpV4Addr_t ipV4Addr)
	Get an IPv4 address from an address data structure. More...

palStatus_t	pal_setSockAddrIPV6Addr (palSocketAddress_t *address, palIpV6Addr_t ipV6Addr)
	Set an IPv6 address to an address data structure and set the `addressType` as IPv6. More...

palStatus_t	pal_getSockAddrIPV6Addr (const palSocketAddress_t *address, palIpV6Addr_t ipV6Addr)
	Get an IPv6 address from an address data structure. More...

palStatus_t	pal_setSockAddrNAT64Addr (palSocketAddress_t *address, palIpV4Addr_t ipV4Addr)
	Set a NAT64 address from an IPv4 address data structure and set `addressType` as IPv6. More...

palStatus_t	pal_getSockAddrPort (const palSocketAddress_t address, uint16_t port)
	Get a port from an address data structure. More...

palStatus_t	pal_setSocketOptions (palSocket_t socket, int optionName, const void *optionValue, palSocketLength_t optionLength)
	Set the value for a socket option on a network socket. More...

palStatus_t	pal_setSocketOptionsWithLevel (palSocket_t socket, palSocketOptionLevelName_t optionLevel, int optionName, const void *optionValue, palSocketLength_t optionLength)
	Set the value for a socket option on a network socket. More...

palStatus_t	pal_isNonBlocking (palSocket_t socket, bool *isNonBlocking)
	Check if a socket is non-blocking. More...

palStatus_t	pal_bind (palSocket_t socket, palSocketAddress_t *myAddress, palSocketLength_t addressLength)
	Bind a socket to a local address. More...

palStatus_t	pal_receiveFrom (palSocket_t socket, void buffer, size_t length, palSocketAddress_t from, palSocketLength_t fromLength, size_t bytesReceived)
	Receive a payload from a specific socket. More...

palStatus_t	pal_sendTo (palSocket_t socket, const void buffer, size_t length, const palSocketAddress_t to, palSocketLength_t toLength, size_t *bytesSent)
	Send a payload to an address using a specific socket. More...

palStatus_t	pal_close (palSocket_t *socket)
	Close a network socket. More...

palStatus_t	pal_getNumberOfNetInterfaces (uint32_t *numInterfaces)
	Get the number of current network interfaces. More...

palStatus_t	pal_getNetInterfaceInfo (uint32_t interfaceNum, palNetInterfaceInfo_t *interfaceInfo)
	Get information regarding the socket at the interface index number given. This number is returned when registering the socket. More...

palStatus_t	pal_setConnectionStatusCallback (uint32_t interfaceNum, connectionStatusCallback callback, void *client_arg)
	Set listener for connection status events. More...

palStatus_t	pal_asynchronousSocket (palSocketDomain_t domain, palSocketType_t type, bool nonBlockingSocket, uint32_t interfaceNum, palAsyncSocketCallback_t callback, palSocket_t *socket)
	Get an asynchronous network socket. More...

palStatus_t	pal_asynchronousSocketWithArgument (palSocketDomain_t domain, palSocketType_t type, bool nonBlockingSocket, uint32_t interfaceNum, palAsyncSocketCallback_t callback, void callbackArgument, palSocket_t socket)
	Get an asynchronous network socket that passes the provided `callbackArgument` to a specified callback when it is triggered. More...

uint8_t	pal_getRttEstimate ()
	This function returns the round-trip estimate for packet in seconds. More...

uint16_t	pal_getStaggerEstimate (uint16_t data_amount)
	This function returns the stagger estimate for registration in seconds. More...

void	pal_setFixedStaggerEstimate (uint16_t stagger_estimate)
	This function sets an application defined override value for the stagger estimate for registration in seconds. More...

Detailed Description

PAL network. This file contains the network APIs and it is a part of the PAL service API.

It provides network functionalities for UDP and TCP sockets and connections.

PAL network socket API
PAL network socket configuration options:

Set PAL_NET_TCP_AND_TLS_SUPPORT to true if TCP is supported by the platform and is required.
Set PAL_NET_DNS_SUPPORT to true if DNS hostname lookup API is supported.

Macro Definition Documentation

#define PAL_IPV4_ADDRESS_SIZE 4

#define PAL_IPV6_ADDRESS_SIZE 16

#define PAL_NET_DEFAULT_INTERFACE 0xFFFFFFFF

#define PAL_NET_MAX_ADDR_SIZE 32

#define PAL_NET_SELECT_IS_ERR	(	socketStatus,
		index
	)	((socketStatus[index] & PAL_NET_SOCKET_SELECT_ERR_BIT) != 0)

Check if ERR bit is set in select result for a given socket index.

#define PAL_NET_SELECT_IS_RX	(	socketStatus,
		index
	)	((socketStatus[index] & PAL_NET_SOCKET_SELECT_RX_BIT) != 0)

Check if RX bit is set in select result for a given socket index.

#define PAL_NET_SELECT_IS_TX	(	socketStatus,
		index
	)	((socketStatus[index] & PAL_NET_SOCKET_SELECT_TX_BIT) != 0)

Check if TX bit is set in select result for a given socket index.

#define PAL_NET_SOCKET_SELECT_ERR_BIT (4)

#define PAL_NET_SOCKET_SELECT_MAX_SOCKETS 8

#define PAL_NET_SOCKET_SELECT_RX_BIT (1)

#define PAL_NET_SOCKET_SELECT_TX_BIT (2)

Typedef Documentation

typedef void(* connectionStatusCallback) (palNetworkStatus_t status, void *client_arg)

typedef void(* palAsyncSocketCallback_t) (void *)

The type of the callback function passed when creating asynchronous sockets.

Parameters

[in] argument The user provided argument passed to the callback function.

typedef uint8_t palIpV4Addr_t[PAL_IPV4_ADDRESS_SIZE]

typedef uint8_t palIpV6Addr_t[PAL_IPV6_ADDRESS_SIZE]

typedef struct palNetInterfaceInfo palNetInterfaceInfo_t

typedef void* palSocket_t

PAL socket handle type.

typedef struct palSocketAddress palSocketAddress_t

Address data structure with enough room to support IPV4 and IPV6.

typedef uint32_t palSocketLength_t

The length of data.

Enumeration Type Documentation

enum palNetworkStatus_t

Network status event.

Enumerator
PAL_NETWORK_STATUS_DISCONNECTED
PAL_NETWORK_STATUS_CONNECTED

enum palSocketDomain_t

Network domains supported by PAL.

Enumerator
PAL_AF_UNSPEC
PAL_AF_INET	Internet IP Protocol.
PAL_AF_INET6	IP version 6.

enum palSocketOptionLevelName_t

Socket protocol level options supported by PAL.

Enumerator
PAL_SOL_SOCKET
PAL_SOL_IPPROTO_IPV6

enum palSocketOptionName_t

Socket options supported by PAL.

Enumerator
PAL_SO_REUSEADDR	Allow local address reuse.
PAL_SO_SNDTIMEO	Send timeout.
PAL_SO_RCVTIMEO	Receive timeout.
PAL_SO_IPV6_MULTICAST_HOPS	Hop limit for subsequent multicast datagrams to be set to any value from 0 to 255. This ability is used to control the scope of the multicasts.
PAL_SO_IPV6_TRAFFIC_CLASS	Use to set IPv6 traffic class priority. Default is 0.

enum palSocketType_t

Socket types supported by PAL.

Enumerator
PAL_SOCK_DGRAM	Datagram socket.

Function Documentation

palStatus_t pal_asynchronousSocket	(	palSocketDomain_t	domain,
		palSocketType_t	type,
		bool	nonBlockingSocket,
		uint32_t	interfaceNum,
		palAsyncSocketCallback_t	callback,
		palSocket_t *	socket
	)

Get an asynchronous network socket.

Parameters

[in]	domain	The domain for the created socket. See enum `palSocketDomain_t` for supported types.
[in]	type	The type for the socket. See enum `palSocketType_t` for supported types.
[in]	nonBlockingSocket	If `true`, the socket is non-blocking.
[in]	interfaceNum	The number of the network interface used for this socket. Select `PAL_NET_DEFAULT_INTERFACE` for the default interface.
[in]	callback	A callback function that is called when any supported event happens in the given asynchronous socket. See `palAsyncSocketCallback_t` enum for the types of events supported.
[out]	socket	The socket is returned through this output parameter.

Returns: PAL_SUCCESS (0) in case of success, or a specific negative error code in case of failure.

palStatus_t pal_asynchronousSocketWithArgument	(	palSocketDomain_t	domain,
		palSocketType_t	type,
		bool	nonBlockingSocket,
		uint32_t	interfaceNum,
		palAsyncSocketCallback_t	callback,
		void *	callbackArgument,
		palSocket_t *	socket
	)

Get an asynchronous network socket that passes the provided callbackArgument to a specified callback when it is triggered.

Parameters

[in]	domain	The domain for the created socket. See enum `palSocketDomain_t` for supported types.
[in]	type	The type for the created socket. See enum `palSocketType_t` for supported types.
[in]	nonBlockingSocket	If `true`, the socket is created as non-blocking.
[in]	interfaceNum	The number of the network interface used for this socket. Select `PAL_NET_DEFAULT_INTERFACE` for the default interface.
[in]	callback	A callback function that is called when any supported event happens in the given asynchronous socket.
[in]	callbackArgument	The argument with which the specified callback function is called.
[out]	socket	The socket is returned through this output parameter.

Returns: PAL_SUCCESS (0) in case of success, or a specific negative error code in case of failure.

palStatus_t pal_bind	(	palSocket_t	socket,
		palSocketAddress_t *	myAddress,
		palSocketLength_t	addressLength
	)

Bind a socket to a local address.

Parameters

[in]	socket	The socket to bind.
[in]	myAddress	The address to bind to.
[in]	addressLength	The length of the address passed in `myAddress`.

Returns: PAL_SUCCESS (0) in case of success, or a specific negative error code in case of failure.

palStatus_t pal_close ( palSocket_t * socket )

Close a network socket.

Parameters

[in,out] socket The socket to be closed.

Returns: PAL_SUCCESS (0) in case of success, or a specific negative error code in case of failure.

Note: Receives palSocket_t*, not palSocket_t, so that it can zero the socket to avoid re-use.

palStatus_t pal_getNetInterfaceInfo	(	uint32_t	interfaceNum,
		palNetInterfaceInfo_t *	interfaceInfo
	)

Get information regarding the socket at the interface index number given. This number is returned when registering the socket.

Parameters

[in]	interfaceNum	The number of the interface to get information for.
[out]	interfaceInfo	The information for the given interface number.

Returns: PAL_SUCCESS (0) in case of success, or a specific negative error code in case of failure.

palStatus_t pal_getNumberOfNetInterfaces ( uint32_t * numInterfaces )

Get the number of current network interfaces.

Parameters

[out] numInterfaces The number of interfaces.

Returns: PAL_SUCCESS (0) in case of success, or a specific negative error code in case of failure.

uint8_t pal_getRttEstimate ( )

This function returns the round-trip estimate for packet in seconds.

This value can be used to control client retransmission and responsiveness in high latency networks based on the network information the stack has. This feature is currently only supported for Mbed OS Wi-SUN stack as a dynamic feature. Other platforms/stacks return PAL_DEFAULT_RTT_ESTIMATE. This API limits the RTT to uint8_t due to most of the callers only supporting uint8_t or uint16_t types.

Parameters

[out] rtt_estimate The round-trip estimate in seconds.

palStatus_t pal_getSockAddrIPV4Addr	(	const palSocketAddress_t *	address,
		palIpV4Addr_t	ipV4Addr
	)

Get an IPv4 address from an address data structure.

Parameters

[in]	address	The address data structure to query.
[out]	ipV4Addr	The IPv4 address to get.

Returns: PAL_SUCCESS (0) in case of success, or a specific negative error code in case of failure.

palStatus_t pal_getSockAddrIPV6Addr	(	const palSocketAddress_t *	address,
		palIpV6Addr_t	ipV6Addr
	)

Get an IPv6 address from an address data structure.

Parameters

[in]	address	The address data structure to query.
[out]	ipV6Addr	The address to get.

Returns: PAL_SUCCESS (0) in case of success, or a specific negative error code in case of failure.

palStatus_t pal_getSockAddrPort	(	const palSocketAddress_t *	address,
		uint16_t *	port
	)

Get a port from an address data structure.

Parameters

[in]	address	The address data structure to query.
[out]	port	The port to get.

Returns: PAL_SUCCESS (0) in case of success, or a specific negative error code in case of failure.

uint16_t pal_getStaggerEstimate ( uint16_t data_amount )

This function returns the stagger estimate for registration in seconds.

This value can be used to delay the registration of the client after interface GLOBAL_UP to stagger the traffic in a multidevice network with limited bandwidth. This feature is currently only supported for Mbed OS Wi-SUN stack as a dynamic feature. Other platforms/stacks return PAL_DEFAULT_STAGGER_ESTIMATE.

Parameters

[in]	estimate	for the amount of data in KiB to be transferred.
[out]	stagger_estimate	The randomized stagger estimate in seconds.

palStatus_t pal_isNonBlocking	(	palSocket_t	socket,
		bool *	isNonBlocking
	)

Check if a socket is non-blocking.

Parameters

[in]	socket	The socket to check.
[out]	isNonBlocking	`True` if the socket is non-blocking, otherwise `false`.

Returns: PAL_SUCCESS (0) in case of success, or a specific negative error code in case of failure.

palStatus_t pal_receiveFrom	(	palSocket_t	socket,
		void *	buffer,
		size_t	length,
		palSocketAddress_t *	from,
		palSocketLength_t *	fromLength,
		size_t *	bytesReceived
	)

Receive a payload from a specific socket.

Parameters

[in]	socket	The socket to receive from. The socket passed to this function should usually be of type `PAL_SOCK_DGRAM`, though your specific implementation may support other types as well.
[out]	buffer	The buffer for the payload data.
[in]	length	The length of the buffer for the payload data.
[out]	from	The address that sent the payload.
[in,out]	fromLength	The length of `from` on input, the length of the data returned on output.
[out]	bytesReceived	The actual amount of payload data received in the buffer.

Returns: PAL_SUCCESS (0) in case of success, or a specific negative error code in case of failure.

palStatus_t pal_registerNetworkInterface	(	void *	networkInterfaceContext,
		uint32_t *	interfaceIndex
	)

Register a network interface for use with PAL sockets.

Must be called before other socket functions. Most APIs will not work before an interface is added.

Parameters

[in]	networkInterfaceContext	The network interface to be added. This value is OS-specific.
[out]	interfaceIndex	Contains the index assigned to the interface in case it has been assigned successfully. When creating a socket, this index can be used to bind the socket to the interface.

Returns: PAL_SUCCESS (0) in case of success, or a specific negative error code in case of failure.

Note: In mbed OS the networkInterfaceContext is the NetworkInterface object pointer for the network adapter, assuming that connect has already been called on this interface object.; In Linux the networkInterfaceContext is the string name of the network interface (e.g. eth0 ).; If a context is not applicable on a target configuration, use NULL .

palStatus_t pal_sendTo	(	palSocket_t	socket,
		const void *	buffer,
		size_t	length,
		const palSocketAddress_t *	to,
		palSocketLength_t	toLength,
		size_t *	bytesSent
	)

Send a payload to an address using a specific socket.

Parameters

[in]	socket	The socket to use for sending the payload. The socket passed to this function should usually be of type `PAL_SOCK_DGRAM`, though your specific implementation may support other types as well.
[in]	buffer	The buffer for the payload data.
[in]	length	The length of the buffer for the payload data.
[in]	to	The address to which the payload should be sent.
[in]	toLength	The length of the `to` address.
[out]	bytesSent	The actual amount of payload data sent.

Returns: PAL_SUCCESS (0) in case of success, or a specific negative error code in case of failure.

palStatus_t pal_setConnectionStatusCallback	(	uint32_t	interfaceNum,
		connectionStatusCallback	callback,
		void *	client_arg
	)

Set listener for connection status events.

Parameters

[in]	interfaceNum	Index of the network interface to be listen.
[in]	callback	Callback that is called when network interface status change.
[in]	client_arg	The argument which is passed to the callback function.

Returns: PAL_SUCCESS (0) in case of success, a specific negative error code in case of failure.

void pal_setFixedStaggerEstimate ( uint16_t stagger_estimate )

This function sets an application defined override value for the stagger estimate for registration in seconds.

This value can be used to set a delay for the registration of the client after interface GLOBAL_UP to stagger the traffic in a multidevice network with limited bandwidth. When set to any value larger than 0, this overrides any compile-time values set by PAL_DEFAULT_STAGGER_ESTIMATE or provided by network stack. If value is 0, this override is disabled.

Parameters

[in] stagger value in seconds.

palStatus_t pal_setSockAddrIPV4Addr	(	palSocketAddress_t *	address,
		palIpV4Addr_t	ipV4Addr
	)

Set an IPv4 address to an address data structure and set addressType as IPv4.

Parameters

[in,out]	address	The address data structure to configure.
[in]	ipV4Addr	The address value to set.

Returns: PAL_SUCCESS (0) in case of success, or a specific negative error code in case of failure.

palStatus_t pal_setSockAddrIPV6Addr	(	palSocketAddress_t *	address,
		palIpV6Addr_t	ipV6Addr
	)

Set an IPv6 address to an address data structure and set the addressType as IPv6.

Parameters

[in,out]	address	The address data structure to configure.
[in]	ipV6Addr	The address value to set.

Returns: PAL_SUCCESS (0) in case of success, or a specific negative error code in case of failure.

palStatus_t pal_setSockAddrNAT64Addr	(	palSocketAddress_t *	address,
		palIpV4Addr_t	ipV4Addr
	)

Set a NAT64 address from an IPv4 address data structure and set addressType as IPv6.

Parameters

[in,out]	address	The address data structure to configure.
[in]	ipV4Addr	The address value to set.

Returns: PAL_SUCCESS (0) in case of success, or a specific negative error code in case of failure.

palStatus_t pal_setSockAddrPort	(	palSocketAddress_t *	address,
		uint16_t	port
	)

Set a port to an address data structure.

Parameters

[in,out]	address	The address data structure to configure.
[in]	port	The port number to set.

Returns: PAL_SUCCESS (0) in case of success, or a specific negative error code in case of failure.

Note: To set the socket correctly, the addressType field of the address must be set correctly. You can set it either directly, or using the pal_setSockAddrIPV4Addr or pal_setSockAddrIPV6Addr functions.

palStatus_t pal_setSocketOptions	(	palSocket_t	socket,
		int	optionName,
		const void *	optionValue,
		palSocketLength_t	optionLength
	)

Set the value for a socket option on a network socket.

Parameters

[in]	socket	The socket to configure.
[in]	optionName	The identification of the socket option to set. See `palSocketOptionName_t` for supported options.
[in]	optionValue	The buffer holding the option value to set for the option.
[in]	optionLength	The size of the buffer provided for `optionValue`.

Returns: PAL_SUCCESS (0) in case of success, or a specific negative error code in case of failure.

palStatus_t pal_setSocketOptionsWithLevel	(	palSocket_t	socket,
		palSocketOptionLevelName_t	optionLevel,
		int	optionName,
		const void *	optionValue,
		palSocketLength_t	optionLength
	)

Set the value for a socket option on a network socket.

Parameters

[in]	socket	The socket to configure.
[in]	optionLevel	Specifies the protocol level at which the option resides. See `palSocketOptionLevelName_t` for supported levels.
[in]	optionName	The identification of the socket option to set. See `palSocketOptionName_t` for supported options.
[in]	optionValue	The buffer holding the option value to set for the option.
[in]	optionLength	The size of the buffer provided for `optionValue`.

Returns: PAL_SUCCESS (0) in case of success, or a specific negative error code in case of failure.

palStatus_t pal_unregisterNetworkInterface ( uint32_t interfaceIndex )

Unregister a network interface.

Parameters

interfaceIndex Index of the network interface to be removed.

Returns: PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.

Documentation

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation