Mistake on this page? Email us
pal_plat_network.h File Reference

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"

Go to the source code of this file.

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]domainThe domain of the created socket. See enum palSocketDomain_t for supported types.
[in]typeThe type of the created socket. See enum palSocketType_t for supported types.
[in]callbackA callback function that is called when any supported event takes place in the given asynchronous socket.
[in]callbackArgumentthe argument with which the specified callback will be called when any supported event takes place in the given asynchronous socket.
[out]socketThis 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]socketThe socket to bind.
[in]myAddressThe address to bind to.
[in]addressLengthThe 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]socketPointer 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]interfaceNumThe number of the interface to get information from.
[out]interfaceInfoThe 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]numInterfacesThe 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_estimateThe 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]estimatefor the amount of data in KiB to be transferred.
[out]stagger_estimateThe randomized stagger estimate.
palStatus_t pal_plat_isNonBlocking ( palSocket_t  socket,
bool *  isNonBlocking 
)

Check if a socket is non-blocking.

Parameters
[in]socketThe socket for which to check non-blocking status.
[out]isNonBlockingThe 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]socketThe 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]bufferThe buffer for the payload data.
[in]lengthThe length of the buffer for the payload data in bytes.
[out]fromThe address that sent the payload. This value is optional, pass NULL when not used.
[in,out]fromLengthThe 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]bytesReceivedThe 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]networkInterfaceContextThe 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]interfaceIndexContains 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]socketThe 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]bufferThe buffer for the payload data.
[in]lengthThe length of the buffer for the payload data.
[in]toThe address to which the payload should be sent.
[in]toLengthThe length of the to address.
[out]bytesSentThe 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]socketThe socket to configure.
[in]optionNameThe name of the option to be set. See enum palSocketOptionName_t for supported types.
[in]optionValueThe buffer holding the value to set for the given option.
[in]optionLengthThe 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]socketThe socket to configure.
[in]optionLevelSpecifies the protocol level at which the option resides. See palSocketOptionLevelName_t for supported options.
[in]optionNameThe identification of the socket option to set. See palSocketOptionName_t for supported options.
[in]optionValueThe buffer holding the option value to set for the option.
[in]optionLengthThe 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]contextOptional 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]contextOptional 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
interfaceIndexIndex of the network interface to be removed.
Returns
PAL_SUCCESS (0) in case of success. A specific negative error code in case of failure.