Mistake on this page?
Report an issue in GitHub or email us
DNS.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2018 ARM Limited
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 /** @file DNS.h Domain Name Service */
18 /** @addtogroup netsocket
19  * @{ */
20 
21 #ifndef DNS_H
22 #define DNS_H
23 
24 /** Base class for DNS provider */
25 class DNS {
26 public:
27 
28  /** Translate a hostname to an IP address with specific version using network interface name.
29  *
30  * The hostname may be either a domain name or an IP address. If the
31  * hostname is an IP address, no network transactions will be performed.
32  *
33  * If no stack-specific DNS resolution is provided, the hostname
34  * will be resolve using a UDP socket on the stack.
35  *
36  * @param host Hostname to resolve.
37  * @param address Pointer to a SocketAddress to store the result.
38  * @param version IP version of address to resolve, NSAPI_UNSPEC indicates
39  * version is chosen by the stack (defaults to NSAPI_UNSPEC).
40  * @param interface_name Network interface name
41  * @return NSAPI_ERROR_OK on success, negative error code on failure.
42  */
43  virtual nsapi_error_t gethostbyname(const char *host,
44  SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC, const char *interface_name = NULL) = 0;
45 
46  /** Translate a hostname to the multiple IP addresses with specific version using network interface name.
47  *
48  * The hostname may be either a domain name or an IP address. If the
49  * hostname is an IP address, no network transactions will be performed.
50  *
51  * If no stack-specific DNS resolution is provided, the hostname
52  * will be resolve using a UDP socket on the stack.
53  *
54  * @param hostname Hostname to resolve.
55  * @param hints Pointer to a SocketAddress with query parameters.
56  * @param res Pointer to a SocketAddress array to store the result..
57  * @param interface_name Network interface name
58  * @return number of results on success, negative error code on failure.
59  */
60  virtual nsapi_value_or_error_t getaddrinfo(const char *hostname, SocketAddress *hints, SocketAddress **res, const char *interface_name = NULL) = 0;
61 
62  /** Hostname translation callback for gethostbyname_async.
63  *
64  * The callback is called after DNS resolution completes, or a failure occurs.
65  *
66  * Callback should not take more than 10ms to execute, otherwise it might
67  * prevent underlying thread processing. A portable user of the callback
68  * should not make calls to network operations due to stack size limitations.
69  * The callback should not perform expensive operations such as socket recv/send
70  * calls or blocking operations.
71  *
72  * @param result Negative error code on failure or
73  * value that represents the number of DNS records
74  * @param address On success, destination for the host SocketAddress.
75  */
77 
78  /** Translate a hostname to an IP address (asynchronous)
79  *
80  * The hostname may be either a domain name or an IP address. If the
81  * hostname is an IP address, no network transactions will be performed.
82  *
83  * If no stack-specific DNS resolution is provided, the hostname
84  * will be resolved using a UDP socket on the stack.
85  *
86  * The call is non-blocking. The result of the DNS operation is returned by the callback.
87  * If this function returns failure, the callback will not be called. If it is successful,
88  * (the IP address was found from the DNS cache), the callback will be called
89  * before the function returns.
90  *
91  * @param host Hostname to resolve.
92  * @param callback Callback that is called to return the result.
93  * @param version IP version of address to resolve. NSAPI_UNSPEC indicates that the
94  * version is chosen by the stack (defaults to NSAPI_UNSPEC).
95  * @param interface_name Network interface name
96  * @return NSAPI_ERROR_OK on immediate success,
97  * negative error code on immediate failure or
98  * a positive unique ID that represents the hostname translation operation
99  * and can be passed to cancel.
100  */
101  virtual nsapi_value_or_error_t gethostbyname_async(const char *host, hostbyname_cb_t callback, nsapi_version_t version = NSAPI_UNSPEC,
102  const char *interface_name = NULL) = 0;
103 
104  /** Translate a hostname to the multiple IP addresses (asynchronous)
105  *
106  * The hostname may be either a domain name or an IP address. If the
107  * hostname is an IP address, no network transactions will be performed.
108  *
109  * If no stack-specific DNS resolution is provided, the hostname
110  * will be resolved using a UDP socket on the stack.
111  *
112  * The call is non-blocking. Result of the DNS operation is returned by the callback.
113  * If this function returns failure, callback will not be called. In case that
114  * IP addresses are found from DNS cache, callback will be called before function returns.
115  *
116  * @param hostname Hostname to resolve.
117  * @param hints Pointer to a SocketAddress with query parameters.
118  * @param callback Callback that is called to return the result.
119  * @param interface_name Network interface name
120  * @return NSAPI_ERROR_OK on immediate success,
121  * negative error code on immediate failure or
122  * a positive unique ID that represents the hostname translation operation
123  * and can be passed to cancel.
124  */
125  virtual nsapi_value_or_error_t getaddrinfo_async(const char *hostname, SocketAddress *hints, hostbyname_cb_t callback, const char *interface_name = NULL) = 0;
126 
127  /** Cancel asynchronous hostname translation.
128  *
129  * When translation is canceled, callback is not called.
130  *
131  * @param id Unique ID of the hostname translation operation returned by gethostbyname_async.
132  * @return NSAPI_ERROR_OK on success, negative error code on failure.
133  */
134  virtual nsapi_error_t gethostbyname_async_cancel(int id) = 0;
135 
136  /** Add a domain name server to list of servers to query.
137  *
138  * @param address DNS server host address.
139  * @param interface_name Network interface name
140  * @return NSAPI_ERROR_OK on success, negative error code on failure.
141  */
142  virtual nsapi_error_t add_dns_server(const SocketAddress &address, const char *interface_name = NULL) = 0;
143 
144 protected:
145  ~DNS() = default;
146 };
147 
148 #endif
149 
150 /** @} */
Base class for DNS provider.
Definition: DNS.h:25
virtual nsapi_error_t gethostbyname_async_cancel(int id)=0
Cancel asynchronous hostname translation.
virtual nsapi_error_t gethostbyname(const char *host, SocketAddress *address, nsapi_version_t version=NSAPI_UNSPEC, const char *interface_name=NULL)=0
Translate a hostname to an IP address with specific version using network interface name...
mbed::Callback< void(nsapi_value_or_error_t result, SocketAddress *address)> hostbyname_cb_t
Hostname translation callback for gethostbyname_async.
Definition: DNS.h:76
virtual nsapi_value_or_error_t gethostbyname_async(const char *host, hostbyname_cb_t callback, nsapi_version_t version=NSAPI_UNSPEC, const char *interface_name=NULL)=0
Translate a hostname to an IP address (asynchronous)
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
virtual nsapi_value_or_error_t getaddrinfo(const char *hostname, SocketAddress *hints, SocketAddress **res, const char *interface_name=NULL)=0
Translate a hostname to the multiple IP addresses with specific version using network interface name...
signed int nsapi_value_or_error_t
Type used to represent either a value or error.
Definition: nsapi_types.h:113
SocketAddress class.
Definition: SocketAddress.h:36
virtual nsapi_value_or_error_t getaddrinfo_async(const char *hostname, SocketAddress *hints, hostbyname_cb_t callback, const char *interface_name=NULL)=0
Translate a hostname to the multiple IP addresses (asynchronous)
virtual nsapi_error_t add_dns_server(const SocketAddress &address, const char *interface_name=NULL)=0
Add a domain name server to list of servers to query.
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.