Struct Channel 

pub struct Channel { /* private fields */ }

A channel for name service lookups.

Implementations

impl Channel

pub fn as_raw(&self) -> ares_channel

Returns the raw ares_channel pointer.

Safety

The returned pointer is only valid for the lifetime of this Channel. Callers must ensure that any use of the pointer is compatible with concurrent access (e.g. only call thread-safe c-ares functions).

pub fn new() -> Result<Self>

Create a new channel for name service lookups, with default Options.

Examples

let channel = c_ares::Channel::new().unwrap();

pub fn with_options(options: Options) -> Result<Channel>

Create a new channel for name service lookups, with the given Options.

Examples

let mut options = c_ares::Options::new();
options.set_flags(c_ares::Flags::STAYOPEN)
       .set_tries(2);
let channel = c_ares::Channel::with_options(options).unwrap();

pub fn reinit(&mut self) -> Result<&mut Self>

Reinitialize a channel from system configuration.

pub fn try_clone(&self) -> Result<Channel>

Duplicate a channel.

pub fn process_fd(&mut self, read_fd: Option<Socket>, write_fd: Option<Socket>)

Handle input, output, and timeout events associated with the specified file descriptors (sockets).

Providing a value for read_fd indicates that the identified socket is readable; likewise providing a value for write_fd indicates that the identified socket is writable. Use None for “no action”.

pub fn process(&mut self, read_fds: &mut fd_set, write_fds: &mut fd_set)

Handle input and output events associated with the specified file descriptors (sockets). Also handles timeouts associated with the Channel.

pub fn process_fds( &mut self, events: &[FdEvents], flags: ProcessFlags, ) -> Result<()>

Process events on multiple file descriptors based on the event mask associated with each file descriptor. Recommended over calling process_fd() multiple times since it would trigger additional logic such as timeout processing on each call.

pub fn sockets(&self) -> Sockets

Retrieve the set of socket descriptors which the calling application should wait on for reading and / or writing.

Examples

let channel = c_ares::Channel::new().unwrap();
for (socket, readable, writable) in &channel.sockets() {
    println!("socket {socket}: read={readable}, write={writable}");
}

pub fn fds(&self, read_fds: &mut fd_set, write_fds: &mut fd_set) -> u32

Retrieve the set of socket descriptors which the calling application should wait on for reading and / or writing.

pub fn set_servers<I, S>(&mut self, servers: I) -> Result<&mut Self>

where I: IntoIterator<Item = S>, S: AsRef<str>,

Set the list of servers to contact, instead of the servers specified in resolv.conf or the local named.

String format is host[:port]. IPv6 addresses with ports require square brackets eg [2001:4860:4860::8888]:53.

Examples

let mut channel = c_ares::Channel::new().unwrap();
channel.set_servers(&["8.8.8.8", "8.8.4.4:53"]).unwrap();

pub fn servers(&self) -> Vec<String>

Retrieves the list of configured servers.

Each entry is in host[:port] format, matching what set_servers accepts.

pub fn set_local_ipv4(&mut self, ipv4: Ipv4Addr) -> &mut Self

Set the local IPv4 address from which to make queries.

pub fn set_local_ipv6(&mut self, ipv6: Ipv6Addr) -> &mut Self

Set the local IPv6 address from which to make queries.

pub fn set_local_device(&mut self, device: &str) -> Result<&mut Self>

Set the local device from which to make queries.

pub fn set_sortlist<I, S>(&mut self, sortlist: I) -> Result<&mut Self>

where I: IntoIterator<Item = S>, S: AsRef<str>,

Initializes an address sortlist configuration, so that addresses returned by get_host_by_name() are sorted according to the sortlist.

Each element of the sortlist holds an IP-address/netmask pair. The netmask is optional but follows the address after a slash if present. For example: “130.155.160.0/255.255.240.0”, or “130.155.0.0”.

pub fn set_server_state_callback<F>(&mut self, callback: F) -> &mut Self

where F: Fn(&str, bool, ServerStateFlags) + Send + Sync + 'static,

