PAL
A Platform Abstraction Layer connects the mbed-client with the underlying platform.
Data Structures | Macros | Typedefs | Enumerations | Functions
pal_network.h File Reference
#include "pal.h"

Go to the source code of this file.

Data Structures

struct  palSocketAddress
 
struct  palNetInterfaceInfo
 
struct  pal_timeVal
 

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) /*! 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_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*/
 

Typedefs

typedef uint32_t palSocketLength_t
 
typedef void * palSocket_t
 
typedef struct palSocketAddress palSocketAddress_t
 
typedef struct palNetInterfaceInfo palNetInterfaceInfo_t
 
typedef uint8_t palIpV4Addr_t[PAL_IPV4_ADDRESS_SIZE]
 
typedef uint8_t palIpV6Addr_t[PAL_IPV6_ADDRESS_SIZE]
 
typedef struct pal_timeVal pal_timeVal_t
 

Enumerations

enum  palSocketDomain_t { PAL_AF_UNSPEC = 0, PAL_AF_INET = 2, PAL_AF_INET6 = 10 }
 
enum  palSocketType_t { PAL_SOCK_DGRAM = 2 }
 
enum  palSocketOptionName_t { PAL_SO_REUSEADDR = 0x0004, PAL_SO_SNDTIMEO = 0x1005, PAL_SO_RCVTIMEO = 0x1006 }
 

Functions

palStatus_t pal_registerNetworkInterface (void *networkInterfaceContext, uint32_t *interfaceIndex)
 
palStatus_t pal_setSockAddrPort (palSocketAddress_t *address, uint16_t port)
 
palStatus_t pal_setSockAddrIPV4Addr (palSocketAddress_t *address, palIpV4Addr_t ipV4Addr)
 
palStatus_t pal_setSockAddrIPV6Addr (palSocketAddress_t *address, palIpV6Addr_t ipV6Addr)
 
palStatus_t pal_getSockAddrIPV4Addr (const palSocketAddress_t *address, palIpV4Addr_t ipV4Addr)
 
palStatus_t pal_getSockAddrIPV6Addr (const palSocketAddress_t *address, palIpV6Addr_t ipV6Addr)
 
palStatus_t pal_getSockAddrPort (const palSocketAddress_t *address, uint16_t *port)
 
palStatus_t pal_socket (palSocketDomain_t domain, palSocketType_t type, bool nonBlockingSocket, uint32_t interfaceNum, palSocket_t *socket)
 
palStatus_t pal_getSocketOptions (palSocket_t socket, palSocketOptionName_t optionName, void *optionValue, palSocketLength_t *optionLength)
 
palStatus_t pal_setSocketOptions (palSocket_t socket, int optionName, const void *optionValue, palSocketLength_t optionLength)
 
palStatus_t pal_bind (palSocket_t socket, palSocketAddress_t *myAddress, palSocketLength_t addressLength)
 
palStatus_t pal_receiveFrom (palSocket_t socket, void *buffer, size_t length, palSocketAddress_t *from, palSocketLength_t *fromLength, size_t *bytesReceived)
 
palStatus_t pal_sendTo (palSocket_t socket, const void *buffer, size_t length, const palSocketAddress_t *to, palSocketLength_t toLength, size_t *bytesSent)
 
palStatus_t pal_close (palSocket_t *socket)
 
palStatus_t pal_getNumberOfNetInterfaces (uint32_t *numInterfaces)
 
palStatus_t pal_getNetInterfaceInfo (uint32_t interfaceNum, palNetInterfaceInfo_t *interfaceInfo)
 
palStatus_t pal_socketMiniSelect (const palSocket_t socketsToCheck[PAL_NET_SOCKET_SELECT_MAX_SOCKETS], uint32_t numberOfSockets, pal_timeVal_t *timeout, uint8_t palSocketStatus[PAL_NET_SOCKET_SELECT_MAX_SOCKETS], uint32_t *numberOfSocketsSet)
 

Macro Definition Documentation

#define PAL_IPV4_ADDRESS_SIZE   4
#define PAL_IPV6_ADDRESS_SIZE   16
#define PAL_NET_DEFAULT_INTERFACE   0xFFFFFFFF

socket options supported by PAL

