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  /** Hostname translation callback for gethostbyname_async.
46  *
47  * The callback is called after DNS resolution completes, or a failure occurs.
48  *
49  * Callback should not take more than 10ms to execute, otherwise it might
50  * prevent underlying thread processing. A portable user of the callback
51  * should not make calls to network operations due to stack size limitations.
52  * The callback should not perform expensive operations such as socket recv/send
53  * calls or blocking operations.
54  *
55  * @param result NSAPI_ERROR_OK on success, negative error code on failure.
56  * @param address On success, destination for the host SocketAddress.
57  */
59 
60  /** Translate a hostname to an IP address (asynchronous)
61  *
62  * The hostname may be either a domain name or an IP address. If the
63  * hostname is an IP address, no network transactions will be performed.
64  *
65  * If no stack-specific DNS resolution is provided, the hostname
66  * will be resolved using a UDP socket on the stack.
67  *
68  * The call is non-blocking. The result of the DNS operation is returned by the callback.
69  * If this function returns failure, the callback will not be called. If it is successful,
70  * (the IP address was found from the DNS cache), the callback will be called
71  * before the function returns.
72  *
73  * @param host Hostname to resolve.
74  * @param callback Callback that is called to return the result.
75  * @param version IP version of address to resolve. NSAPI_UNSPEC indicates that the
76  * version is chosen by the stack (defaults to NSAPI_UNSPEC).
77  * @param interface_name Network interface name
78  * @return NSAPI_ERROR_OK on immediate success,
79  * negative error code on immediate failure or
80  * a positive unique ID that represents the hostname translation operation
81  * and can be passed to cancel.
82  */
83  virtual nsapi_value_or_error_t gethostbyname_async(const char *host, hostbyname_cb_t callback, nsapi_version_t version = NSAPI_UNSPEC,
84  const char *interface_name = NULL) = 0;
85 
86  /** Cancel asynchronous hostname translation.
87  *
88  * When translation is canceled, callback is not called.
89  *
90  * @param id Unique ID of the hostname translation operation returned by gethostbyname_async.
91  * @return NSAPI_ERROR_OK on success, negative error code on failure.
92  */
93  virtual nsapi_error_t gethostbyname_async_cancel(int id) = 0;
94 
95  /** Add a domain name server to list of servers to query.
96  *
97  * @param address DNS server host address.
98  * @param interface_name Network interface name
99  * @return NSAPI_ERROR_OK on success, negative error code on failure.
100  */
101  virtual nsapi_error_t add_dns_server(const SocketAddress &address, const char *interface_name = NULL) = 0;
102 };
103 
104 #endif
105 
106 /** @} */
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...
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()> callback(R(*func)()=0)
Create a callback class with type inferred from the arguments.
Definition: Callback.h:3848
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:35
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< void(nsapi_error_t result, SocketAddress *address)> hostbyname_cb_t
Hostname translation callback for gethostbyname_async.
Definition: DNS.h:58
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.