Overview
The Asterisk DNS API is designed as a facade over resolver implementations. It provides a consistent view and also additional features. These additional features include a construct for doing queries in parallel and gathering the results, parsing some DNS types, and applying sorting/weight logic to some DNS types.
Threading
The API provides a guarantee that it is safe to initiate and cancel queries from any thread. It does NOT, however, provide a guarantee that the ordering of queries shall be preserved. In other words, if you execute multiple queries individually you will not necessarily receive callbacks in the order the queries were originally executed. This API only guarantees that an individual DNS result and records are safe to retrieve within the scope of the respective asynchronous callback.
dns.h
The dns.h file is the public API into the DNS core. It provides mechanisms to perform individual DNS queries and access the results. All data structures are opaque and can not be accessed directly.
Query
A query contains information about an in-process DNS query. It also contains information about the result of the query.
Result
A result contains information about a completed DNS query. It also contains the resulting DNS records (if there are any).
Record
A record is a DNS record.
Code
dns_query_set.h
The dns_query_set.h file is the public API into doing parallel queries. It provides mechanisms to group DNS queries together and receive notification when all have been completed. It mirrors the single query API in functionality.
Code
dns_naptr.h
The dns_naptr.h file is the public API into accessing NAPTR records. The DNS core will automatically parse and make this information available. It will also sort the records.
Code
dns_srv.h
The dns_srv.h file is the public API into accessing SRV records. The DNS core will automatically parse and make this information available. It will also sort the records.
Code
dns_tlsa.h
The dns_tlsa.h file is the public API into accessing TLSA records.
dns_resolver.h
The dns_resolver.h file contains the interface as defined for resolver implementations.
Code
dns_internal.h
The dns_internal.h file contains the internal data structures.
Code
Examples
Synchronous Resolution
This example blocks the calling thread until resolution has completed. Once completed result information is returned.
Asynchronous Resolution
This example does not block the calling thread when resolving. A callback is invoked upon query completion instead. The result information can then be retrieved from the query.
Parallel Queries
This example uses a query set to do two queries in an asynchronous manner. Each query is done on a different domain. Once both queries have completed the callback is invoked and each query result can be examined.
Fallback
This example does a fall back from an AAAA record lookup to an A record lookup if no results were available for the AAAA record lookup. This also uses the asynchronous function and the same callback is used for both queries.
NAPTR
This example does a NAPTR lookup followed by SRV followed by AAAA and then A. The results of the NAPTR and SRV lookups are taken into account when deciding the next step to take.
Recurring
The recurring example has the DNS core re-run the specified query according to the lowest TTL of the result records. It is up to the user to store the previous results and determine whether action should be taken or not.