Simple interface for Mbed Cloud Client
pal_network.h File Reference
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. More...
Go to the source code of this file.
Data Structures | |
struct | palNetInterfaceInfo |
Typedefs | |
typedef uint32_t | palSocketLength_t |
PAL network socket API PAL network sockets configurations options: Set PAL_NET_TCP_AND_TLS_SUPPORT to true if TCP is supported by the platform and is required. | |
typedef void * | palSocket_t |
typedef struct palNetInterfaceInfo | palNetInterfaceInfo_t |
typedef void(* | palAsyncSocketCallback_t )(void *) |
typedef void(* | palGetAddressInfoAsyncCallback_t )(const char *url, palSocketAddress_t *address, palSocketLength_t *addressLength, palStatus_t status, void *callbackArgument) |
Enumerations | |
enum | palSocketDomain_t { , PAL_AF_INET6 = 10 } |
enum | palSocketType_t { , PAL_SOCK_STREAM_SERVER = 99, PAL_SOCK_DGRAM = 2 } |
enum | palSocketOptionName_t { , PAL_SO_KEEPALIVE = 0x0008, PAL_SO_KEEPIDLE = 0x0009, PAL_SO_KEEPINTVL = 0x0010, 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_setSocketOptions (palSocket_t socket, int optionName, const void *optionValue, palSocketLength_t optionLength) |
palStatus_t | pal_isNonBlocking (palSocket_t socket, bool *isNonBlocking) |
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_listen (palSocket_t socket, int backlog) |
palStatus_t | pal_accept (palSocket_t socket, palSocketAddress_t *address, palSocketLength_t *addressLen, palSocket_t *acceptedSocket) |
palStatus_t | pal_connect (palSocket_t socket, const palSocketAddress_t *address, palSocketLength_t addressLen) |
palStatus_t | pal_recv (palSocket_t socket, void *buf, size_t len, size_t *recievedDataSize) |
palStatus_t | pal_send (palSocket_t socket, const void *buf, size_t len, size_t *sentDataSize) |
palStatus_t | pal_asynchronousSocket (palSocketDomain_t domain, palSocketType_t type, bool nonBlockingSocket, uint32_t interfaceNum, palAsyncSocketCallback_t callback, palSocket_t *socket) |
palStatus_t | pal_asynchronousSocketWithArgument (palSocketDomain_t domain, palSocketType_t type, bool nonBlockingSocket, uint32_t interfaceNum, palAsyncSocketCallback_t callback, void *callbackArgument, palSocket_t *socket) |
palStatus_t | pal_getAddressInfo (const char *url, palSocketAddress_t *address, palSocketLength_t *addressLength) |
palStatus_t | pal_getAddressInfoAsync (const char *url, palSocketAddress_t *address, palSocketLength_t *addressLength, palGetAddressInfoAsyncCallback_t callback, void *callbackArgument) |
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.
Definition in file pal_network.h.
Typedef Documentation
typedef void(* palAsyncSocketCallback_t)(void *) |
The type of the callback funciton passed when creating asynchronous sockets.
- Parameters:
-
[in] argument The user provided argument passed to the callback function.
Definition at line 284 of file pal_network.h.
typedef void(* palGetAddressInfoAsyncCallback_t)(const char *url, palSocketAddress_t *address, palSocketLength_t *addressLength, palStatus_t status, void *callbackArgument) |
Prototype of the callback function invoked when querying address info asynchronously (pal_getAddressInfoAsync).
- Parameters:
-
[in] url The user provided url (or IP address string) that was requested to be translated [in] address The address for the output of the translation [in] addressLength The length of the address for the output of the translation in bytes [in] status The status of the operation - PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure [in] callbackArgument The user callback argument
Definition at line 328 of file pal_network.h.
typedef struct palNetInterfaceInfo palNetInterfaceInfo_t |
Address data structure with enough room to support IPV4 and IPV6.
typedef void* palSocket_t |
The length of data.
Definition at line 43 of file pal_network.h.
typedef uint32_t palSocketLength_t |
PAL network socket API
PAL network sockets configurations options:
Set PAL_NET_TCP_AND_TLS_SUPPORT to true if TCP is supported by the platform and is required.
Set PAL_NET_ASYNCHRONOUS_SOCKET_API to true if asynchronous socket API is supported by the platform and is required: Currently MANDATORY. Set PAL_NET_DNS_SUPPORT to true if DNS URL lookup API is supported.
Definition at line 42 of file pal_network.h.
Enumeration Type Documentation
enum palSocketDomain_t |
Definition at line 58 of file pal_network.h.
Socket types supported by PAL.
- Enumerator:
Definition at line 73 of file pal_network.h.
enum palSocketType_t |
Network domains supported by PAL.
Definition at line 64 of file pal_network.h.
Function Documentation
palStatus_t pal_accept | ( | palSocket_t | socket, |
palSocketAddress_t * | address, | ||
palSocketLength_t * | addressLen, | ||
palSocket_t * | acceptedSocket | ||
) |
Accept a connection on the given socket.
- Parameters:
-
[in] socket The socket on which to accept the connection. (The socket must be already created and bound and listen has must have been called on it.) [The sockets passed to this function should be of type PAL_SOCK_STREAM_SERVER (the implementation may support other types as well).] [out] address The source address of the incoming connection. [in,out] addressLen The length of the address field on input, the length of the data returned on output. [out] acceptedSocket The socket of the accepted connection.
- Returns:
- PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
Definition at line 283 of file pal_network.c.
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 created socket (see enum `palSocketType_t` for supported types). [in] nonBlockingSocket If true, the socket is created as non-blocking (with O_NONBLOCK set). [in] interfaceNum The number of the network interface used for this socket (info in interfaces supported via `pal_getNumberOfNetInterfaces` and `pal_getNetInterfaceInfo`). 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 `palAsyncSocketCallbackType` 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.
Definition at line 331 of file pal_network.c.
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 the provided callback on callback events.
- 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 (with O_NONBLOCK set). [in] interfaceNum The number of the network interface used for this socket (info in interfaces supported via `pal_getNumberOfNetInterfaces` and `pal_getNetInterfaceInfo`). 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 callback function is called when any supported event happens in the given asynchronous socket. [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.
Definition at line 340 of file pal_network.c.
palStatus_t pal_bind | ( | palSocket_t | socket, |
palSocketAddress_t * | myAddress, | ||
palSocketLength_t | addressLength | ||
) |
Bind a given 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.
Definition at line 209 of file pal_network.c.
palStatus_t pal_close | ( | palSocket_t * | socket ) |
Close a network socket.
- Parameters:
-
[in,out] 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.
Definition at line 242 of file pal_network.c.
palStatus_t pal_connect | ( | palSocket_t | socket, |
const palSocketAddress_t * | address, | ||
palSocketLength_t | addressLen | ||
) |
Open a connection from the given socket to the given address.
- Parameters:
-
[in] socket The socket to use for connection to the given address. [The sockets passed to this function should be of type PAL_SOCK_STREAM (the implementation may support other types as well).] [in] address The destination address of the connection. [in] addressLen The length of the address field.
- Returns:
- PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
Definition at line 294 of file pal_network.c.
palStatus_t pal_getAddressInfo | ( | const char * | url, |
palSocketAddress_t * | address, | ||
palSocketLength_t * | addressLength | ||
) |
This function translates from a URL to `palSocketAddress_t` which can be used with PAL sockets. It supports both IP address as strings and URLs (using DNS lookup).
- Parameters:
-
[in] url The URL (or IP address string) to be translated to a `palSocketAddress_t`. [out] address The address for the output of the translation.
Definition at line 353 of file pal_network.c.
palStatus_t pal_getAddressInfoAsync | ( | const char * | url, |
palSocketAddress_t * | address, | ||
palSocketLength_t * | addressLength, | ||
palGetAddressInfoAsyncCallback_t | callback, | ||
void * | callbackArgument | ||
) |
This function translates from a URL to `palSocketAddress_t` which can be used with PAL sockets. It supports both IP address as strings and URLs (using DNS lookup).
- Note:
- The function is a non-blocking function.
- Parameters:
-
[in] url The user provided url (or IP address string) to be translated [out] address The address for the output of the translation [out] addressLength The length of the address for the output of the translation in bytes [in] callback The user provided callback to be invoked once the function has completed [in] callbackArgument The user provided callback argument which will be passed back to the (user provided) callback function
Definition at line 375 of file pal_network.c.
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] interfaceNum The number of the interface to get information for. [out] interfaceInfo Set to 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.
Definition at line 264 of file pal_network.c.
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.
Definition at line 253 of file pal_network.c.
palStatus_t pal_getSockAddrIPV4Addr | ( | const palSocketAddress_t * | address, |
palIpV4Addr_t | ipV4Addr | ||
) |
Get an IPv4 address from `palSocketAddress_t`.
- Parameters:
-
[in] address The address to set. [out] ipV4Addr The address that is set in `address`.
- Returns:
- PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
Definition at line 115 of file pal_network.c.
palStatus_t pal_getSockAddrIPV6Addr | ( | const palSocketAddress_t * | address, |
palIpV6Addr_t | ipV6Addr | ||
) |
Get an IPv6 address from `palSocketAddress_t`.
- Parameters:
-
[in] address The address to set. [out] ipV6Addr The address that is set in `address`.
- Returns:
- PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
Definition at line 135 of file pal_network.c.
palStatus_t pal_getSockAddrPort | ( | const palSocketAddress_t * | address, |
uint16_t * | port | ||
) |
Get a port from `palSocketAddress_t`.
- Parameters:
-
[in] address The address to set. [out] port The port that is set in `address`.
- Returns:
- PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
Definition at line 155 of file pal_network.c.
palStatus_t pal_isNonBlocking | ( | palSocket_t | socket, |
bool * | isNonBlocking | ||
) |
Check if a given 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.
Definition at line 200 of file pal_network.c.
palStatus_t pal_listen | ( | palSocket_t | socket, |
int | backlog | ||
) |
Use the given socket to listen for incoming connections. This may also limit the queue of incoming connections.
- Parameters:
-
[in] socket The socket to listen to. [The sockets passed to this function should be of type PAL_SOCK_STREAM_SERVER (the implementation may support other types as well).] [in] backlog The amount of pending connections that can be saved for the socket.
- Returns:
- PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
Definition at line 276 of file pal_network.c.
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] socket The socket to receive from. [The sockets passed to this function should be of type PAL_SOCK_DGRAM (the 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 the `from` address. Contains the amount of data actually written to the `from` address. [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.
Definition at line 220 of file pal_network.c.
palStatus_t pal_recv | ( | palSocket_t | socket, |
void * | buf, | ||
size_t | len, | ||
size_t * | recievedDataSize | ||
) |
Receive data from the given connected socket.
- Parameters:
-
[in] socket The connected socket on which to receive data. [The sockets passed to this function should be of type PAL_SOCK_STREAM (the implementation may support other types as well).] [out] buf The output buffer for the message data. [in] len The length of the input data buffer. [out] recievedDataSize The length of the data actually received.
- Returns:
- PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
Definition at line 305 of file pal_network.c.
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] networkInterfaceContext The network interface to be added ( this is an OS specific value). In mbed OS the networkInterfaceContext is the `NetworkInterface` object pointer for the network adapter [**Note:** We assume 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"). For more examples see the PAL palTestGetNetWorkInterfaceContext function implementations in the platform bring-up examples (found in Examples). The palTestGetNetWorkInterfaceContext function illustrates the expected value for networkInterfaceContext for that target. If a context is not applicable on a target configuration use NULL. [out] interfaceIndex Contains 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:
- PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
Definition at line 55 of file pal_network.c.
palStatus_t pal_send | ( | palSocket_t | socket, |
const void * | buf, | ||
size_t | len, | ||
size_t * | sentDataSize | ||
) |
Send a given buffer via the given connected socket.
- Parameters:
-
[in] socket The connected socket on which to send data. [The sockets passed to this function should be of type PAL_SOCK_STREAM (the implementation may support other types as well).] [in] buf The output buffer for the message data. [in] len The length of the input data buffer. [out] sentDataSize The length of the data sent.
- Returns:
- PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
Definition at line 315 of file pal_network.c.
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] socket The socket to use for sending the payload. [The sockets passed to this function should be of type PAL_SOCK_DGRAM (the 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.
Definition at line 231 of file pal_network.c.
palStatus_t pal_setSockAddrIPV4Addr | ( | palSocketAddress_t * | address, |
palIpV4Addr_t | ipV4Addr | ||
) |
Set an IPv4 address to `palSocketAddress_t` and `addressType` to IPv4.
- Parameters:
-
[in,out] address The address to set. [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.
Definition at line 89 of file pal_network.c.
palStatus_t pal_setSockAddrIPV6Addr | ( | palSocketAddress_t * | address, |
palIpV6Addr_t | ipV6Addr | ||
) |
Set an IPv6 address to `palSocketAddress_t` and the `addressType` to IPv6.
- Parameters:
-
[in,out] address The address to set. [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.
Definition at line 100 of file pal_network.c.
palStatus_t pal_setSockAddrPort | ( | palSocketAddress_t * | address, |
uint16_t | port | ||
) |
Set a port to `palSocketAddress_t`.
You can set it either directly or via the `palSetSockAddrIPV4Addr` or `palSetSockAddrIPV6Addr` functions.
- Parameters:
-
[in,out] address The address to set. [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.
Definition at line 63 of file pal_network.c.
palStatus_t pal_setSocketOptions | ( | palSocket_t | socket, |
int | optionName, | ||
const void * | optionValue, | ||
palSocketLength_t | optionLength | ||
) |
Set the value for a given socket option on a given network socket.
- Parameters:
-
[in] socket The socket for which to get options. [in] optionName The identification of the socket option for which we are getting the value (see enum palSocketOptionName_t for supported types). [in] optionValue The buffer holding the option value to set for the given 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.
Definition at line 190 of file pal_network.c.
palStatus_t pal_socket | ( | palSocketDomain_t | domain, |
palSocketType_t | type, | ||
bool | nonBlockingSocket, | ||
uint32_t | interfaceNum, | ||
palSocket_t * | socket | ||
) |
Get a network socket.
- Parameters:
-
[in] domain The domain for the created socket (see `palSocketDomain_t` for supported types). [in] type The type of the created socket (see `palSocketType_t` for supported types). [in] nonBlockingSocket If true, the socket is created as non-blocking (with O_NONBLOCK set). [in] interfaceNum The number of the network interface used for this socket (info in interfaces supported via `pal_getNumberOfNetInterfaces` and `pal_getNetInterfaceInfo`). Select PAL_NET_DEFAULT_INTERFACE for the default interface. [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.
Definition at line 180 of file pal_network.c.
Generated on Tue Jul 12 2022 19:01:38 by 1.7.2