nsapi_dns.h

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