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

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