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 }
	Socket 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_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_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...

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

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.

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.

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.

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_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_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