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 theChannel
directly either withget_sock()
or withfds()
. -
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()
orprocess()
on theChannel
to tellc-ares
what has happened. -
If you have queries pending and don't see events happening, you still need to call either
process_fd()
orprocess()
at some point anyway - to givec-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 |
AResult |
The contents of a single A record. |
AResults |
The result of a successful A lookup. |
AResultsIter |
Iterator of |
CNameResults |
The result of a successful CNAME lookup. |
Channel |
A channel for name service lookups. |
Flags |
Flags that may be passed when initializing a |
GetSock |
Information about the set of sockets that |
GetSockIter |
Iterator for sockets of interest to |
HostAddressResultsIter |
Iterator of |
HostAliasResultsIter |
Iterator of |
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 |
NAPTRResult |
The contents of a single NAPTR record. |
NAPTRResults |
The result of a successful NAPTR lookup. |
NAPTRResultsIter |
Iterator of |
NIFlags |
Flags that may be provided on a call to |
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 |
TXTResult |
The contents of a single TXT record. |
TXTResults |
The result of a successful TXT lookup. |
TXTResultsIter |
Iterator of |
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 |
Functions
version |
Get the version number of the underlying |
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
|