PAL network - platform. This file contains the network APIs that need to be implemented in the platform layer. More...

#include "pal.h"
#include "pal_network.h"

Functions
palStatus_t	pal_plat_socketsInit (void *context)
	Initialize sockets. More...

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

palStatus_t	pal_plat_unregisterNetworkInterface (uint32_t interfaceIndex)

palStatus_t	pal_plat_socketsTerminate (void *context)
	Socket termination. More...

palStatus_t	pal_plat_setSocketOptions (palSocket_t socket, int optionName, const void *optionValue, palSocketLength_t optionLength)
	Set options for a network socket. More...

palStatus_t	pal_plat_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_plat_isNonBlocking (palSocket_t socket, bool *isNonBlocking)
	Check if a socket is non-blocking. More...

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

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

palStatus_t	pal_plat_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_plat_close (palSocket_t *socket)
	Close a network socket. More...

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

palStatus_t	pal_plat_getNetInterfaceInfo (uint32_t interfaceNum, palNetInterfaceInfo_t *interfaceInfo)
	Get information regarding a socket at a specific interface number. More...

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

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

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

Detailed Description

PAL network - platform. This file contains the network APIs that need to be implemented in the platform layer.

PAL network socket API /n PAL network socket configuration options:

define PAL_NET_TCP_AND_TLS_SUPPORT if TCP is supported by the platform and is required.
define PAL_NET_DNS_SUPPORT if DNS name resolution is supported.

Function Documentation

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

Get an asynchronous network socket.

Parameters

[in]	domain	The domain of the created socket. See enum `palSocketDomain_t` for supported types.
[in]	type	The type of the created socket. See enum `palSocketType_t` for supported types.
[in]	callback	A callback function that is called when any supported event takes place in the given asynchronous socket.
[in]	callbackArgument	the argument with which the specified callback will be called when any supported event takes place in the given asynchronous socket.
[out]	socket	This output parameter returns the socket.

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

palStatus_t pal_plat_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. A specific negative error code in case of failure.

palStatus_t pal_plat_close ( palSocket_t * socket )

Close a network socket.

Note: The function recieves palSocket_t* and not palSocket_t so that it can zero the socket to avoid re-use.

Parameters

[in,out] socket Pointer to the socket to release and zero.

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

palStatus_t pal_plat_getNetInterfaceInfo	(	uint32_t	interfaceNum,
		palNetInterfaceInfo_t *	interfaceInfo
	)

Get information regarding a socket at a specific interface number.

Parameters

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

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

palStatus_t pal_plat_getNumberOfNetInterfaces ( uint32_t * numInterfaces )

Get the number of current network interfaces.

The function counts interfaces that have been successfully registered.

Parameters

[out] numInterfaces The number of interfaces after a successful call.

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

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

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

palStatus_t pal_plat_isNonBlocking	(	palSocket_t	socket,
		bool *	isNonBlocking
	)

Check if a socket is non-blocking.

Parameters

[in]	socket	The socket for which to check non-blocking status.
[out]	isNonBlocking	The non-blocking status for the socket. Is `true` if non-blocking, otherwise `false`.

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

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

Receive a payload from a socket.

Parameters

[in]	socket	The socket to receive from. The socket passed to this function should be of type `PAL_SOCK_DGRAM`, unless your specific implementation supports other types as well.
[out]	buffer	The buffer for the payload data.
[in]	length	The length of the buffer for the payload data in bytes.
[out]	from	The address that sent the payload. This value is optional, pass NULL when not used.
[in,out]	fromLength	The length of the `from` address. When completed, this contains the amount of data actually written to the `from` address. This value is optional, pass NULL when not used.
[out]	bytesReceived	The actual amount of payload data received in the buffer.

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

palStatus_t pal_plat_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 context of the network interface to be added. This is OS-specific. In mbed OS, this is the NetworkInterface object pointer for the network adapter and assumes a connect has already been called on this. If not available, use NULL. This is not required on some OSs.
[out]	interfaceIndex	Contains the index assigned to the interface if it has been assigned successfully. This index can be used when creating a socket to bind the socket to the interface.

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

palStatus_t pal_plat_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 be of type `PAL_SOCK_DGRAM`, unless your specific implementation supports 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. A specific negative error code in case of failure.

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

Set options for a network socket.

See palSocketOptionName_t for supported options.

Parameters

[in]	socket	The socket to configure.
[in]	optionName	The name of the option to be set. See enum `palSocketOptionName_t` for supported types.
[in]	optionValue	The buffer holding the value to set for the given option.
[in]	optionLength	The size of the buffer provided for `optionValue` in bytes.

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

palStatus_t pal_plat_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 options.
[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_plat_socketsInit ( void * context )

Initialize sockets.

Must be called before other socket functions. By default, is called from PAL init.

Parameters

[in] context Optional context. If not available or applicable, use NULL.

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

palStatus_t pal_plat_socketsTerminate ( void * context )

Socket termination.

This can be called when sockets are no longer needed, to free socket resources.

Parameters

[in] context Optional context. If not available, use NULL.

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

palStatus_t pal_plat_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. A specific negative error code in case of failure.

Documentation

Functions

Detailed Description

Function Documentation