Crate c_ares 

A safe wrapper for the c-ares library.

If your c-ares is sufficiently recent (version 1.26+) and built with thread safety, it should be quite ergonomic to use this crate directly. See the event_thread example.

Otherwise, you will need to manage your own event loop. You may prefer the c-ares-resolver crate, which does that for you. That crate also offers a variety of resolvers: using callbacks, using futures, or blocking.

Direct usage without the event thread 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:

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

Structs

AAAAResult

The contents of a single AAAA record.

AAAAResults

The result of a successful AAAA lookup.

AAAAResultsIter

Iterator of AAAAResults.

ARecord

Typed view of an A record.

AResult

The contents of a single A record.

AResults

The result of a successful A lookup.

AResultsIter

Iterator of AResults.

AaaaRecord

Typed view of an AAAA record.

AddrInfoCName

A single CNAME record from an AddrInfoResults.

AddrInfoCNameIter

Iterator over the CNAME chain in an AddrInfoResults.

AddrInfoFlags

Flags that may be passed in AddrInfoHints.

AddrInfoHints

Hints for an ares_getaddrinfo() call, controlling the returned results.

AddrInfoNode

A single address node from an AddrInfoResults.

AddrInfoNodeIter

Iterator over the address nodes in an AddrInfoResults.

AddrInfoResults

The result of a successful get_addrinfo() call.

AresBuf

A smart pointer wrapping a byte buffer as allocated by c-ares.

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.

CaaRecord

Typed view of a CAA record.

Channel

A channel for name service lookups.

CnameRecord

Typed view of a CNAME record.

DnsFlags

DNS message header flags.

DnsParseFlags

Flags controlling DNS message parsing behaviour.

DnsRecord

An owned DNS record (message), wrapping ares_dns_record_t.

DnsRr

A view of a DNS resource record, wrapping ares_dns_rr_t.

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.

HinfoRecord

Typed view of an HINFO record.

HostAddressResultsIter

Iterator of IpAddrs.

HostAliasResultsIter

Iterator of &'a strs.

HostResults

The result of a host lookup, wrapping a C hostent.

HttpsRecord

Typed view of an HTTPS record.

MXResult

The contents of a single MX record.

MXResults

The result of a successful MX lookup.

MXResultsIter

Iterator of MXResults.

MxRecord

Typed view of an MX record.

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.

NaptrRecord

Typed view of a NAPTR record.

NsRecord

Typed view of an NS record.

OptParseError

Error returned when an option value cannot be parsed.

OptRecord

Typed view of an OPT (EDNS0) record.

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

PtrRecord

Typed view of a PTR record.

RawRrRecord

Typed view of a RAW_RR record.

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.

SigRecord

Typed view of a SIG record.

SoaRecord

Typed view of an SOA record.

Sockets

Information about the set of sockets that c-ares is interested in, as returned by sockets().

SocketsIter

Iterator for sockets of interest to c-ares.

SrvRecord

Typed view of an SRV record.

SvcbRecord

Typed view of an SVCB record.

TXTResult

The contents of a single TXT record.

TXTResults

The result of a successful TXT lookup.

TXTResultsIter

Iterator of TXTResults.

TlsaRecord

Typed view of a TLSA record.

TxtRecord

Typed view of a TXT record.

URIResult

The contents of a single URI record.

URIResults

The result of a successful URI lookup.

URIResultsIter

Iterator of URIResults.

UriRecord

Typed view of a URI record.

Enums

AddressFamily

Address families.

DnsCls

DNS classes for requests and responses.

DnsDataType

Data types for DNS resource record fields.

DnsOpcode

DNS header opcodes.

DnsOptDataType

Data type for option records for keys like OPT_OPTIONS and HTTPS_PARAMS.

DnsRcode

DNS response codes.

DnsRecordType

DNS record types handled by c-ares.

DnsRrKey

DNS resource record field keys.

DnsSection

DNS message sections.

Error

Error codes that the library might return.

EventSys

Event system to use for the c-ares built-in event thread.

OptValue

A parsed DNS option value.

TypedRr

Match-friendly enumeration of every typed record view.

Constants

SOCKET_BAD

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

Functions

expand_name

Expand a DNS-encoded domain name from a DNS message.

expand_string

Expand a single DNS-encoded string from a DNS message.

parse_opt_value

Parse a raw option value according to its datatype.

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.