c-ares 1.1.2

A Rust wrapper for the c-ares library, for asynchronous DNS requests.

Crate c_ares [] [src]

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 with get_sock().

  • 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 process_fd() 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 process_fd() 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.

Modules

flags

Flags that may be passed when initializing a Channel.

ni_flags

Flags that may be provided on a call to get_name_info()

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.

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.

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.