Crate c_ares

Expand description

A safe wrapper for the c-ares library.

This crate is a fairly faithful wrapper of c-ares; which is to say that it preserves some of the complexity of using the underlying library. If you just want to make a DNS query, you should probably prefer the c-ares-resolver crate, which does the hard work for you.

Direct usage of this crate requires you to pay attention to c-ares as it tells you which file descriptors it cares about, and to poll for activity on those file descriptors. This likely requires you to have an event loop or similar with which to integrate.

Still here? Usage of this crate is as follows:

Create a Channel.
Make queries on the Channel. Queries all take callbacks, which will be called when the query completes.
Have c-ares tell you what file descriptors to listen on for read and / or write events. You can do this either by providing a callback, which is called whenever the set of interesting file descriptors changes, or by querying the Channel directly either with get_sock() or with fds().
Do as c-ares asks. That is, listen for the events that it requests, on the file descriptors that it cares about.
When a file descriptor becomes readable or writable, call either process_fd() or process() on the Channel to tell c-ares what has happened.
If you have queries pending and don’t see events happening, you still need to call either process_fd() or process() at some point anyway - to give c-ares an opportunity to process any requests that have timed out.

Complete examples showing how to use the library can be found here.

Structs§

AAAAResult: The contents of a single AAAA record.
AAAAResults: The result of a successful AAAA lookup.
AAAAResultsIter: Iterator of AAAAResults.
AResult: The contents of a single A record.
AResults: The result of a successful A lookup.
AResultsIter: Iterator of AResults.
AresString: A smart pointer wrapping a string as allocated by c-ares.
CAAResult: The contents of a single CAA record.
CAAResults: The result of a successful CAA lookup.
CAAResultsIter: Iterator of CAAResults.
CNameResults: The result of a successful CNAME lookup.
Channel: A channel for name service lookups.
FdEventFlags: Events used by FdEvents.
FdEvents: Type holding a file descriptor and mask of events, used by crate::Channel::process_fds().
Flags: Flags that may be passed when initializing a Channel.
GetSock: Information about the set of sockets that c-ares is interested in, as returned by get_sock().
GetSockIter: Iterator for sockets of interest to c-ares.
HostAddressResultsIter: Iterator of IpAddrs.
HostAliasResultsIter: Iterator of &'a strs.
HostResults: The result of a successful host lookup.
MXResult: The contents of a single MX record.
MXResults: The result of a successful MX lookup.
MXResultsIter: Iterator of MXResults.
NAPTRResult: The contents of a single NAPTR record.
NAPTRResults: The result of a successful NAPTR lookup.
NAPTRResultsIter: Iterator of NAPTRResults.
NIFlags: Flags that may be provided on a call to get_name_info().
NSResults: The result of a successful NS lookup.
NameInfoResult: The result of a successful name-info lookup.
Options: Used to configure the behaviour of the name resolver.
PTRResults: The result of a successful PTR lookup.
ProcessFlags: Flags used by crate::Channel::process_fds().
SOAResult: The result of a successful SOA lookup.
SRVResult: The contents of a single SRV record.
SRVResults: The result of a successful SRV lookup.
SRVResultsIter: Iterator of SRVResults.
ServerFailoverOptions: Server failover options.
ServerStateFlags: Flags that may be provided on server state callbacks.
TXTResult: The contents of a single TXT record.
TXTResults: The result of a successful TXT lookup.
TXTResultsIter: Iterator of TXTResults.
URIResult: The contents of a single URI record.
URIResults: The result of a successful URI lookup.
URIResultsIter: Iterator of URIResults.

Enums§

AddressFamily: Address families.
Error: Error codes that the library might return.

Constants§

SOCKET_BAD: An invalid socket / file descriptor. Use this to represent ‘no action’ when calling process_fd() on a channel.

Functions§

thread_safety: Whether the underlying c-ares library was built with thread safety enabled or not.
version: Get the version number of the underlying c-ares library.

Type Aliases§