nsapi_dns.h

00001 /* nsapi_dns.h
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 #ifndef NSAPI_DNS_H
00018 #define NSAPI_DNS_H
00019 
00020 #include "nsapi_types.h"
00021 #ifdef __cplusplus
00022 #include "network-socket/NetworkStack.h"
00023 #endif
00024 
00025 #ifndef __cplusplus
00026 
00027 
00028 /** Query a domain name server for an IP address of a given hostname
00029  *
00030  *  @param stack    Network stack as target for DNS query
00031  *  @param addr     Destination for the host address
00032  *  @param host     Hostname to resolve
00033  *  @param version  IP version to resolve
00034  *  @return         0 on success, negative error code on failure
00035  *                  NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
00036  */
00037 int nsapi_dns_query(nsapi_stack_t *stack, nsapi_addr_t *addr,
00038         const char *host, nsapi_version_t version);
00039 
00040 /** Query a domain name server for multiple IP address of a given hostname
00041  *
00042  *  @param stack      Network stack as target for DNS query
00043  *  @param addr       Array for the host addresses
00044  *  @param addr_count Number of addresses allocated in the array
00045  *  @param host       Hostname to resolve
00046  *  @param version    IP version to resolve
00047  *  @return           Number of addresses found on success, negative error code on failure
00048  *                    NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
00049  */
00050 int nsapi_dns_query_multiple(nsapi_stack_t *stack,
00051         nsapi_addr_t *addr, unsigned addr_count,
00052         const char *host, nsapi_version_t version);
00053 
00054 /** Add a domain name server to list of servers to query
00055  *
00056  *  @param addr     Destination for the host address
00057  *  @return         0 on success, negative error code on failure
00058  */
00059 int nsapi_dns_add_server(nsapi_addr_t addr);
00060 
00061 
00062 #else
00063 
00064 
00065 /** Query a domain name server for an IP address of a given hostname
00066  *
00067  *  @param stack    Network stack as target for DNS query
00068  *  @param addr     Destination for the host address
00069  *  @param host     Hostname to resolve
00070  *  @param version  IP version to resolve (defaults to NSAPI_IPv4)
00071  *  @return         0 on success, negative error code on failure
00072  *                  NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
00073  */
00074 int nsapi_dns_query(NetworkStack *stack, SocketAddress *addr,
00075         const char *host, nsapi_version_t version = NSAPI_IPv4);
00076 
00077 /** Query a domain name server for an IP address of a given hostname
00078  *
00079  *  @param stack    Network stack as target for DNS query
00080  *  @param addr     Destination for the host address
00081  *  @param host     Hostname to resolve
00082  *  @param version  IP version to resolve (defaults to NSAPI_IPv4)
00083  *  @return         0 on success, negative error code on failure
00084  *                  NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
00085  */
00086 extern "C" int nsapi_dns_query(nsapi_stack_t *stack, nsapi_addr_t *addr,
00087         const char *host, nsapi_version_t version = NSAPI_IPv4);
00088 
00089 /** Query a domain name server for an IP address of a given hostname
00090  *
00091  *  @param stack    Network stack as target for DNS query
00092  *  @param addr     Destination for the host address
00093  *  @param host     Hostname to resolve
00094  *  @param version  IP version to resolve (defaults to NSAPI_IPv4)
00095  *  @return         0 on success, negative error code on failure
00096  *                  NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
00097  */
00098 template <typename S>
00099 int nsapi_dns_query(S *stack, SocketAddress *addr,
00100         const char *host, nsapi_version_t version = NSAPI_IPv4)
00101 {
00102     return nsapi_dns_query(nsapi_create_stack(stack), addr, host, version);
00103 }
00104 
00105 /** Query a domain name server for multiple IP address of a given hostname
00106  *
00107  *  @param stack      Network stack as target for DNS query
00108  *  @param addr       Array for the host addresses
00109  *  @param addr_count Number of addresses allocated in the array
00110  *  @param host       Hostname to resolve
00111  *  @param version    IP version to resolve (defaults to NSAPI_IPv4)
00112  *  @return           Number of addresses found on success, negative error code on failure
00113  *                    NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
00114  */
00115 int nsapi_dns_query_multiple(NetworkStack *stack,
00116         SocketAddress *addr, unsigned addr_count,
00117         const char *host, nsapi_version_t version = NSAPI_IPv4);
00118 
00119 /** Query a domain name server for multiple IP address of a given hostname
00120  *
00121  *  @param stack      Network stack as target for DNS query
00122  *  @param addr       Array for the host addresses
00123  *  @param addr_count Number of addresses allocated in the array
00124  *  @param host       Hostname to resolve
00125  *  @param version    IP version to resolve (defaults to NSAPI_IPv4)
00126  *  @return           Number of addresses found on success, negative error code on failure
00127  *                    NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
00128  */
00129 extern "C" int nsapi_dns_query_multiple(nsapi_stack_t *stack,
00130         nsapi_addr_t *addr, unsigned addr_count,
00131         const char *host, nsapi_version_t version = NSAPI_IPv4);
00132 
00133 /** Query a domain name server for multiple IP address of a given hostname
00134  *
00135  *  @param stack      Network stack as target for DNS query
00136  *  @param addr       Array for the host addresses
00137  *  @param addr_count Number of addresses allocated in the array
00138  *  @param host       Hostname to resolve
00139  *  @param version    IP version to resolve (defaults to NSAPI_IPv4)
00140  *  @return           Number of addresses found on success, negative error code on failure
00141  *                    NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
00142  */
00143 template <typename S>
00144 int nsapi_dns_query_multiple(S *stack,
00145         SocketAddress *addr, unsigned addr_count,
00146         const char *host, nsapi_version_t version = NSAPI_IPv4)
00147 {
00148     return nsapi_dns_query_multiple(nsapi_create_stack(stack),
00149                 addr, addr_count, host, version);
00150 }
00151 
00152 /** Add a domain name server to list of servers to query
00153  *
00154  *  @param addr     Destination for the host address
00155  *  @return         0 on success, negative error code on failure
00156  */
00157 extern "C" int nsapi_dns_add_server(nsapi_addr_t addr);
00158 
00159 /** Add a domain name server to list of servers to query
00160  *
00161  *  @param addr     Destination for the host address
00162  *  @return         0 on success, negative error code on failure
00163  */
00164 static inline int nsapi_dns_add_server(const SocketAddress &address)
00165 {
00166     return nsapi_dns_add_server(address.get_addr());
00167 }
00168 
00169 /** Add a domain name server to list of servers to query
00170  *
00171  *  @param addr     Destination for the host address
00172  *  @return         0 on success, negative error code on failure
00173  */
00174 static inline int nsapi_dns_add_server(const char *address)
00175 {
00176     return nsapi_dns_add_server(SocketAddress(address));
00177 }
00178 
00179 
00180 #endif
00181 
00182 #endif