[][src]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.