Keil Studio Cloud
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  * SPDX-License-Identifier: Apache-2.0
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 /** @file DNS.h Domain Name Service */
19 /** @addtogroup netsocket
20  * @{ */
21 
22 #ifndef DNS_H
23 #define DNS_H
24 
25 /** Base class for DNS provider */
26 class DNS {
27 public:
28 
29  /** Translate a hostname to an IP address with specific version using network interface name.
30  *
31  * The hostname may be either a domain name or an IP address. If the
32  * hostname is an IP address, no network transactions will be performed.
33  *
34  * If no stack-specific DNS resolution is provided, the hostname
35  * will be resolve using a UDP socket on the stack.
36  *
37  * @param host Hostname to resolve.
38  * @param address Pointer to a SocketAddress to store the result.
39  * @param version IP version of address to resolve, NSAPI_UNSPEC indicates
40  * version is chosen by the stack (defaults to NSAPI_UNSPEC).
41  * @param interface_name Network interface name
42  * @return NSAPI_ERROR_OK on success, negative error code on failure.
43  */
44  virtual nsapi_error_t gethostbyname(const char *host,
45  SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC, const char *interface_name = NULL) = 0;
46 
47  /** Translate a hostname to the multiple IP addresses with specific version using network interface name.
48  *
49  * The hostname may be either a domain name or an IP address. If the
50  * hostname is an IP address, no network transactions will be performed.
51  *
52  * If no stack-specific DNS resolution is provided, the hostname
53  * will be resolve using a UDP socket on the stack.
54  *
55  * @param hostname Hostname to resolve.
56  * @param hints Pointer to a SocketAddress with query parameters.
57  * @param res Pointer to a SocketAddress array to store the result..
58  * @param interface_name Network interface name
59  * @return number of results on success, negative error code on failure.
60  */
61  virtual nsapi_value_or_error_t getaddrinfo(const char *hostname, SocketAddress *hints, SocketAddress **res, const char *interface_name = NULL) = 0;
62 
63  /** Hostname translation callback for gethostbyname_async.
64  *
65  * The callback is called after DNS resolution completes, or a failure occurs.
66  *
67  * Callback should not take more than 10ms to execute, otherwise it might
68  * prevent underlying thread processing. A portable user of the callback
69  * should not make calls to network operations due to stack size limitations.
70  * The callback should not perform expensive operations such as socket recv/send
71  * calls or blocking operations.
72  *
73  * @param result Negative error code on failure or
74  * value that represents the number of DNS records
75  * @param address On success, destination for the host SocketAddress.
76  */
77  typedef mbed::Callback<void (nsapi_value_or_error_t result, SocketAddress *address)> hostbyname_cb_t;
78 
79  /** Translate a hostname to an IP address (asynchronous)
80  *
81  * The hostname may be either a domain name or an IP address. If the
82  * hostname is an IP address, no network transactions will be performed.
83  *
84  * If no stack-specific DNS resolution is provided, the hostname
85  * will be resolved using a UDP socket on the stack.
86  *
87  * The call is non-blocking. The result of the DNS operation is returned by the callback.
88  * If this function returns failure, the callback will not be called. If it is successful,
89  * (the IP address was found from the DNS cache), the callback will be called
90  * before the function returns.
91  *
92  * @param host Hostname to resolve.
93  * @param callback Callback that is called to return the result.
94  * @param version IP version of address to resolve. NSAPI_UNSPEC indicates that the
95  * version is chosen by the stack (defaults to NSAPI_UNSPEC).
96  * @param interface_name Network interface name
97  * @return NSAPI_ERROR_OK on immediate success,
98  * negative error code on immediate failure or
99  * a positive unique ID that represents the hostname translation operation
100  * and can be passed to cancel.
101  */
102  virtual nsapi_value_or_error_t gethostbyname_async(const char *host, hostbyname_cb_t callback, nsapi_version_t version = NSAPI_UNSPEC,
103  const char *interface_name = NULL) = 0;
104 
105  /** Translate a hostname to the multiple IP addresses (asynchronous)
106  *
107  * The hostname may be either a domain name or an IP address. If the
108  * hostname is an IP address, no network transactions will be performed.
109  *
110  * If no stack-specific DNS resolution is provided, the hostname
111  * will be resolved using a UDP socket on the stack.
112  *
113  * The call is non-blocking. Result of the DNS operation is returned by the callback.
114  * If this function returns failure, callback will not be called. In case that
115  * IP addresses are found from DNS cache, callback will be called before function returns.
116  *
117  * @param hostname Hostname to resolve.
118  * @param hints Pointer to a SocketAddress with query parameters.
119  * @param callback Callback that is called to return the result.
120  * @param interface_name Network interface name
121  * @return NSAPI_ERROR_OK on immediate success,
122  * negative error code on immediate failure or
123  * a positive unique ID that represents the hostname translation operation
124  * and can be passed to cancel.
125  */
126  virtual nsapi_value_or_error_t getaddrinfo_async(const char *hostname, SocketAddress *hints, hostbyname_cb_t callback, const char *interface_name = NULL) = 0;
127 
128  /** Cancel asynchronous hostname translation.
129  *
130  * When translation is canceled, callback is not called.
131  *
132  * @param id Unique ID of the hostname translation operation returned by gethostbyname_async.
133  * @return NSAPI_ERROR_OK on success, negative error code on failure.
134  */
135  virtual nsapi_error_t gethostbyname_async_cancel(int id) = 0;
136 
137  /** Add a domain name server to list of servers to query.
138  *
139  * @param address DNS server host address.
140  * @param interface_name Network interface name
141  * @return NSAPI_ERROR_OK on success, negative error code on failure.
142  */
143  virtual nsapi_error_t add_dns_server(const SocketAddress &address, const char *interface_name = NULL) = 0;
144 
145 protected:
146  ~DNS() = default;
147 };
148 
149 #endif
150 
151 /** @} */
DNS
Base class for DNS provider.
Definition: DNS.h:26
DNS::gethostbyname_async_cancel
virtual nsapi_error_t gethostbyname_async_cancel(int id)=0
Cancel asynchronous hostname translation.
DNS::gethostbyname
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...
DNS::hostbyname_cb_t
mbed::Callback< void(nsapi_value_or_error_t result, SocketAddress *address)> hostbyname_cb_t
Hostname translation callback for gethostbyname_async.
Definition: DNS.h:77
DNS::gethostbyname_async
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)
nsapi_error_t
signed int nsapi_error_t
Type used to represent error codes.
Definition: nsapi_types.h:142
NSAPI_UNSPEC
Definition: nsapi_types.h:230
mbed::callback
Callback< R(ArgTs...)> callback(R(*func)(ArgTs...)=nullptr) noexcept
Create a callback class with type inferred from the arguments.
Definition: Callback.h:678
DNS::getaddrinfo
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...
nsapi_value_or_error_t
signed int nsapi_value_or_error_t
Type used to represent either a value or error.
Definition: nsapi_types.h:160
SocketAddress
SocketAddress class.
Definition: SocketAddress.h:37
DNS::getaddrinfo_async
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)
DNS::add_dns_server
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.
mbed::Callback
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.