pal_network.h

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 
00110 /*! Set an IPv4 address to `palSocketAddress_t` and `addressType` to IPv4.
00111 * @param[in,out] address The address to set.
00112 * @param[in] ipV4Addr The address value to set.
00113 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
00114 */
00115 palStatus_t pal_setSockAddrIPV4Addr(palSocketAddress_t* address, palIpV4Addr_t ipV4Addr);
00116 
00117 /*! Get an IPv4 address from `palSocketAddress_t`.
00118 * @param[in] address The address to set.
00119 * @param[out] ipV4Addr The address that is set in `address`.
00120 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
00121 */
00122 palStatus_t pal_getSockAddrIPV4Addr(const palSocketAddress_t* address, palIpV4Addr_t ipV4Addr);
00123 
00124 
00125 /*! Set an IPv6 address to `palSocketAddress_t` and the `addressType` to IPv6.
00126 * @param[in,out] address The address to set.
00127 * @param[in] ipV6Addr The address value to set.
00128 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
00129 */
00130 palStatus_t pal_setSockAddrIPV6Addr(palSocketAddress_t* address, palIpV6Addr_t ipV6Addr);
00131 
00132 /*! Get an IPv6 address from `palSocketAddress_t`.
00133 * @param[in] address The address to set.
00134 * @param[out] ipV6Addr The address that is set in `address`.
00135 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
00136 */
00137 palStatus_t pal_getSockAddrIPV6Addr(const palSocketAddress_t* address, palIpV6Addr_t ipV6Addr);
00138 
00139 
00140 /*! Get a port from `palSocketAddress_t`.
00141 * @param[in] address The address to set.
00142 * @param[out] port The port that is set in `address`.
00143 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
00144 */
00145 palStatus_t pal_getSockAddrPort(const palSocketAddress_t* address, uint16_t* port);
00146 
00147 /*! Get a network socket.
00148 * @param[in] domain The domain for the created socket (see `palSocketDomain_t` for supported types).
00149 * @param[in] type The type of the created socket (see `palSocketType_t` for supported types).
00150 * @param[in] nonBlockingSocket If true, the socket is created as non-blocking (with O_NONBLOCK set).
00151 * @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.
00152 * @param[out] socket The socket is returned through this output parameter.
00153 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
00154 */
00155 palStatus_t pal_socket(palSocketDomain_t  domain, palSocketType_t  type, bool nonBlockingSocket, uint32_t interfaceNum, palSocket_t* socket);
00156 
00157 /*!  Set the value for a given socket option on a given network socket.
00158 * @param[in] socket The socket for which to get options.
00159 * @param[in] optionName The identification of the socket option for which we are getting the value (see enum palSocketOptionName_t for supported types).
00160 * @param[in] optionValue The buffer holding the option value to set for the given option.
00161 * @param[in] optionLength  The size of the buffer provided for `optionValue`.
00162 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
00163 */
00164 palStatus_t pal_setSocketOptions(palSocket_t socket, int optionName, const void* optionValue, palSocketLength_t optionLength);
00165 
00166 /*! Check if a given socket is non-blocking.
00167 * @param[in] socket The socket to check.
00168 * @param[out] isNonBlocking True if the socket is non-blocking, otherwise false.
00169 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
00170 */
00171 palStatus_t pal_isNonBlocking(palSocket_t socket, bool* isNonBlocking);
00172 
00173 /*! Bind a given socket to a local address.
00174 * @param[in] socket The socket to bind.
00175 * @param[in] myAddress The address to bind to.
00176 * @param[in] addressLength The length of the address passed in `myAddress`.
00177 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
00178 */
00179 palStatus_t pal_bind(palSocket_t socket, palSocketAddress_t* myAddress, palSocketLength_t addressLength);
00180 
00181 /*! Receive a payload from the given socket.
00182 * @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).]
00183 * @param[out] buffer The buffer for the payload data.
00184 * @param[in] length The length of the buffer for the payload data.
00185 * @param[out] from The address that sent the payload.
00186 * @param[in, out] fromLength The length of the `from` address. Contains the amount of data actually written to the `from` address.
00187 * @param[out] bytesReceived The actual amount of payload data received in the buffer.
00188 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
00189 */
00190 palStatus_t pal_receiveFrom(palSocket_t socket, void* buffer, size_t length, palSocketAddress_t* from, palSocketLength_t* fromLength, size_t* bytesReceived);
00191 
00192 /*! Send a payload to the given address using the given socket.
00193 * @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).]
00194 * @param[in] buffer The buffer for the payload data.
00195 * @param[in] length The length of the buffer for the payload data.
00196 * @param[in] to The address to which the payload should be sent.
00197 * @param[in] toLength The length of the `to` address.
00198 * @param[out] bytesSent The actual amount of payload data sent.
00199 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
00200 */
00201 palStatus_t pal_sendTo(palSocket_t socket, const void* buffer, size_t length, const palSocketAddress_t* to, palSocketLength_t toLength, size_t* bytesSent);
00202 
00203 /*! Close a network socket.
00204 * @param[in,out] The socket to be closed.
00205 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
00206 \note Receives `palSocket_t*`, NOT `palSocket_t`, so that it can zero the socket to avoid re-use.
00207 */
00208 palStatus_t pal_close(palSocket_t* socket);
00209 
00210 /*! Get the number of current network interfaces.
00211 * @param[out] numInterfaces The number of interfaces.
00212 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
00213 */
00214 palStatus_t pal_getNumberOfNetInterfaces(uint32_t* numInterfaces);
00215 
00216 /*! Get information regarding the socket at the index/interface number given (this number is returned when registering the socket).
00217 * @param[in] interfaceNum The number of the interface to get information for.
00218 * @param[out] interfaceInfo Set to the information for the given interface number.
00219 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
00220 */
00221 palStatus_t pal_getNetInterfaceInfo(uint32_t interfaceNum, palNetInterfaceInfo_t * interfaceInfo);
00222 
00223 
00224 #define PAL_NET_SOCKET_SELECT_MAX_SOCKETS 8
00225 #define PAL_NET_SOCKET_SELECT_RX_BIT (1)
00226 #define PAL_NET_SOCKET_SELECT_TX_BIT (2)
00227 #define PAL_NET_SOCKET_SELECT_ERR_BIT (4)
00228 
00229 #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. */
00230 #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. */
00231 #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. */
00232 
00233 #if PAL_NET_TCP_AND_TLS_SUPPORT // The functionality below is supported only if TCP is supported.
00234 
00235 
00236 /*! Use the given socket to listen for incoming connections. This may also limit the queue of incoming connections.
00237 * @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).]
00238 * @param[in] backlog The amount of pending connections that can be saved for the socket.
00239 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
00240 */
00241 palStatus_t pal_listen(palSocket_t socket, int backlog);
00242 
00243 /*! Accept a connection on the given socket.
00244 * @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).]
00245 * @param[out] address The source address of the incoming connection.
00246 * @param[in, out] addressLen The length of the address field on input, the length of the data returned on output.
00247 * @param[out] acceptedSocket The socket of the accepted connection.
00248 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
00249 */
00250 palStatus_t pal_accept(palSocket_t socket, palSocketAddress_t* address, palSocketLength_t* addressLen, palSocket_t* acceptedSocket);
00251 
00252 /*! Open a connection from the given socket to the given address.
00253 * @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).]
00254 * @param[in] address The destination address of the connection.
00255 * @param[in] addressLen The length of the address field.
00256 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
00257 */
00258 palStatus_t pal_connect(palSocket_t socket, const palSocketAddress_t* address, palSocketLength_t addressLen);
00259 
00260 /*! Receive data from the given connected socket.
00261 * @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).]
00262 * @param[out] buf The output buffer for the message data.
00263 * @param[in] len The length of the input data buffer.
00264 * @param[out] recievedDataSize The length of the data actually received.
00265 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
00266 */
00267 palStatus_t pal_recv(palSocket_t socket, void* buf, size_t len, size_t* recievedDataSize);
00268 
00269 /*! Send a given buffer via the given connected socket.
00270 * @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).]
00271 * @param[in] buf The output buffer for the message data.
00272 * @param[in] len The length of the input data buffer.
00273 * @param[out] sentDataSize The length of the data sent.
00274 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
00275 */
00276 palStatus_t pal_send(palSocket_t socket, const void* buf, size_t len, size_t* sentDataSize);
00277 
00278 
00279 #endif //PAL_NET_TCP_AND_TLS_SUPPORT
00280 
00281 
00282 #if PAL_NET_ASYNCHRONOUS_SOCKET_API
00283 
00284 /*! The type of the callback funciton passed when creating asynchronous sockets.
00285 * @param[in] argument The user provided argument passed to the callback function.
00286 */
00287 typedef void(*palAsyncSocketCallback_t )(void*);
00288 
00289 /*! Get an asynchronous network socket.
00290 * @param[in] domain The domain for the created socket (see enum `palSocketDomain_t` for supported types).
00291 * @param[in] type The type for the created socket (see enum `palSocketType_t` for supported types).
00292 * @param[in] nonBlockingSocket If true, the socket is created as non-blocking (with O_NONBLOCK set).
00293 * @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.
00294 * @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).
00295 * @param[out] socket The socket is returned through this output parameter.
00296 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
00297 */
00298 palStatus_t pal_asynchronousSocket(palSocketDomain_t  domain, palSocketType_t  type, bool nonBlockingSocket, uint32_t interfaceNum, palAsyncSocketCallback_t  callback, palSocket_t* socket);
00299 
00300 /*! Get an asynchronous network socket that passes the provided `callbackArgument` to the provided callback on callback events.
00301 * @param[in] domain The domain for the created socket (see enum `palSocketDomain_t` for supported types).
00302 * @param[in] type The type for the created socket (see enum `palSocketType_t` for supported types).
00303 * @param[in] nonBlockingSocket If true, the socket is created as non-blocking (with O_NONBLOCK set).
00304 * @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.
00305 * @param[in] callback A callback function that is called when any supported event happens in the given asynchronous socket.
00306 * @param[in] callbackArgument The argument with which the callback function is called when any supported event happens in the given asynchronous socket.
00307 * @param[out] socket The socket is returned through this output parameter.
00308 \return PAL_SUCCESS (0) in case of success or a specific negative error code in case of failure.
00309 */
00310 palStatus_t pal_asynchronousSocketWithArgument(palSocketDomain_t  domain, palSocketType_t  type, bool nonBlockingSocket, uint32_t interfaceNum, palAsyncSocketCallback_t  callback,void* callbackArgument, palSocket_t* socket);
00311 
00312 
00313 
00314 #endif
00315 
00316 #if PAL_NET_DNS_SUPPORT
00317 
00318 /*! 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).
00319 * @param[in] url The URL (or IP address string) to be translated to a `palSocketAddress_t`.
00320 * @param[out] address The address for the output of the translation.
00321 */
00322 palStatus_t pal_getAddressInfo(const char* url, palSocketAddress_t* address, palSocketLength_t* addressLength);
00323 
00324 /*! Prototype of the callback function invoked when querying address info asynchronously (pal_getAddressInfoAsync).
00325 * @param[in] url The user provided url (or IP address string) that was requested to be translated
00326 * @param[in] address The address for the output of the translation
00327 * @param[in] addressLength The length of the address for the output of the translation in bytes
00328 * @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
00329 * @param[in] callbackArgument The user callback argument
00330 */
00331 #ifndef PAL_DNS_API_V2
00332 typedef void(*palGetAddressInfoAsyncCallback_t )(const char* url, palSocketAddress_t* address, palSocketLength_t* addressLength, palStatus_t status, void* callbackArgument);
00333 
00334 /*! 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
00335 \note The function is a non-blocking function.
00336 * @param[in] url The user provided url (or IP address string) to be translated
00337 * @param[out] address The address for the output of the translation
00338 * @param[out] addressLength The length of the address for the output of the translation in bytes
00339 * @param[in] callback The user provided callback to be invoked once the function has completed
00340 * @param[in] callbackArgument The user provided callback argument which will be passed back to the (user provided) callback function
00341 */
00342 palStatus_t pal_getAddressInfoAsync(const char* url, palSocketAddress_t* address, palSocketLength_t* addressLength, palGetAddressInfoAsyncCallback_t  callback, void* callbackArgument);
00343 #else
00344 typedef int32_t palDNSQuery_t; /*! PAL DNS query handle, may be used to cancel the asynchronous DNS query. */
00345 
00346 /*! Prototype of the callback function invoked when querying address info asynchronously (pal_getAddressInfoAsync).
00347 * @param[in] url The user provided url (or IP address string) that was requested to be translated
00348 * @param[out] address The address for the output of the translation
00349 * @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
00350 * @param[in] callbackArgument The user callback argument
00351 */
00352 typedef void(*palGetAddressInfoAsyncCallback_t )(const char* url, palSocketAddress_t* address, palStatus_t status, void* callbackArgument);
00353 
00354 /*! structure used by pal_getAddressInfoAsync
00355 * @param[in] url The user provided url (or IP address string) that was requested to be translated
00356 * @param[out] address The address for the output of the translation
00357 * @param[in] callback address of palGetAddressInfoAsyncCallback_t.
00358 * @param[in] callbackArgument The user callback argument of palGetAddressInfoAsyncCallback_t
00359 * @param[out] queryHandle handler ID, which can be used for calcel request.
00360 */
00361 typedef struct pal_asyncAddressInfo
00362 {
00363     char* url;
00364     palSocketAddress_t* address;
00365     palGetAddressInfoAsyncCallback_t  callback;
00366     void* callbackArgument;
00367     palDNSQuery_t *queryHandle;
00368 } pal_asyncAddressInfo_t ;
00369 
00370 /*! 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
00371 \note The function is a non-blocking function.
00372 * @param[in] url The user provided url (or IP address string) to be translated
00373 * @param[out] address The address for the output of the translation
00374 * @param[in] callback The user provided callback to be invoked once the function has completed
00375 * @param[out] queryHandle DNS query handler. Caller must take of care allocation. If not used then use NULL.
00376 */
00377 palStatus_t pal_getAddressInfoAsync(const char* url, 
00378                                      palSocketAddress_t* address, 
00379                                      palGetAddressInfoAsyncCallback_t  callback, 
00380                                      void* callbackArgument, 
00381                                      palDNSQuery_t* queryHandle);
00382 
00383 /*! This function is cancelation for pal_getAddressInfoAsync. 
00384 * @param[in] queryHandle Id of ongoing DNS query.
00385 */
00386 palStatus_t pal_cancelAddressInfoAsync(palDNSQuery_t queryHandle);
00387 #endif  // #ifndef PAL_DNS_API_V2
00388 
00389 #endif  // PAL_NET_DNS_SUPPORT
00390 
00391 #ifdef __cplusplus
00392 }
00393 #endif
00394 #endif //_PAL_SOCKET_H
00395 
00396