Set a callback function to be invoked whenever a query on the channel completes.

callback(server, success, flags) will be called when a query completes.

• server indicates the DNS server that was used for the query.
• success indicates whether the query succeeded or not.
• flags is a bitmask of flags describing various aspects of the query.

pub fn set_pending_write_callback<F>(&mut self, callback: F) -> &mut Self

where F: Fn() + Send + Sync + 'static,

Set a callback function to be invoked when there is potential pending data which needs to be written.

pub fn query_a<F>(&mut self, name: &str, handler: F)

where F: FnOnce(Result<AResults>) + Send + 'static,

Initiate a single-question DNS query for the A records associated with name.

On completion, handler is called with the result.

pub fn search_a<F>(&mut self, name: &str, handler: F)

where F: FnOnce(Result<AResults>) + Send + 'static,

Initiate a series of single-question DNS queries for the A records associated with name.

On completion, handler is called with the result.

pub fn query_aaaa<F>(&mut self, name: &str, handler: F)

where F: FnOnce(Result<AAAAResults>) + Send + 'static,

Initiate a single-question DNS query for the AAAA records associated with name.

On completion, handler is called with the result.

pub fn search_aaaa<F>(&mut self, name: &str, handler: F)

where F: FnOnce(Result<AAAAResults>) + Send + 'static,

Initiate a series of single-question DNS queries for the AAAA records associated with name.

On completion, handler is called with the result.

pub fn query_caa<F>(&mut self, name: &str, handler: F)

where F: FnOnce(Result<CAAResults>) + Send + 'static,

Initiate a single-question DNS query for the CAA records associated with name.

On completion, handler is called with the result.

pub fn search_caa<F>(&mut self, name: &str, handler: F)

where F: FnOnce(Result<CAAResults>) + Send + 'static,

Initiate a series of single-question DNS queries for the CAA records associated with name.

On completion, handler is called with the result.

pub fn query_cname<F>(&mut self, name: &str, handler: F)

where F: FnOnce(Result<CNameResults>) + Send + 'static,

Initiate a single-question DNS query for the CNAME records associated with name.

On completion, handler is called with the result.

pub fn search_cname<F>(&mut self, name: &str, handler: F)

where F: FnOnce(Result<CNameResults>) + Send + 'static,

Initiate a series of single-question DNS queries for the CNAME records associated with name.

On completion, handler is called with the result.

pub fn query_mx<F>(&mut self, name: &str, handler: F)

where F: FnOnce(Result<MXResults>) + Send + 'static,

Initiate a single-question DNS query for the MX records associated with name.

On completion, handler is called with the result.

pub fn search_mx<F>(&mut self, name: &str, handler: F)

where F: FnOnce(Result<MXResults>) + Send + 'static,

Initiate a series of single-question DNS queries for the MX records associated with name.

On completion, handler is called with the result.

pub fn query_naptr<F>(&mut self, name: &str, handler: F)

where F: FnOnce(Result<NAPTRResults>) + Send + 'static,

Initiate a single-question DNS query for the NAPTR records associated with name.

On completion, handler is called with the result.

pub fn search_naptr<F>(&mut self, name: &str, handler: F)

where F: FnOnce(Result<NAPTRResults>) + Send + 'static,

Initiate a series of single-question DNS queries for the NAPTR records associated with name.

On completion, handler is called with the result.

pub fn query_ns<F>(&mut self, name: &str, handler: F)

where F: FnOnce(Result<NSResults>) + Send + 'static,

Initiate a single-question DNS query for the NS records associated with name.

On completion, handler is called with the result.

pub fn search_ns<F>(&mut self, name: &str, handler: F)

where F: FnOnce(Result<NSResults>) + Send + 'static,

Initiate a series of single-question DNS queries for the NS records associated with name.

On completion, handler is called with the result.

pub fn query_ptr<F>(&mut self, name: &str, handler: F)

where F: FnOnce(Result<PTRResults>) + Send + 'static,

Initiate a single-question DNS query for the PTR records associated with name.

On completion, handler is called with the result.

pub fn search_ptr<F>(&mut self, name: &str, handler: F)

