Debian Codegraph @

src/vendor/azure-uamqp-c/deps/azure-c-shared-utility/devdoc/dns_async.md

raw
1 dns_resolver
2 =================
3
4 ## Overview
5
6 **dns_resolver** performs an asynchronous lookup of a TCP IPv4 address given a host name.
7
8 This module is intended to locate IP addresses for an Azure server, and more flexible behavior is deliberately out-of-scope at this time. IPv6 address lookup is currently out-of-scope, although support for it may be added in the future via addition of a `dns_resolver_get_ipv6` call.
9
10 The present implementation will not actually provide asynchronous behavior, which is a feature to be added in the future.
11 ## References
12
13 [dns_resolver.h](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/dns_resolver.h)
14
15 ### Exposed API
16
17
18 **SRS_dns_resolver_30_001: [** The dns_resolver shall use the constants and types defined in `dns_resolver.h`.
19 ```c
20 typedef void* DNSRESOLVER_HANDLE;
21
22 // If options are added in future, DNSRESOLVER_OPTIONS will become a struct containing the options
23 typedef void DNSRESOLVER_OPTIONS;
24 ```
25 **]**
26
27 **SRS_dns_resolver_30_002: [** The dns_resolver shall implement the methods defined in `dns_resolver.h`.
28 ```c
29 DNSRESOLVER_HANDLE dns_resolver_create(const char* hostname, int port, const DNSRESOLVER_OPTIONS* options);
30 int dns_resolver_is_lookup_complete(DNSRESOLVER_HANDLE dns, bool* is_complete);
31 uint32_t dns_resolver_get_ipv4(DNSRESOLVER_HANDLE dns);
32 void dns_resolver_destroy(DNSRESOLVER_HANDLE dns);
33 ```
34 **]**
35
36
37 ### dns_resolver_create
38 `dns_resolver_create` begins a single attempt at asynchronous DNS lookup.
39 ```c
40 DNSRESOLVER_HANDLE dns_resolver_create(const char* hostname, int port, const DNSRESOLVER_OPTIONS* options);
41 ```
42
43 **SRS_dns_resolver_30_010: [** `dns_resolver_create` shall make a copy of the `hostname` parameter to allow immediate deletion by the caller. **]**
44
45 **SRS_dns_resolver_30_011: [** If the `hostname` parameter is `NULL`, `dns_resolver_create` shall log an error and return `NULL`. **]**
46
47 **SRS_dns_resolver_30_012: [** The optional `options` parameter shall be ignored. **]**
48
49 **SRS_dns_resolver_30_013: [** On success, `dns_resolver_create` shall return the created `DNSRESOLVER_HANDLE`. **]**
50
51 **SRS_dns_resolver_30_014: [** On any failure, `dns_resolver_create` shall log an error and return `NULL`. **]**
52
53
54 ### dns_resolver_is_lookup_complete
55 `dns_resolver_is_lookup_complete` tests whether `dns_resolver_create`'s single attempt at DNS lookup has been completed. To complete the lookup process, this method must be called repeatedly until it returns `true`.
56
57 ```c
58 bool dns_resolver_is_create_complete(DNSRESOLVER_HANDLE dns);
59 ```
60
61 **SRS_dns_resolver_30_020: [** If the `dns` parameter is NULL, `dns_resolver_is_create_complete` shall log an error and return `false`. **]**
62
63 **SRS_dns_resolver_30_021: [** `dns_resolver_is_create_complete` shall perform the asynchronous work of DNS lookup and log any errors. **]**
64
65 **SRS_dns_resolver_30_022: [** If the DNS lookup process has completed, `dns_resolver_is_create_complete` shall return `true`. **]**
66
67 **SRS_dns_resolver_30_023: [** If the DNS lookup process is not yet complete, `dns_resolver_is_create_complete` shall return `false`. **]**
68
69 **SRS_dns_resolver_30_024: [** If `dns_resolver_is_create_complete` has previously returned `true`, `dns_resolver_is_create_complete` shall do nothing and return `true`. **]**
70
71
72 ### dns_resolver_get_ipv4
73 `dns_resolver_get_ipv4` retrieves the IP address address after `dns_resolver_is_create_complete` indicates completion. A return value of 0 indicates failure.
74
75 ```c
76 uint32_t dns_resolver_get_ipv4(DNSRESOLVER_HANDLE dns);
77 ```
78
79 **SRS_dns_resolver_30_030: [** If the `dns` parameter is NULL, `dns_resolver_get_ipv4` shall log an error and return 0. **]**
80
81 **SRS_dns_resolver_30_031: [** If `dns_resolver_is_create_complete` has not yet returned `true`, `dns_resolver_get_ipv4` shall log an error and return 0. **]**
82
83 **SRS_dns_resolver_30_032: [** If `dns_resolver_is_create_complete` has returned `true` and the lookup process has succeeded, `dns_resolver_get_ipv4` shall return the discovered IPv4 address. **]**
84
85 **SRS_dns_resolver_30_033: [** If `dns_resolver_is_create_complete` has returned `true` and the lookup process has failed, `dns_resolver_get_ipv4` shall return 0. **]**
86
87
88 ### dns_resolver_destroy
89 `dns_resolver_destroy` releases any resources acquired during the DNS lookup process.
90
91 ```c
92 void dns_resolver_destroy(DNSRESOLVER_HANDLE dns);
93 ```
94
95 **SRS_dns_resolver_30_050: [** If the `dns` parameter is `NULL`, `dns_resolver_destroy` shall log an error and do nothing. **]**
96
97 **SRS_dns_resolver_30_051: [** `dns_resolver_destroy` shall delete all acquired resources and delete the `DNSRESOLVER_HANDLE`. **]**