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

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.

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