Expand description
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
s.AResult
s.Channel
.c-ares
is interested in, as returned by
get_sock()
.c-ares
.IpAddr
s.&'a CStr
s.MXResult
s.NAPTRResult
s.get_name_info()
.SRVResult
s.TXTResult
s.Enums
Constants
process_fd()
on a channel.Functions
c-ares
library.