where F: FnOnce(Result<PTRResults>) + Send + 'static,

Initiate a series of single-question DNS queries for the PTR records associated with name.

On completion, handler is called with the result.

pub fn query_soa<F>(&mut self, name: &str, handler: F)

where F: FnOnce(Result<SOAResult>) + Send + 'static,

Initiate a single-question DNS query for the SOA records associated with name.

On completion, handler is called with the result.

pub fn search_soa<F>(&mut self, name: &str, handler: F)

where F: FnOnce(Result<SOAResult>) + Send + 'static,

Initiate a series of single-question DNS queries for the SOA records associated with name.

On completion, handler is called with the result.

pub fn query_srv<F>(&mut self, name: &str, handler: F)

where F: FnOnce(Result<SRVResults>) + Send + 'static,

Initiate a single-question DNS query for the SRV records associated with name.

On completion, handler is called with the result.

pub fn search_srv<F>(&mut self, name: &str, handler: F)

where F: FnOnce(Result<SRVResults>) + Send + 'static,

Initiate a series of single-question DNS queries for the SRV records associated with name.

On completion, handler is called with the result.

pub fn query_txt<F>(&mut self, name: &str, handler: F)

where F: FnOnce(Result<TXTResults>) + Send + 'static,

Initiate a single-question DNS query for the TXT records associated with name.

On completion, handler is called with the result.

pub fn search_txt<F>(&mut self, name: &str, handler: F)

where F: FnOnce(Result<TXTResults>) + Send + 'static,

Initiate a series of single-question DNS queries for the TXT records associated with name.

On completion, handler is called with the result.

pub fn query_uri<F>(&mut self, name: &str, handler: F)

where F: FnOnce(Result<URIResults>) + Send + 'static,

Initiate a single-question DNS query for the URI records associated with name.

On completion, handler is called with the result.

pub fn search_uri<F>(&mut self, name: &str, handler: F)

where F: FnOnce(Result<URIResults>) + Send + 'static,

Initiate a series of single-question DNS queries for the URI records associated with name.

On completion, handler is called with the result.

pub fn get_host_by_address<F>(&mut self, address: &IpAddr, handler: F)

where F: FnOnce(Result<&HostResults>) + Send + 'static,

Perform a host query by address.

On completion, handler is called with the result.

pub fn get_host_by_name<F>( &mut self, name: &str, family: AddressFamily, handler: F, )

where F: FnOnce(Result<&HostResults>) + Send + 'static,

Perform a host query by name.

On completion, handler is called with the result.

pub fn get_name_info<F>( &mut self, address: &SocketAddr, flags: NIFlags, handler: F, )