#define PAL_NET_MAX_ADDR_SIZE   32

PAL socket handle type

#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 struct pal_timeVal pal_timeVal_t
typedef uint8_t palIpV4Addr_t[PAL_IPV4_ADDRESS_SIZE]
typedef uint8_t palIpV6Addr_t[PAL_IPV6_ADDRESS_SIZE]

address data structure with enough room to support IPV4 and IPV6

typedef void* palSocket_t

length of data

typedef uint32_t palSocketLength_t

PAL network socket API pal network sockets configurations options: set PAL_NET_TCP_AND_TLS_SUPPORT to true TCP is supported by the platform and is required set PAL_NET_ASYNCHRONOUS_SOCKET_API to true if asynchronous socket API supported by the platform and is required : CURRENTLY MANDATORY set PAL_NET_DNS_SUPPORT to true if you DNS url lookup API is supported.

Enumeration Type Documentation

Enumerator
PAL_AF_UNSPEC 
PAL_AF_INET 
PAL_AF_INET6 

Internet IP Protocol

socket types supported by PAL

Enumerator
PAL_SO_REUSEADDR 
PAL_SO_SNDTIMEO 

allow local address reuse

PAL_SO_RCVTIMEO 

send timeout

network domains supported by PAL

Enumerator
PAL_SOCK_DGRAM 

Function Documentation

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

bind a given socket to a local address

Parameters
[in]socketthe socket to bind
[in]myAddressthe address to which to bind
[in]addressLengththe length of the address passed in myAddress
Returns
the function returns the status in the form of PalStatus_t which will be 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]socketrelease and zero socket pointed to by given pointer.
Returns
the function returns the status as in the form of PalStatus_t which will be PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure
Note
recieves palSocket_t* and 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 index/interface number given (this number is returned when registering the socket)

Parameters
[in]interfaceNumthe number of the interface to get information for.
[out]interfaceInfowill be set to the information for the given interface number.
Returns
the function returns the status as in the form of PalStatus_t which will be 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]numInterfaceswill hold the number of interfaces after a successful call
Returns
the function returns the status as in the form of PalStatus_t which will be 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 a palSocketAddress_t

Parameters
[in]addressthe address to set
[out]ipV4Addrthe address that is set in the address
Returns
the function returns the status in the form of palStatus_t which will be 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 a palSocketAddress_t

Parameters
[in]addressthe address to set
[out]ipV6Addrthe address that is set in the address
Returns
the function returns the status in the form of PalStatus_t which will be 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 a palSocketAddress_t

Parameters
[in]addressthe address to set
[out]portthe port that is set in the address
Returns
the function returns the status in the form of PalStatus_t which will be PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure
palStatus_t pal_getSocketOptions ( palSocket_t  socket,
palSocketOptionName_t  optionName,
void *  optionValue,
palSocketLength_t optionLength 
)

get options for a given network socket

Parameters
[in]socketthe socket for which to get options
[in]optionNamefor which we are setting the option (see enum PAL_NET_SOCKET_OPTION for supported types)
[out]optionValuethe buffer holding the option value returned by the function
[in,out]optionLengththe size of the buffer provided for optionValue when calling the function after the call it will contain the length of data actually written to the optionValue buffer.
Returns
the function returns the status in the form of PalStatus_t which will be 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 the given socket

Parameters
[in]socketthe socket to receive from [we expect sockets passed to this function to be of type PAL_SOCK_DGRAM ( the implementation may support other types as well) ]
[out]bufferthe buffer for the payload data
[in]lengthof the buffer for the payload data
[out]fromthe address which sent the payload
[in,out]fromLengththe length of the 'from' address, after completion will contain the amount of data actually written to the from address
[out]bytesReceivedafter the call will contain the actual amount of payload data received to the buffer
Returns
the function returns the status in the form of PalStatus_t which will be 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 a single interface is added.

Parameters
[in]networkInterfaceContextof the network interface to be added (OS specific , e.g. in MbedOS this is the NetworkInterface object pointer for the network adapter [note: we assume connect has already been called on this]) - if not available use NULL .
[out]InterfaceIndexwill contain the index assigned to the interface in case it has been assigned successfully. this index can be used when creating a socket to bind the socket to the interface.
Returns
the function returns the status in the form of palStatus_t which will be PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure
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 the given address using the given socket

