Crate c_ares

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 complication of using the underlying library:

• 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.

If that sounds a bit too much like hard work, you should probably prefer the c-ares-resolver crate, which takes care of all that stuff for you and presents a much simpler API.

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.
CNameResults	The result of a successful CNAME lookup.
Channel	A channel for name service lookups.
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 CStrs.
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.
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.
TXTResult	The contents of a single TXT record.
TXTResults	The result of a successful TXT lookup.
TXTResultsIter	Iterator of TXTResults.

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

version

Get the version number of the underlying c-ares library.

Type Definitions

Result	The type used by this library for methods that might fail.
Socket	The platform-specific file descriptor / socket type. That is, either a RawFd or a RawSocket.