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