nsapi_dns.h

00001 /*
00002  * Original work Copyright (c) 2013 Henry Leinen (henry[dot]leinen [at] online [dot] de)
00003  * Modified work Copyright (c) 2015 ARM Limited
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 /** \addtogroup netsocket */
00019 /** @{*/
00020 
00021 #ifndef NSAPI_DNS_H
00022 #define NSAPI_DNS_H
00023 
00024 #include "nsapi_types.h"
00025 #ifdef __cplusplus
00026 #include "netsocket/NetworkStack.h"
00027 #endif
00028 
00029 #ifndef __cplusplus
00030 
00031 
00032 /** Query a domain name server for an IP address of a given hostname
00033  *
00034  *  @param stack    Network stack as target for DNS query
00035  *  @param host     Hostname to resolve
00036  *  @param addr     Destination for the host address
00037  *  @param version  IP version to resolve
00038  *  @return         0 on success, negative error code on failure
00039  *                  NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
00040  */
00041 nsapi_error_t nsapi_dns_query(nsapi_stack_t *stack, const char *host,
00042                               nsapi_addr_t *addr, nsapi_version_t version);
00043 
00044 /** Query a domain name server for multiple IP address of a given hostname
00045  *
00046  *  @param stack      Network stack as target for DNS query
00047  *  @param host       Hostname to resolve
00048  *  @param addr       Array for the host addresses
00049  *  @param addr_count Number of addresses allocated in the array
00050  *  @param version    IP version to resolve
00051  *  @return           Number of addresses found on success, negative error code on failure
00052  *                    NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
00053  */
00054 nsapi_size_or_error_t nsapi_dns_query_multiple(nsapi_stack_t *stack, const char *host,
00055                                                nsapi_addr_t *addr, nsapi_size_t addr_count, nsapi_version_t version);
00056 
00057 /** Add a domain name server to list of servers to query
00058  *
00059  *  @param addr     Destination for the host address
00060  *  @return         0 on success, negative error code on failure
00061  */
00062 nsapi_error_t nsapi_dns_add_server(nsapi_addr_t addr, const char *interface_name);
00063 
00064 
00065 #else
00066 
00067 typedef mbed::Callback<nsapi_error_t (int delay_ms, mbed::Callback<void()> user_cb)> call_in_callback_cb_t;
00068 
00069 /** Query a domain name server for an IP address of a given hostname
00070  *
00071  *  @param stack    Network stack as target for DNS query
00072  *  @param host     Hostname to resolve
00073  *  @param addr     Destination for the host address
00074  *  @param version  IP version to resolve (defaults to NSAPI_IPv4)
00075  *  @return         0 on success, negative error code on failure
00076  *                  NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
00077  */
00078 nsapi_error_t nsapi_dns_query(NetworkStack *stack, const char *host,
00079                               SocketAddress *addr, nsapi_version_t version = NSAPI_IPv4 );
00080 
00081 /** Query a domain name server for an IP address of a given hostname using Network interface name
00082  *
00083  *  @param stack    Network stack as target for DNS query
00084  *  @param host     Hostname to resolve
00085  *  @param addr     Destination for the host address
00086  *  @param interface_name Network interface name
00087  *  @param version  IP version to resolve (defaults to NSAPI_IPv4)
00088  *  @return         See @ref nsapi_dns_query_multiple
00089  */
00090 nsapi_error_t nsapi_dns_query(NetworkStack *stack, const char *host,
00091                               SocketAddress *addr, const char *interface_name, nsapi_version_t version = NSAPI_IPv4 );
00092 
00093 
00094 /** Query a domain name server for an IP address of a given hostname
00095  *
00096  *  @param stack    Network stack as target for DNS query
00097  *  @param host     Hostname to resolve
00098  *  @param callback Callback that is called for result
00099  *  @param version  IP version to resolve (defaults to NSAPI_IPv4)
00100  *  @return         0 on success, negative error code on failure or an unique id that
00101  *                  represents the hostname translation operation and can be passed to
00102  *                  cancel, NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
00103  */
00104 nsapi_error_t nsapi_dns_query_async(NetworkStack *stack, const char *host,
00105                                     NetworkStack::hostbyname_cb_t callback, call_in_callback_cb_t call_in_cb,
00106                                     nsapi_version_t version = NSAPI_IPv4 );
00107 
00108 /** Query a domain name server for an IP address of a given hostname using Network interface name
00109  *
00110  *  @param stack    Network stack as target for DNS query
00111  *  @param host     Hostname to resolve
00112  *  @param callback Callback that is called for result
00113  *  @param interface_name Network interface name
00114  *  @param version  IP version to resolve (defaults to NSAPI_IPv4)
00115  *  @return         0 on success, negative error code on failure or an unique id that
00116  *                  represents the hostname translation operation and can be passed to
00117  *                  cancel, NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
00118  */
00119 nsapi_error_t nsapi_dns_query_async(NetworkStack *stack, const char *host,
00120                                     NetworkStack::hostbyname_cb_t callback, call_in_callback_cb_t call_in_cb,
00121                                     const char *interface_name, nsapi_version_t version = NSAPI_IPv4 );
00122 
00123 /** Query a domain name server for an IP address of a given hostname (asynchronous)
00124  *
00125  *  @param stack    Network stack as target for DNS query
00126  *  @param host     Hostname to resolve
00127  *  @param addr     Destination for the host address
00128  *  @param version  IP version to resolve (defaults to NSAPI_IPv4)
00129  *  @return         0 on success, negative error code on failure
00130  *                  NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
00131  */
00132 extern "C" nsapi_error_t nsapi_dns_query(nsapi_stack_t *stack, const char *host,
00133                                          nsapi_addr_t *addr, nsapi_version_t version = NSAPI_IPv4 );
00134 
00135 /** Query a domain name server for an IP address of a given hostname
00136  *
00137  *  @param stack    Network stack as target for DNS query
00138  *  @param host     Hostname to resolve
00139  *  @param addr     Destination for the host address
00140  *  @param version  IP version to resolve (defaults to NSAPI_IPv4)
00141  *  @return         0 on success, negative error code on failure
00142  *                  NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
00143  */
00144 template <typename S>
00145 nsapi_error_t nsapi_dns_query(S *stack, const char *host,
00146                               SocketAddress *addr, nsapi_version_t version = NSAPI_IPv4 )
00147 {
00148     return nsapi_dns_query(nsapi_create_stack(stack), host, addr, version);
00149 }
00150 
00151 /** Query a domain name server for multiple IP address of a given hostname
00152  *
00153  *  @param stack      Network stack as target for DNS query
00154  *  @param host       Hostname to resolve
00155  *  @param addr       Array for the host addresses
00156  *  @param addr_count Number of addresses allocated in the array
00157  *  @param version    IP version to resolve (defaults to NSAPI_IPv4)
00158  *  @return           Positive number of addresses found on success
00159  *  @retval           NSAPI_ERROR_PARAMETER if provided parameters are invalid
00160  *  @retval           NSAPI_ERROR_NO_MEMORY if allocation fails due to lack of memory
00161  *  @retval           NSAPI_ERROR_DNS_FAILURE if DNS resolution fails
00162  *  @retval           NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled and
00163  *                    DNS cannot be resolved immediately.
00164  */
00165 nsapi_size_or_error_t nsapi_dns_query_multiple(NetworkStack *stack, const char *host,
00166                                                SocketAddress *addr, nsapi_size_t addr_count,  const char *interface_name, nsapi_version_t version = NSAPI_IPv4 );
00167 
00168 /** Query a domain name server for an IP address of a given hostname (asynchronous)
00169  *
00170  *  @param stack      Network stack as target for DNS query
00171  *  @param host       Hostname to resolve
00172  *  @param callback   Callback that is called for result
00173  *  @param addr_count Number of addresses allocated in the array
00174  *  @param version    IP version to resolve (defaults to NSAPI_IPv4)
00175  *  @return           0 on success, negative error code on failure or an unique id that
00176                       represents the hostname translation operation and can be passed to
00177  *                    cancel, NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
00178  */
00179 nsapi_size_or_error_t nsapi_dns_query_multiple_async(NetworkStack *stack, const char *host,
00180                                                      NetworkStack::hostbyname_cb_t callback, nsapi_size_t addr_count,
00181                                                      call_in_callback_cb_t call_in_cb, const char *interface_name, nsapi_version_t version = NSAPI_IPv4 );
00182 
00183 /** Query a domain name server for multiple IP address of a given hostname
00184  *
00185  *  @param stack      Network stack as target for DNS query
00186  *  @param host       Hostname to resolve
00187  *  @param addr       Array for the host addresses
00188  *  @param addr_count Number of addresses allocated in the array
00189  *  @param version    IP version to resolve (defaults to NSAPI_IPv4)
00190  *  @return           Number of addresses found on success, negative error code on failure
00191  *                    NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
00192  */
00193 extern "C" nsapi_size_or_error_t nsapi_dns_query_multiple(nsapi_stack_t *stack, const char *host,
00194                                                           nsapi_addr_t *addr, nsapi_size_t addr_count, const char *interface_name, nsapi_version_t version = NSAPI_IPv4 );
00195 
00196 
00197 /** Query a domain name server for multiple IP address of a given hostname
00198  *
00199  *  @param stack      Network stack as target for DNS query
00200  *  @param host       Hostname to resolve
00201  *  @param addr       Array for the host addresses
00202  *  @param addr_count Number of addresses allocated in the array
00203  *  @param version    IP version to resolve (defaults to NSAPI_IPv4)
00204  *  @return           Number of addresses found on success, negative error code on failure
00205  *                    NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
00206  */
00207 template <typename S>
00208 nsapi_size_or_error_t nsapi_dns_query_multiple(S *stack, const char *host,
00209                                                SocketAddress *addr, nsapi_size_t addr_count, nsapi_version_t version = NSAPI_IPv4 )
00210 {
00211     return nsapi_dns_query_multiple(nsapi_create_stack(stack),
00212                                     host, addr, addr_count, version);
00213 }
00214 
00215 /** Cancels asynchronous hostname translation
00216   *
00217   *  When translation is cancelled, callback will not be called.
00218   *
00219   *  @param id       Unique id of the hostname translation operation
00220   *  @return         0 on success, negative error code on failure
00221   */
00222 nsapi_error_t nsapi_dns_query_async_cancel(nsapi_size_or_error_t id);
00223 
00224 /** Set a call in callback
00225  *
00226  *  Can be used to provide an application specific call in callback to
00227  *  DNS resolver. When callback is set it is used instead of stack
00228  *  specific call in callbacks.
00229  *
00230  *  @param callback  Callback
00231  */
00232 void nsapi_dns_call_in_set(call_in_callback_cb_t callback);
00233 
00234 /**
00235  * @brief nsapi_dns_reset Resets all internal states and frees reserved memory, see NOTE!
00236  * Can be used to clean up system resources when there is no need for network connections.
00237  * NOTE: Does NOT clear asynchronous ongoing operations!
00238  * Currently only cleans up DNS cache (if used)
00239  */
00240 void nsapi_dns_reset();
00241 
00242 /** Add a domain name server to list of servers to query
00243  *
00244  *  @param addr     Destination for the host address
00245  *  @return         0 on success, negative error code on failure
00246  */
00247 extern "C" nsapi_error_t nsapi_dns_add_server(nsapi_addr_t addr, const char *interface_name);
00248 
00249 /** Add a domain name server to list of servers to query
00250  *
00251  *  @param addr     Destination for the host address
00252  *  @return         0 on success, negative error code on failure
00253  */
00254 static inline nsapi_error_t nsapi_dns_add_server(const SocketAddress &address, const char *interface_name)
00255 {
00256     return nsapi_dns_add_server(address.get_addr(), interface_name);
00257 }
00258 
00259 /** Add a domain name server to list of servers to query
00260  *
00261  *  @param addr     Destination for the host address
00262  *  @return         0 on success, negative error code on failure
00263  */
00264 static inline nsapi_error_t nsapi_dns_add_server(const char *address, const char *interface_name)
00265 {
00266     return nsapi_dns_add_server(SocketAddress(address), interface_name);
00267 }
00268 
00269 
00270 #endif
00271 
00272 #endif
00273 
00274 /** @}*/