where F: FnOnce(Result<NameInfoResult<'_>>) + Send + 'static,

Address-to-nodename translation in protocol-independent manner.

The valid values for flags are documented here.

On completion, handler is called with the result.

pub fn get_addrinfo<F>( &mut self, name: &str, service: Option<&str>, hints: &AddrInfoHints, handler: F, )

where F: FnOnce(Result<AddrInfoResults>) + Send + 'static,

Initiate a host query by name and service.

The hints parameter controls the desired address family, socket type, protocol, and behaviour flags.

On completion, handler is called with the result.

pub fn query<F>( &mut self, name: &str, dns_class: u16, query_type: u16, handler: F, )

where F: FnOnce(Result<&[u8]>) + Send + 'static,

Initiate a single-question DNS query for name. The class and type of the query are per the provided parameters, taking values as defined in arpa/nameser.h.

On completion, handler is called with the result.

This method is provided so that users can query DNS types for which c-ares does not provide a parser. This is expected to be a last resort; if a suitable query_xxx() is available, that should be preferred.

pub fn search<F>( &mut self, name: &str, dns_class: u16, query_type: u16, handler: F, )

where F: FnOnce(Result<&[u8]>) + Send + 'static,

Initiate a series of single-question DNS queries for name. The class and type of the query are per the provided parameters, taking values as defined in arpa/nameser.h.

On completion, handler is called with the result.

This method is provided so that users can search DNS types for which c-ares does not provide a parser. This is expected to be a last resort; if a suitable search_xxx() is available, that should be preferred.

pub fn send_dnsrec<F>(&mut self, dnsrec: &DnsRecord, handler: F) -> Result<u16>

where F: FnOnce(Result<&DnsRecord>) + Send + 'static,

Send a DNS query using a pre-built DnsRecord.

On completion, handler is called with a Result<DnsRecord> containing the parsed response.

Returns the query ID on success.

Examples

use c_ares::*;

let mut channel = Channel::new().unwrap();
let mut query = DnsRecord::new(0, DnsFlags::RD, DnsOpcode::Query, DnsRcode::NoError).unwrap();
query.query_add("example.com", DnsRecordType::A, DnsCls::IN).unwrap();
channel.send_dnsrec(&query, move |result| {
    let record = result.unwrap();
    for rr in record.rrs(DnsSection::Answer) {
        if let Some(addr) = rr.get_addr(DnsRrKey::A_ADDR) {
            println!("address: {addr}");
        }
    }
}).unwrap();
// ... drive the event loop ...

pub fn query_dnsrec<F>( &mut self, name: &str, dns_class: DnsCls, query_type: DnsRecordType, handler: F, ) -> Result<u16>

where F: FnOnce(Result<&DnsRecord>) + Send + 'static,

Initiate a DNS query for name with the given class and type, receiving a parsed DnsRecord in the callback.

Returns the query ID on success.

Examples

use c_ares::{Channel, DnsCls, DnsRecordType, DnsRrKey, DnsSection};

let mut channel = Channel::new().unwrap();
channel.query_dnsrec(
    "example.com",
    DnsCls::IN,
    DnsRecordType::A,
    move |result| {
        let record = result.unwrap();
        for rr in record.rrs(DnsSection::Answer) {
            if let Some(addr) = rr.get_addr(DnsRrKey::A_ADDR) {
                println!("address: {addr}");
            }
        }
    },
).unwrap();
// ... drive the event loop with channel.sockets() / channel.process_fd() ...

pub fn search_dnsrec<F>(&mut self, dnsrec: &DnsRecord, handler: F) -> Result<()>

where F: FnOnce(Result<&DnsRecord>) + Send + 'static,

Initiate a series of DNS queries using a pre-built DnsRecord, receiving a parsed DnsRecord in the callback.

Examples

use c_ares::*;

let mut channel = Channel::new().unwrap();
let mut query = DnsRecord::new(0, DnsFlags::RD, DnsOpcode::Query, DnsRcode::NoError).unwrap();
query.query_add("example.com", DnsRecordType::A, DnsCls::IN).unwrap();
channel.search_dnsrec(&query, move |result| {
    let record = result.unwrap();
    for rr in record.rrs(DnsSection::Answer) {
        if let Some(addr) = rr.get_addr(DnsRrKey::A_ADDR) {
            println!("address: {addr}");
        }
    }
}).unwrap();
// ... drive the event loop ...

pub fn cancel(&mut self)

Cancel all requests made on this Channel.

Callbacks will be invoked for each pending query, passing a result Err(Error::ECANCELLED).

pub fn process_pending_write(&mut self)

Kick c-ares to process a pending write.

pub fn timeout(&self, max_timeout: Option<Duration>) -> Option<Duration>

Return the maximum time to wait before processing timeouts.

If there are pending queries, returns the time until the next timeout fires, optionally capped at max_timeout. If there are no pending queries, returns max_timeout (which may be None).

pub fn queue_wait_empty(&self, timeout: Option<Duration>) -> Result<()>

Block until notified that there are no longer any queries in queue, or the specified timeout has expired.

Pass None to wait indefinitely.

pub fn queue_active_queries(&self) -> usize

Retrieve the total number of active queries pending answers from servers.

Some c-ares requests may spawn multiple queries, such as get_addrinfo() when using AddressFamily::UNSPEC, which will be reflected in this number.

Trait Implementations

impl Debug for Channel

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Channel

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Send for Channel

impl Sync for Channel