pal_network.h

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