Parameters
[in]socketthe socket to use for sending the payload [we expect sockets passed to this function to be of type PAL_SOCK_DGRAM ( the implementation may support other types as well) ]
[in]bufferthe buffer for the payload data
[in]lengthof the buffer for the payload data
[in]tothe address to which to payload should be sent
[in]toLengththe length of the 'to' address
[out]bytesSentafter the call will contain the actual amount of payload data sent
Returns
the function returns the status in the form of PalStatus_t which will be PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure
palStatus_t pal_setSockAddrIPV4Addr ( palSocketAddress_t address,
palIpV4Addr_t  ipV4Addr 
)

set an ipV4 address to a palSocketAddress_t and also set the addressType to ipv4

Parameters
[in,out]addressthe address to set
[in]ipV4Addrthe address value to set
Returns
the function returns the status in the form of palStatus_t which will be 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 a palSocketAddress_t and also set the addressType to ipv6

Parameters
[in,out]addressthe address to set
[in]ipV6Addrthe address value to set
Returns
the function returns the status in the form of palStatus_t which will be 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 a palSocketAddress_t setting it can be done either directly or via the palSetSockAddrIPV4Addr or palSetSockAddrIPV6Addr functions

Parameters
[in,out]addressthe address to set
[in]portthe port number to set
Returns
the function returns the status in the form of palStatus_t which will be PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure
Note
for the socket to be set correctly the addressType field of the address must be set correctly.
palStatus_t pal_setSocketOptions ( palSocket_t  socket,
int  optionName,
const void *  optionValue,
palSocketLength_t  optionLength 
)

set options for a given network socket

Parameters
[in]socketthe socket for which to get options
[in]optionNamefor which we are setting the option (see enum PAL_NET_SOCKET_OPTION for supported types)
[in]optionValuethe buffer holding the option value to set for the given option
[in]optionLengththe size of the buffer provided for optionValue
Returns
the function returns the status in the form of PalStatus_t which will be PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure
palStatus_t pal_socket ( palSocketDomain_t  domain,
palSocketType_t  type,
bool  nonBlockingSocket,
uint32_t  interfaceNum,
palSocket_t socket 
)

get a network socket

Parameters
[in]domainthe domain for the created socket (see palSocketDomain_t for supported types)
[in]typethe type for the created socket (see palSocketType_t for supported types)
[in]nonBlockingSocketif true the socket created is created as non-blocking (i.e. with O_NONBLOCK set)
[in]interfaceNumthe number of the network interface used for this socket (info in interfaces supported via pal_getNumberOfNetInterfaces and pal_getNetInterfaceInfo ), choose PAL_NET_DEFAULT_INTERFACE for default interface.
[out]socketsocket is returned through this output parameter
Returns
the function returns the status in the form of PalStatus_t which will be PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure
palStatus_t pal_socketMiniSelect ( const palSocket_t  socketsToCheck[PAL_NET_SOCKET_SELECT_MAX_SOCKETS],
uint32_t  numberOfSockets,
pal_timeVal_t timeout,
uint8_t  palSocketStatus[PAL_NET_SOCKET_SELECT_MAX_SOCKETS],
uint32_t *  numberOfSocketsSet 
)

check if one or more (up to PAL_NET_SOCKET_SELECT_MAX_SOCKETS) sockets given has data available for reading/writing/error, the function will block until data is available for one of the given sockets or the timeout expires. To use the function: set the sockets you want to check in the socketsToCheck array and set a timeout, when it returns the socketStatus output will indicate the status of each socket passed in.

Parameters
[in]socketsToCheckon input: the array of up to 8 sockets handles to check.
[in]numberOfSocketsthe number of sockets set in the input socketsToCheck array.
[in]timeoutthe amount of time till timeout if no socket activity is detected
[out]socketStatuswill provide information on each socket in the input array indicating which event was set (none, rx, tx, err) check for desired event using macros.
[out]numberOfSocketsSetis the total number of sockets set in all three data sets (tx, rx, err)after the function completes
Returns
the function returns the status in the form of PalStatus_t which will be PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure
Note
the entry in index x in the socketStatus array corresponds to the socket at index x in the sockets to check array.