Simple interface for Mbed Cloud Client
Embed:
(wiki syntax)
Show/hide line numbers
pal_network.h
Go to the documentation of this file.
00001 /******************************************************************************* 00002 * Copyright 2016, 2017 ARM Ltd. 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 *******************************************************************************/ 00016 00017 00018 #ifndef _PAL_SOCKET_H 00019 #define _PAL_SOCKET_H 00020 00021 #ifndef _PAL_H 00022 #error "Please do include call this file directly, use pal.h instead" 00023 #endif 00024 00025 00026 #ifdef __cplusplus 00027 extern "C" { 00028 #endif 00029 00030 /*! \file pal_network.h 00031 * \brief PAL network. 00032 * This file contains the network APIs and it is a part of the PAL service API. 00033 * It provides network functionalities for UDP and TCP sockets and connections. 00034 */ 00035 00036 //! PAL network socket API \n 00037 //! PAL network sockets configurations options: \n 00038 //! Set PAL_NET_TCP_AND_TLS_SUPPORT to true if TCP is supported by the platform and is required. \n 00039 //! Set PAL_NET_ASYNCHRONOUS_SOCKET_API to true if asynchronous socket API is supported by the platform and is required: Currently MANDATORY. 00040 //! Set PAL_NET_DNS_SUPPORT to true if DNS URL lookup API is supported. 00041 00042 typedef uint32_t palSocketLength_t; /*! The length of data. */ 00043 typedef void* palSocket_t ; /*! PAL socket handle type. */ 00044 00045 #define PAL_NET_MAX_ADDR_SIZE 32 // check if we can make this more efficient 00046 00047 typedef struct palSocketAddress { 00048 unsigned short addressType; /*! Address family for the socket. */ 00049 char addressData[PAL_NET_MAX_ADDR_SIZE]; /*! Address (based on protocol). */ 00050 } palSocketAddress_t; /*! Address data structure with enough room to support IPV4 and IPV6. */ 00051 00052 typedef struct palNetInterfaceInfo { 00053 char interfaceName[16]; //15 + ‘\0’ 00054 palSocketAddress_t address; 00055 uint32_t addressSize; 00056 } palNetInterfaceInfo_t ; 00057 00058 typedef enum { 00059 PAL_AF_UNSPEC = 0, 00060 PAL_AF_INET = 2, /*! Internet IP Protocol. */ 00061 PAL_AF_INET6 = 10, /*! IP version 6. */ 00062 } palSocketDomain_t ;/*! Network domains supported by PAL. */ 00063 00064 typedef enum { 00065 #if PAL_NET_TCP_AND_TLS_SUPPORT 00066 PAL_SOCK_STREAM = 1, /*! Stream socket. */ 00067 PAL_SOCK_STREAM_SERVER = 99, /*! Stream socket. */ 00068 #endif //PAL_NET_TCP_AND_TLS_SUPPORT 00069 PAL_SOCK_DGRAM = 2 /*! Datagram socket. */ 00070 } palSocketType_t ;/*! Socket types supported by PAL. */ 00071 00072 00073 typedef enum { 00074 PAL_SO_REUSEADDR = 0x0004, /*! Allow local address reuse. */ 00075 #if PAL_NET_TCP_AND_TLS_SUPPORT // Socket options below supported only if TCP is supported. 00076 PAL_SO_KEEPALIVE = 0x0008, /*! Keep TCP connection open even if idle using periodic messages. */ 00077 PAL_SO_KEEPIDLE = 0x0009, /*! The time (in seconds) the connection needs to remain idle before TCP starts sending keepalive probes, if the socket option SO_KEEPALIVE has been set on this socket. */ 00078 PAL_SO_KEEPINTVL = 0x0010, /*! The time (in seconds) between individual keepalive probes */ 00079 #endif //PAL_NET_TCP_AND_TLS_SUPPORT 00080 PAL_SO_SNDTIMEO = 0x1005, /*! Send timeout. */ 00081 PAL_SO_RCVTIMEO = 0x1006, /*! Receive timeout. */ 00082 } palSocketOptionName_t ;/*! Socket options supported by PAL. */ 00083 00084 #define PAL_NET_DEFAULT_INTERFACE 0xFFFFFFFF 00085 00086 #define PAL_IPV4_ADDRESS_SIZE 4 00087 #define PAL_IPV6_ADDRESS_SIZE 16 00088 00089 typedef uint8_t palIpV4Addr_t[PAL_IPV4_ADDRESS_SIZE]; 00090 typedef uint8_t palIpV6Addr_t[PAL_IPV6_ADDRESS_SIZE]; 00091 00092 00093 /*! 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. 00094 * @param[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\PlatformBSP). The palTestGetNetWorkInterfaceContext function illustrates the expected value for networkInterfaceContext for that target. If a context is not applicable on a target configuration use NULL. 00095 * @param[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. 00096 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure. 00097 */ 00098 palStatus_t pal_registerNetworkInterface(void* networkInterfaceContext, uint32_t* interfaceIndex); 00099 00100 /*! Set a port to `palSocketAddress_t`. \n 00101 * You can set it either directly or via the `palSetSockAddrIPV4Addr` or `palSetSockAddrIPV6Addr` functions. 00102 * @param[in,out] address The address to set. 00103 * @param[in] port The port number to set. 00104 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure. 00105 \note To set the socket correctly, the `addressType` field of the address must be set correctly. 00106 */ 00107 palStatus_t pal_setSockAddrPort(palSocketAddress_t* address, uint16_t port); 00108 00109 /*! Set an IPv4 address to `palSocketAddress_t` and `addressType` to IPv4. 00110 * @param[in,out] address The address to set. 00111 * @param[in] ipV4Addr The address value to set. 00112 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure. 00113 */ 00114 palStatus_t pal_setSockAddrIPV4Addr(palSocketAddress_t* address, palIpV4Addr_t ipV4Addr); 00115 00116 /*! Set an IPv6 address to `palSocketAddress_t` and the `addressType` to IPv6. 00117 * @param[in,out] address The address to set. 00118 * @param[in] ipV6Addr The address value to set. 00119 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure. 00120 */ 00121 palStatus_t pal_setSockAddrIPV6Addr(palSocketAddress_t* address, palIpV6Addr_t ipV6Addr); 00122 00123 /*! Get an IPv4 address from `palSocketAddress_t`. 00124 * @param[in] address The address to set. 00125 * @param[out] ipV4Addr The address that is set in `address`. 00126 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure. 00127 */ 00128 palStatus_t pal_getSockAddrIPV4Addr(const palSocketAddress_t* address, palIpV4Addr_t ipV4Addr); 00129 00130 /*! Get an IPv6 address from `palSocketAddress_t`. 00131 * @param[in] address The address to set. 00132 * @param[out] ipV6Addr The address that is set in `address`. 00133 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure. 00134 */ 00135 palStatus_t pal_getSockAddrIPV6Addr(const palSocketAddress_t* address, palIpV6Addr_t ipV6Addr); 00136 00137 /*! Get a port from `palSocketAddress_t`. 00138 * @param[in] address The address to set. 00139 * @param[out] port The port that is set in `address`. 00140 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure. 00141 */ 00142 palStatus_t pal_getSockAddrPort(const palSocketAddress_t* address, uint16_t* port); 00143 00144 /*! Get a network socket. 00145 * @param[in] domain The domain for the created socket (see `palSocketDomain_t` for supported types). 00146 * @param[in] type The type of the created socket (see `palSocketType_t` for supported types). 00147 * @param[in] nonBlockingSocket If true, the socket is created as non-blocking (with O_NONBLOCK set). 00148 * @param[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. 00149 * @param[out] socket The socket is returned through this output parameter. 00150 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure. 00151 */ 00152 palStatus_t pal_socket(palSocketDomain_t domain, palSocketType_t type, bool nonBlockingSocket, uint32_t interfaceNum, palSocket_t* socket); 00153 00154 /*! Set the value for a given socket option on a given network socket. 00155 * @param[in] socket The socket for which to get options. 00156 * @param[in] optionName The identification of the socket option for which we are getting the value (see enum palSocketOptionName_t for supported types). 00157 * @param[in] optionValue The buffer holding the option value to set for the given option. 00158 * @param[in] optionLength The size of the buffer provided for `optionValue`. 00159 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure. 00160 */ 00161 palStatus_t pal_setSocketOptions(palSocket_t socket, int optionName, const void* optionValue, palSocketLength_t optionLength); 00162 00163 /*! Check if a given socket is non-blocking. 00164 * @param[in] socket The socket to check. 00165 * @param[out] isNonBlocking True if the socket is non-blocking, otherwise false. 00166 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure. 00167 */ 00168 palStatus_t pal_isNonBlocking(palSocket_t socket, bool* isNonBlocking); 00169 00170 /*! Bind a given socket to a local address. 00171 * @param[in] socket The socket to bind. 00172 * @param[in] myAddress The address to bind to. 00173 * @param[in] addressLength The length of the address passed in `myAddress`. 00174 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure. 00175 */ 00176 palStatus_t pal_bind(palSocket_t socket, palSocketAddress_t* myAddress, palSocketLength_t addressLength); 00177 00178 /*! Receive a payload from the given socket. 00179 * @param[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).] 00180 * @param[out] buffer The buffer for the payload data. 00181 * @param[in] length The length of the buffer for the payload data. 00182 * @param[out] from The address that sent the payload. 00183 * @param[in, out] fromLength The length of the `from` address. Contains the amount of data actually written to the `from` address. 00184 * @param[out] bytesReceived The actual amount of payload data received in the buffer. 00185 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure. 00186 */ 00187 palStatus_t pal_receiveFrom(palSocket_t socket, void* buffer, size_t length, palSocketAddress_t* from, palSocketLength_t* fromLength, size_t* bytesReceived); 00188 00189 /*! Send a payload to the given address using the given socket. 00190 * @param[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).] 00191 * @param[in] buffer The buffer for the payload data. 00192 * @param[in] length The length of the buffer for the payload data. 00193 * @param[in] to The address to which the payload should be sent. 00194 * @param[in] toLength The length of the `to` address. 00195 * @param[out] bytesSent The actual amount of payload data sent. 00196 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure. 00197 */ 00198 palStatus_t pal_sendTo(palSocket_t socket, const void* buffer, size_t length, const palSocketAddress_t* to, palSocketLength_t toLength, size_t* bytesSent); 00199 00200 /*! Close a network socket. 00201 * @param[in,out] The socket to be closed. 00202 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure. 00203 \note Receives `palSocket_t*`, NOT `palSocket_t`, so that it can zero the socket to avoid re-use. 00204 */ 00205 palStatus_t pal_close(palSocket_t* socket); 00206 00207 /*! Get the number of current network interfaces. 00208 * @param[out] numInterfaces The number of interfaces. 00209 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure. 00210 */ 00211 palStatus_t pal_getNumberOfNetInterfaces(uint32_t* numInterfaces); 00212 00213 /*! Get information regarding the socket at the index/interface number given (this number is returned when registering the socket). 00214 * @param[in] interfaceNum The number of the interface to get information for. 00215 * @param[out] interfaceInfo Set to the information for the given interface number. 00216 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure. 00217 */ 00218 palStatus_t pal_getNetInterfaceInfo(uint32_t interfaceNum, palNetInterfaceInfo_t * interfaceInfo); 00219 00220 00221 #define PAL_NET_SOCKET_SELECT_MAX_SOCKETS 8 00222 #define PAL_NET_SOCKET_SELECT_RX_BIT (1) 00223 #define PAL_NET_SOCKET_SELECT_TX_BIT (2) 00224 #define PAL_NET_SOCKET_SELECT_ERR_BIT (4) 00225 00226 #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. */ 00227 #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. */ 00228 #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. */ 00229 00230 #if PAL_NET_TCP_AND_TLS_SUPPORT // The functionality below is supported only if TCP is supported. 00231 00232 00233 /*! Use the given socket to listen for incoming connections. This may also limit the queue of incoming connections. 00234 * @param[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).] 00235 * @param[in] backlog The amount of pending connections that can be saved for the socket. 00236 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure. 00237 */ 00238 palStatus_t pal_listen(palSocket_t socket, int backlog); 00239 00240 /*! Accept a connection on the given socket. 00241 * @param[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).] 00242 * @param[out] address The source address of the incoming connection. 00243 * @param[in, out] addressLen The length of the address field on input, the length of the data returned on output. 00244 * @param[out] acceptedSocket The socket of the accepted connection. 00245 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure. 00246 */ 00247 palStatus_t pal_accept(palSocket_t socket, palSocketAddress_t* address, palSocketLength_t* addressLen, palSocket_t* acceptedSocket); 00248 00249 /*! Open a connection from the given socket to the given address. 00250 * @param[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).] 00251 * @param[in] address The destination address of the connection. 00252 * @param[in] addressLen The length of the address field. 00253 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure. 00254 */ 00255 palStatus_t pal_connect(palSocket_t socket, const palSocketAddress_t* address, palSocketLength_t addressLen); 00256 00257 /*! Receive data from the given connected socket. 00258 * @param[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).] 00259 * @param[out] buf The output buffer for the message data. 00260 * @param[in] len The length of the input data buffer. 00261 * @param[out] recievedDataSize The length of the data actually received. 00262 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure. 00263 */ 00264 palStatus_t pal_recv(palSocket_t socket, void* buf, size_t len, size_t* recievedDataSize); 00265 00266 /*! Send a given buffer via the given connected socket. 00267 * @param[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).] 00268 * @param[in] buf The output buffer for the message data. 00269 * @param[in] len The length of the input data buffer. 00270 * @param[out] sentDataSize The length of the data sent. 00271 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure. 00272 */ 00273 palStatus_t pal_send(palSocket_t socket, const void* buf, size_t len, size_t* sentDataSize); 00274 00275 00276 #endif //PAL_NET_TCP_AND_TLS_SUPPORT 00277 00278 00279 #if PAL_NET_ASYNCHRONOUS_SOCKET_API 00280 00281 /*! The type of the callback funciton passed when creating asynchronous sockets. 00282 * @param[in] argument The user provided argument passed to the callback function. 00283 */ 00284 typedef void(*palAsyncSocketCallback_t )(void*); 00285 00286 /*! Get an asynchronous network socket. 00287 * @param[in] domain The domain for the created socket (see enum `palSocketDomain_t` for supported types). 00288 * @param[in] type The type for the created socket (see enum `palSocketType_t` for supported types). 00289 * @param[in] nonBlockingSocket If true, the socket is created as non-blocking (with O_NONBLOCK set). 00290 * @param[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. 00291 * @param[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). 00292 * @param[out] socket The socket is returned through this output parameter. 00293 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure. 00294 */ 00295 palStatus_t pal_asynchronousSocket(palSocketDomain_t domain, palSocketType_t type, bool nonBlockingSocket, uint32_t interfaceNum, palAsyncSocketCallback_t callback, palSocket_t* socket); 00296 00297 /*! Get an asynchronous network socket that passes the provided `callbackArgument` to the provided callback on callback events. 00298 * @param[in] domain The domain for the created socket (see enum `palSocketDomain_t` for supported types). 00299 * @param[in] type The type for the created socket (see enum `palSocketType_t` for supported types). 00300 * @param[in] nonBlockingSocket If true, the socket is created as non-blocking (with O_NONBLOCK set). 00301 * @param[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. 00302 * @param[in] callback A callback function that is called when any supported event happens in the given asynchronous socket. 00303 * @param[in] callbackArgument The argument with which the callback function is called when any supported event happens in the given asynchronous socket. 00304 * @param[out] socket The socket is returned through this output parameter. 00305 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure. 00306 */ 00307 palStatus_t pal_asynchronousSocketWithArgument(palSocketDomain_t domain, palSocketType_t type, bool nonBlockingSocket, uint32_t interfaceNum, palAsyncSocketCallback_t callback,void* callbackArgument, palSocket_t* socket); 00308 00309 00310 00311 #endif 00312 00313 #if PAL_NET_DNS_SUPPORT 00314 00315 /*! 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). 00316 * @param[in] url The URL (or IP address string) to be translated to a `palSocketAddress_t`. 00317 * @param[out] address The address for the output of the translation. 00318 */ 00319 palStatus_t pal_getAddressInfo(const char* url, palSocketAddress_t* address, palSocketLength_t* addressLength); 00320 00321 /*! Prototype of the callback function invoked when querying address info asynchronously (pal_getAddressInfoAsync). 00322 * @param[in] url The user provided url (or IP address string) that was requested to be translated 00323 * @param[in] address The address for the output of the translation 00324 * @param[in] addressLength The length of the address for the output of the translation in bytes 00325 * @param[in] status The status of the operation - PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure 00326 * @param[in] callbackArgument The user callback argument 00327 */ 00328 typedef void(*palGetAddressInfoAsyncCallback_t )(const char* url, palSocketAddress_t* address, palSocketLength_t* addressLength, palStatus_t status, void* callbackArgument); 00329 00330 /*! 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). \n 00331 \note The function is a non-blocking function. 00332 * @param[in] url The user provided url (or IP address string) to be translated 00333 * @param[out] address The address for the output of the translation 00334 * @param[out] addressLength The length of the address for the output of the translation in bytes 00335 * @param[in] callback The user provided callback to be invoked once the function has completed 00336 * @param[in] callbackArgument The user provided callback argument which will be passed back to the (user provided) callback function 00337 */ 00338 palStatus_t pal_getAddressInfoAsync(const char* url, palSocketAddress_t* address, palSocketLength_t* addressLength, palGetAddressInfoAsyncCallback_t callback, void* callbackArgument); 00339 00340 #endif 00341 00342 #ifdef __cplusplus 00343 } 00344 #endif 00345 #endif //_PAL_SOCKET_H 00346 00347
Generated on Tue Jul 12 2022 19:01:36 by 1.7.2