Keil Studio Cloud
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  */
54 nsapi_size_or_error_t nsapi_dns_query_multiple(nsapi_stack_t *stack, const char *host,
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 0 on success, negative error code on failure
89  * NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
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 Number of addresses found on success, negative error code on failure
160  * NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
161  */
162 nsapi_size_or_error_t nsapi_dns_query_multiple(NetworkStack *stack, const char *host,
163  SocketAddress *addr, nsapi_size_t addr_count, const char *interface_name, nsapi_version_t version = NSAPI_IPv4);
164 
165 /** Query a domain name server for an IP address of a given hostname (asynchronous)
166  *
167  * @param stack Network stack as target for DNS query
168  * @param host Hostname to resolve
169  * @param callback Callback that is called for result
170  * @param addr_count Number of addresses allocated in the array
171  * @param version IP version to resolve (defaults to NSAPI_IPv4)
172  * @return 0 on success, negative error code on failure or an unique id that
173  represents the hostname translation operation and can be passed to
174  * cancel, NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
175  */
176 nsapi_size_or_error_t nsapi_dns_query_multiple_async(NetworkStack *stack, const char *host,
177  NetworkStack::hostbyname_cb_t callback, nsapi_size_t addr_count,
178  call_in_callback_cb_t call_in_cb, const char *interface_name, nsapi_version_t version = NSAPI_IPv4);
179 
180 /** Query a domain name server for multiple IP address of a given hostname
181  *
182  * @param stack Network stack as target for DNS query
183  * @param host Hostname to resolve
184  * @param addr Array for the host addresses
185  * @param addr_count Number of addresses allocated in the array
186  * @param version IP version to resolve (defaults to NSAPI_IPv4)
187  * @return Number of addresses found on success, negative error code on failure
188  * NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
189  */
190 extern "C" nsapi_size_or_error_t nsapi_dns_query_multiple(nsapi_stack_t *stack, const char *host,
191  nsapi_addr_t *addr, nsapi_size_t addr_count, const char *interface_name, nsapi_version_t version = NSAPI_IPv4);
192 
193 
194 /** Query a domain name server for multiple IP address of a given hostname
195  *
196  * @param stack Network stack as target for DNS query
197  * @param host Hostname to resolve
198  * @param addr Array for the host addresses
199  * @param addr_count Number of addresses allocated in the array
200  * @param version IP version to resolve (defaults to NSAPI_IPv4)
201  * @return Number of addresses found on success, negative error code on failure
202  * NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
203  */
204 template <typename S>
205 nsapi_size_or_error_t nsapi_dns_query_multiple(S *stack, const char *host,
206  SocketAddress *addr, nsapi_size_t addr_count, nsapi_version_t version = NSAPI_IPv4)
207 {
208  return nsapi_dns_query_multiple(nsapi_create_stack(stack),
209  host, addr, addr_count, version);
210 }
211 
212 /** Cancels asynchronous hostname translation
213  *
214  * When translation is cancelled, callback will not be called.
215  *
216  * @param id Unique id of the hostname translation operation
217  * @return 0 on success, negative error code on failure
218  */
219 nsapi_error_t nsapi_dns_query_async_cancel(nsapi_size_or_error_t id);
220 
221 /** Set a call in callback
222  *
223  * Can be used to provide an application specific call in callback to
224  * DNS resolver. When callback is set it is used instead of stack
225  * specific call in callbacks.
226  *
227  * @param callback Callback
228  */
229 void nsapi_dns_call_in_set(call_in_callback_cb_t callback);
230 
231 /**
232  * @brief nsapi_dns_reset Resets all internal states and frees reserved memory, see NOTE!
233  * Can be used to clean up system resources when there is no need for network connections.
234  * NOTE: Does NOT clear asynchronous ongoing operations!
235  * Currently only cleans up DNS cache (if used)
236  */
237 void nsapi_dns_reset();
238 
239 /** Add a domain name server to list of servers to query
240  *
241  * @param addr Destination for the host address
242  * @return 0 on success, negative error code on failure
243  */
244 extern "C" nsapi_error_t nsapi_dns_add_server(nsapi_addr_t addr, const char *interface_name);
245 
246 /** Add a domain name server to list of servers to query
247  *
248  * @param addr Destination for the host address
249  * @return 0 on success, negative error code on failure
250  */
251 static inline nsapi_error_t nsapi_dns_add_server(const SocketAddress &address, const char *interface_name)
252 {
253  return nsapi_dns_add_server(address.get_addr(), interface_name);
254 }
255 
256 /** Add a domain name server to list of servers to query
257  *
258  * @param addr Destination for the host address
259  * @return 0 on success, negative error code on failure
260  */
261 static inline nsapi_error_t nsapi_dns_add_server(const char *address, const char *interface_name)
262 {
263  return nsapi_dns_add_server(SocketAddress(address), interface_name);
264 }
265 
266 
267 #endif
268 
269 #endif
270 
271 /** @}*/
nsapi_dns_query_multiple
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
nsapi_stack structure
Definition: nsapi_types.h:317
nsapi_create_stack
NetworkStack * nsapi_create_stack(nsapi_stack_t *stack)
Convert a raw nsapi_stack_t object into a C++ NetworkStack object.
NetworkStack
NetworkStack class.
Definition: NetworkStack.h:40
nsapi_dns_add_server
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.
nsapi_error_t
signed int nsapi_error_t
Type used to represent error codes.
Definition: nsapi_types.h:95
nsapi_size_or_error_t
signed int nsapi_size_or_error_t
Type used to represent either a size or error passed through sockets.
Definition: nsapi_types.h:106
NSAPI_IPv4
Definition: nsapi_types.h:182
SocketAddress
SocketAddress class.
Definition: SocketAddress.h:35
mbed::callback
Callback< R(ArgTs...)> callback(R(*func)(ArgTs...)=0)
Create a callback class with type inferred from the arguments.
Definition: Callback.h:709
nsapi_size_t
unsigned int nsapi_size_t
Type used to represent the size of data passed through sockets.
Definition: nsapi_types.h:99
NetworkStack.h
NetworkStack class.
nsapi_addr
IP address structure for passing IP addresses by value.
Definition: nsapi_types.h:188
SocketAddress::get_addr
nsapi_addr_t get_addr() const
Get the raw IP address.
nsapi_dns_query
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.
mbed::Callback
Callback class based on template specialization.
Definition: Callback.h:39
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.