Mistake on this page?
Report an issue in GitHub or email us
nsapi_dns.h
1 /*
2  * Original work Copyright (c) 2013 Henry Leinen (henry[dot]leinen [at] online [dot] de)
3  * Modified work Copyright (c) 2015 ARM Limited
4  * SPDX-License-Identifier: Apache-2.0
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 
19 /** \addtogroup netsocket */
20 /** @{*/
21 
22 #ifndef NSAPI_DNS_H
23 #define NSAPI_DNS_H
24 
25 #include "nsapi_types.h"
26 #ifdef __cplusplus
27 #include "netsocket/NetworkStack.h"
28 #endif
29 
30 #ifndef __cplusplus
31 
32 
33 /** Query a domain name server for an IP address of a given hostname
34  *
35  * @param stack Network stack as target for DNS query
36  * @param host Hostname to resolve
37  * @param addr Destination for the host address
38  * @param version IP version to resolve
39  * @return 0 on success, negative error code on failure
40  * NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
41  */
42 nsapi_error_t nsapi_dns_query(nsapi_stack_t *stack, const char *host,
43  nsapi_addr_t *addr, nsapi_version_t version);
44 
45 /** Query a domain name server for multiple IP address of a given hostname
46  *
47  * @param stack Network stack as target for DNS query
48  * @param host Hostname to resolve
49  * @param addr Array for the host addresses
50  * @param addr_count Number of addresses allocated in the array
51  * @param version IP version to resolve
52  * @return Number of addresses found on success, negative error code on failure
53  * NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
54  */
56  nsapi_addr_t *addr, nsapi_size_t addr_count, nsapi_version_t version);
57 
58 /** Add a domain name server to list of servers to query
59  *
60  * @param addr Destination for the host address
61  * @return 0 on success, negative error code on failure
62  */
63 nsapi_error_t nsapi_dns_add_server(nsapi_addr_t addr, const char *interface_name);
64 
65 
66 #else
67 
68 typedef mbed::Callback<nsapi_error_t (int delay_ms, mbed::Callback<void()> user_cb)> call_in_callback_cb_t;
69 
70 /** Query a domain name server for an IP address of a given hostname
71  *
72  * @param stack Network stack as target for DNS query
73  * @param host Hostname to resolve
74  * @param addr Destination for the host address
75  * @param version IP version to resolve (defaults to NSAPI_IPv4)
76  * @return 0 on success, negative error code on failure
77  * NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
78  */
79 nsapi_error_t nsapi_dns_query(NetworkStack *stack, const char *host,
80  SocketAddress *addr, nsapi_version_t version = NSAPI_IPv4);
81 
82 /** Query a domain name server for an IP address of a given hostname using Network interface name
83  *
84  * @param stack Network stack as target for DNS query
85  * @param host Hostname to resolve
86  * @param addr Destination for the host address
87  * @param interface_name Network interface name
88  * @param version IP version to resolve (defaults to NSAPI_IPv4)
89  * @return See @ref nsapi_dns_query_multiple
90  */
91 nsapi_error_t nsapi_dns_query(NetworkStack *stack, const char *host,
92  SocketAddress *addr, const char *interface_name, nsapi_version_t version = NSAPI_IPv4);
93 
94 
95 /** Query a domain name server for an IP address of a given hostname
96  *
97  * @param stack Network stack as target for DNS query
98  * @param host Hostname to resolve
99  * @param callback Callback that is called for result
100  * @param version IP version to resolve (defaults to NSAPI_IPv4)
101  * @return 0 on success, negative error code on failure or an unique id that
102  * represents the hostname translation operation and can be passed to
103  * cancel, NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
104  */
105 nsapi_error_t nsapi_dns_query_async(NetworkStack *stack, const char *host,
106  NetworkStack::hostbyname_cb_t callback, call_in_callback_cb_t call_in_cb,
107  nsapi_version_t version = NSAPI_IPv4);
108 
109 /** Query a domain name server for an IP address of a given hostname using Network interface name
110  *
111  * @param stack Network stack as target for DNS query
112  * @param host Hostname to resolve
113  * @param callback Callback that is called for result
114  * @param interface_name Network interface name
115  * @param version IP version to resolve (defaults to NSAPI_IPv4)
116  * @return 0 on success, negative error code on failure or an unique id that
117  * represents the hostname translation operation and can be passed to
118  * cancel, NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
119  */
120 nsapi_error_t nsapi_dns_query_async(NetworkStack *stack, const char *host,
121  NetworkStack::hostbyname_cb_t callback, call_in_callback_cb_t call_in_cb,
122  const char *interface_name, nsapi_version_t version = NSAPI_IPv4);
123 
124 /** Query a domain name server for an IP address of a given hostname (asynchronous)
125  *
126  * @param stack Network stack as target for DNS query
127  * @param host Hostname to resolve
128  * @param addr Destination for the host address
129  * @param version IP version to resolve (defaults to NSAPI_IPv4)
130  * @return 0 on success, negative error code on failure
131  * NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
132  */
133 extern "C" nsapi_error_t nsapi_dns_query(nsapi_stack_t *stack, const char *host,
134  nsapi_addr_t *addr, nsapi_version_t version = NSAPI_IPv4);
135 
136 /** Query a domain name server for an IP address of a given hostname
137  *
138  * @param stack Network stack as target for DNS query
139  * @param host Hostname to resolve
140  * @param addr Destination for the host address
141  * @param version IP version to resolve (defaults to NSAPI_IPv4)
142  * @return 0 on success, negative error code on failure
143  * NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
144  */
145 template <typename S>
146 nsapi_error_t nsapi_dns_query(S *stack, const char *host,
147  SocketAddress *addr, nsapi_version_t version = NSAPI_IPv4)
148 {
149  return nsapi_dns_query(nsapi_create_stack(stack), host, addr, version);
150 }
151 
152 /** Query a domain name server for multiple IP address of a given hostname
153  *
154  * @param stack Network stack as target for DNS query
155  * @param host Hostname to resolve
156  * @param addr Array for the host addresses
157  * @param addr_count Number of addresses allocated in the array
158  * @param version IP version to resolve (defaults to NSAPI_IPv4)
159  * @return Positive number of addresses found on success
160  * @retval NSAPI_ERROR_PARAMETER if provided parameters are invalid
161  * @retval NSAPI_ERROR_NO_MEMORY if allocation fails due to lack of memory
162  * @retval NSAPI_ERROR_DNS_FAILURE if DNS resolution fails
163  * @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled and
164  * DNS cannot be resolved immediately.
165  */
167  SocketAddress *addr, nsapi_size_t addr_count, const char *interface_name, nsapi_version_t version = NSAPI_IPv4);
168 
169 /** Query a domain name server for an IP address of a given hostname (asynchronous)
170  *
171  * @param stack Network stack as target for DNS query
172  * @param host Hostname to resolve
173  * @param callback Callback that is called for result
174  * @param addr_count Number of addresses allocated in the array
175  * @param version IP version to resolve (defaults to NSAPI_IPv4)
176  * @return 0 on success, negative error code on failure or an unique id that
177  represents the hostname translation operation and can be passed to
178  * cancel, NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
179  */
180 nsapi_size_or_error_t nsapi_dns_query_multiple_async(NetworkStack *stack, const char *host,
182  call_in_callback_cb_t call_in_cb, const char *interface_name, nsapi_version_t version = NSAPI_IPv4);
183 
184 /** Query a domain name server for multiple IP address of a given hostname
185  *
186  * @param stack Network stack as target for DNS query
187  * @param host Hostname to resolve
188  * @param addr Array for the host addresses
189  * @param addr_count Number of addresses allocated in the array
190  * @param version IP version to resolve (defaults to NSAPI_IPv4)
191  * @return Number of addresses found on success, negative error code on failure
192  * NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
193  */
194 extern "C" nsapi_size_or_error_t nsapi_dns_query_multiple(nsapi_stack_t *stack, const char *host,
195  nsapi_addr_t *addr, nsapi_size_t addr_count, const char *interface_name, nsapi_version_t version = NSAPI_IPv4);
196 
197 
198 /** Query a domain name server for multiple IP address of a given hostname
199  *
200  * @param stack Network stack as target for DNS query
201  * @param host Hostname to resolve
202  * @param addr Array for the host addresses
203  * @param addr_count Number of addresses allocated in the array
204  * @param version IP version to resolve (defaults to NSAPI_IPv4)
205  * @return Number of addresses found on success, negative error code on failure
206  * NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
207  */
208 template <typename S>
209 nsapi_size_or_error_t nsapi_dns_query_multiple(S *stack, const char *host,
210  SocketAddress *addr, nsapi_size_t addr_count, nsapi_version_t version = NSAPI_IPv4)
211 {
213  host, addr, addr_count, version);
214 }
215 
216 /** Cancels asynchronous hostname translation
217  *
218  * When translation is cancelled, callback will not be called.
219  *
220  * @param id Unique id of the hostname translation operation
221  * @return 0 on success, negative error code on failure
222  */
223 nsapi_error_t nsapi_dns_query_async_cancel(nsapi_size_or_error_t id);
224 
225 /** Set a call in callback
226  *
227  * Can be used to provide an application specific call in callback to
228  * DNS resolver. When callback is set it is used instead of stack
229  * specific call in callbacks.
230  *
231  * @param callback Callback
232  */
233 void nsapi_dns_call_in_set(call_in_callback_cb_t callback);
234 
235 /**
236  * @brief nsapi_dns_reset Resets all internal states and frees reserved memory, see NOTE!
237  * Can be used to clean up system resources when there is no need for network connections.
238  * NOTE: Does NOT clear asynchronous ongoing operations!
239  * Currently only cleans up DNS cache (if used)
240  */
241 void nsapi_dns_reset();
242 
243 /** Add a domain name server to list of servers to query
244  *
245  * @param addr Destination for the host address
246  * @return 0 on success, negative error code on failure
247  */
248 extern "C" nsapi_error_t nsapi_dns_add_server(nsapi_addr_t addr, const char *interface_name);
249 
250 /** Add a domain name server to list of servers to query
251  *
252  * @param addr Destination for the host address
253  * @return 0 on success, negative error code on failure
254  */
255 static inline nsapi_error_t nsapi_dns_add_server(const SocketAddress &address, const char *interface_name)
256 {
257  return nsapi_dns_add_server(address.get_addr(), interface_name);
258 }
259 
260 /** Add a domain name server to list of servers to query
261  *
262  * @param addr Destination for the host address
263  * @return 0 on success, negative error code on failure
264  */
265 static inline nsapi_error_t nsapi_dns_add_server(const char *address, const char *interface_name)
266 {
267  return nsapi_dns_add_server(SocketAddress(address), interface_name);
268 }
269 
270 
271 #endif
272 
273 #endif
274 
275 /** @}*/
nsapi_size_or_error_t nsapi_dns_query_multiple(nsapi_stack_t *stack, const char *host, nsapi_addr_t *addr, nsapi_size_t addr_count, nsapi_version_t version)
Query a domain name server for multiple IP address of a given hostname.
nsapi_stack structure
Definition: nsapi_types.h:368
NetworkStack * nsapi_create_stack(nsapi_stack_t *stack)
Convert a raw nsapi_stack_t object into a C++ NetworkStack object.
NetworkStack class.
Definition: NetworkStack.h:42
nsapi_error_t nsapi_dns_add_server(nsapi_addr_t addr, const char *interface_name)
Add a domain name server to list of servers to query.
signed int nsapi_error_t
Type used to represent error codes.
Definition: nsapi_types.h:140
Callback< R(ArgTs...)> callback(R(*func)(ArgTs...)=nullptr) noexcept
Create a callback class with type inferred from the arguments.
Definition: Callback.h:678
signed int nsapi_size_or_error_t
Type used to represent either a size or error passed through sockets.
Definition: nsapi_types.h:151
SocketAddress class.
Definition: SocketAddress.h:37
unsigned int nsapi_size_t
Type used to represent the size of data passed through sockets.
Definition: nsapi_types.h:144
NetworkStack class.
IP address structure for passing IP addresses by value.
Definition: nsapi_types.h:235
nsapi_addr_t get_addr() const
Get the raw IP address.
nsapi_error_t nsapi_dns_query(nsapi_stack_t *stack, const char *host, nsapi_addr_t *addr, nsapi_version_t version)
Query a domain name server for an IP address of a given hostname.
Callback class based on template specialization.
Definition: Callback.h:53
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.