| 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`. **]** |