c_ares/
lib.rs

1//! A safe wrapper for the [`c-ares`](https://c-ares.org) library.
2//!
3//! This crate is a fairly faithful wrapper of `c-ares`; which is to say that it preserves some of
4//! the complexity of using the underlying library.  If you just want to make a DNS query, you
5//! should probably prefer the [`c-ares-resolver`](https://crates.io/crates/c-ares-resolver) crate,
6//! which does the hard work for you.
7//!
8//! Direct usage of this crate requires you to pay attention to `c-ares` as it tells you which
9//! file descriptors it cares about, and to poll for activity on those file descriptors.
10//! This likely requires you to have an event loop or similar with which to integrate.
11//!
12//! Still here?  Usage of this crate is as follows:
13//!
14//! - Create a `Channel`.
15//!
16//! - Make queries on the `Channel`.  Queries all take callbacks, which will be called when the
17//!   query completes.
18//!
19//! - Have `c-ares` tell you what file descriptors to listen on for read and / or write events.
20//!   You can do this either by providing a callback, which is called whenever the set of
21//!   interesting file descriptors changes, or by querying the `Channel` directly either with
22//!   `get_sock()` or with `fds()`.
23//!
24//! - Do as `c-ares` asks.  That is, listen for the events that it requests, on the file
25//!   descriptors that it cares about.
26//!
27//! - When a file descriptor becomes readable or writable, call either `process_fd()` or
28//!   `process()` on the `Channel` to tell `c-ares` what has happened.
29//!
30//! - If you have queries pending and don't see events happening, you still need to call either
31//!   `process_fd()` or `process()` at some point anyway - to give `c-ares` an opportunity to
32//!   process any requests that have timed out.
33//!
34//! Complete examples showing how to use the library can be found
35//! [here](https://github.com/dimbleby/rust-c-ares/tree/main/examples).
36#![deny(missing_docs)]
37
38#[macro_use]
39mod macros;
40mod a;
41mod aaaa;
42#[cfg(cares1_17)]
43mod caa;
44mod channel;
45mod cname;
46mod error;
47#[cfg(cares1_34)]
48mod events;
49mod flags;
50mod host;
51mod hostent;
52mod mx;
53mod nameinfo;
54mod naptr;
55mod ni_flags;
56mod ns;
57mod panic;
58mod ptr;
59mod query;
60mod server_state_flags;
61mod soa;
62mod srv;
63mod string;
64mod txt;
65mod types;
66mod uri;
67mod utils;
68
69#[cfg(test)]
70mod tests;
71
72// Re-export public interfaces.
73pub use crate::a::{AResult, AResults, AResultsIter};
74pub use crate::aaaa::{AAAAResult, AAAAResults, AAAAResultsIter};
75#[cfg(cares1_17)]
76pub use crate::caa::{CAAResult, CAAResults, CAAResultsIter};
77#[cfg(cares1_29)]
78pub use crate::channel::ServerFailoverOptions;
79pub use crate::channel::{Channel, GetSock, GetSockIter, Options};
80pub use crate::cname::CNameResults;
81pub use crate::error::{Error, Result};
82#[cfg(cares1_34)]
83pub use crate::events::{FdEventFlags, FdEvents, ProcessFlags};
84pub use crate::flags::Flags;
85pub use crate::host::HostResults;
86pub use crate::hostent::{HostAddressResultsIter, HostAliasResultsIter};
87pub use crate::mx::{MXResult, MXResults, MXResultsIter};
88pub use crate::nameinfo::NameInfoResult;
89pub use crate::naptr::{NAPTRResult, NAPTRResults, NAPTRResultsIter};
90pub use crate::ni_flags::NIFlags;
91pub use crate::ns::NSResults;
92pub use crate::ptr::PTRResults;
93#[cfg(cares1_29)]
94pub use crate::server_state_flags::ServerStateFlags;
95pub use crate::soa::SOAResult;
96pub use crate::srv::{SRVResult, SRVResults, SRVResultsIter};
97pub use crate::string::AresString;
98pub use crate::txt::{TXTResult, TXTResults, TXTResultsIter};
99pub use crate::types::{AddressFamily, Socket, SOCKET_BAD};
100pub use crate::uri::{URIResult, URIResults, URIResultsIter};
101#[cfg(cares1_23)]
102pub use crate::utils::thread_safety;
103pub use crate::utils::version;
c_ares/lib.rs

c_ares/
lib.rs
