Struct BlockingResolver 

pub struct BlockingResolver { /* private fields */ }

A blocking DNS resolver.

The c-ares library returns results via callbacks, and some of those callbacks receive borrowed data. To return owned results, this resolver must clone or copy where the callback-based Resolver need not.

Therefore: if you are trying very hard to avoid unnecessary allocations - prefer the Resolver.

Implementations

impl BlockingResolver

pub fn new() -> Result<Self, Error>

Create a new BlockingResolver, using default Options.

Examples

let resolver = c_ares_resolver::BlockingResolver::new().unwrap();
match resolver.query_a("example.com") {
    Ok(results) => {
        for result in &results {
            println!("{}: TTL {}", result.ipv4(), result.ttl());
        }
    }
    Err(e) => eprintln!("Query failed: {e}"),
}

pub fn with_options(options: Options) -> Result<Self, Error>

Create a new BlockingResolver, with the given Options.

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

Reinitialize a channel from system configuration.

pub fn set_servers<I, S>(&self, servers: I) -> Result<&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.

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(&self, ipv4: Ipv4Addr) -> &Self

Set the local IPv4 address from which to make queries.

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

Set the local IPv6 address from which to make queries.

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

Set the local device from which to make queries.

pub fn set_sortlist<I, S>(&self, sortlist: I) -> Result<&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>(&self, callback: F) -> &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 query_a(&self, name: &str) -> Result<AResults>

Look up the A records associated with name.

pub fn search_a(&self, name: &str) -> Result<AResults>

Search for the A records associated with name.

pub fn query_aaaa(&self, name: &str) -> Result<AAAAResults>

Look up the AAAA records associated with name.

pub fn search_aaaa(&self, name: &str) -> Result<AAAAResults>

Search for the AAAA records associated with name.

pub fn query_caa(&self, name: &str) -> Result<CAAResults>

Look up the CAA records associated with name.

pub fn search_caa(&self, name: &str) -> Result<CAAResults>

Search for the CAA records associated with name.

pub fn query_cname(&self, name: &str) -> Result<CNameResults>

Look up the CNAME records associated with name.

pub fn search_cname(&self, name: &str) -> Result<CNameResults>

Search for the CNAME records associated with name.

pub fn query_mx(&self, name: &str) -> Result<MXResults>

Look up the MX records associated with name.

pub fn search_mx(&self, name: &str) -> Result<MXResults>

Search for the MX records associated with name.

pub fn query_naptr(&self, name: &str) -> Result<NAPTRResults>

Look up the NAPTR records associated with name.

pub fn search_naptr(&self, name: &str) -> Result<NAPTRResults>

Search for the NAPTR records associated with name.

pub fn query_ns(&self, name: &str) -> Result<NSResults>

Look up the NS records associated with name.

pub fn search_ns(&self, name: &str) -> Result<NSResults>

Search for the NS records associated with name.

pub fn query_ptr(&self, name: &str) -> Result<PTRResults>

Look up the PTR records associated with name.

pub fn search_ptr(&self, name: &str) -> Result<PTRResults>

Search for the PTR records associated with name.

pub fn query_soa(&self, name: &str) -> Result<SOAResult>

Look up the SOA records associated with name.

pub fn search_soa(&self, name: &str) -> Result<SOAResult>

Search for the SOA records associated with name.

pub fn query_srv(&self, name: &str) -> Result<SRVResults>

Look up the SRV records associated with name.

pub fn search_srv(&self, name: &str) -> Result<SRVResults>

Search for the SRV records associated with name.

pub fn query_txt(&self, name: &str) -> Result<TXTResults>

Look up the TXT records associated with name.

pub fn search_txt(&self, name: &str) -> Result<TXTResults>

Search for the TXT records associated with name.

pub fn query_uri(&self, name: &str) -> Result<URIResults>

Look up the URI records associated with name.

pub fn search_uri(&self, name: &str) -> Result<URIResults>

Search for the URI records associated with name.

pub fn get_host_by_address(&self, address: &IpAddr) -> Result<HostResults>

Perform a host query by address.

pub fn get_host_by_name( &self, name: &str, family: AddressFamily, ) -> Result<HostResults>

Perform a host query by name.

pub fn get_name_info( &self, address: &SocketAddr, flags: NIFlags, ) -> Result<NameInfoResult>

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

pub fn get_addrinfo( &self, name: &str, service: Option<&str>, hints: &AddrInfoHints, ) -> Result<AddrInfoResults>

Initiate a host query by name and service.

pub fn query( &self, name: &str, dns_class: u16, query_type: u16, ) -> Result<Vec<u8>>

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.

This method is provided so that users can query DNS types for which c-ares does not provide a parser; or in case a third-party parser is preferred. Usually, if a suitable query_xxx() is available, that should be used.

pub fn search( &self, name: &str, dns_class: u16, query_type: u16, ) -> Result<Vec<u8>>

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.

This method is provided so that users can search DNS types for which c-ares does not provide a parser; or in case a third-party parser is preferred. Usually, if a suitable search_xxx() is available, that should be used.

pub fn send_dnsrec(&self, dnsrec: &DnsRecord) -> Result<DnsRecord>

Send a DNS query using a pre-built c_ares::DnsRecord.

Examples

use c_ares::*;

let resolver = c_ares_resolver::BlockingResolver::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();
let response = resolver.send_dnsrec(&query).unwrap();
for rr in response.rrs(DnsSection::Answer) {
    if let Some(addr) = rr.get_addr(DnsRrKey::A_ADDR) {
        println!("address: {addr}");
    }
}

pub fn query_dnsrec( &self, name: &str, dns_class: DnsCls, query_type: DnsRecordType, ) -> Result<DnsRecord>

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

Examples

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

let resolver = c_ares_resolver::BlockingResolver::new().unwrap();
let record = resolver
    .query_dnsrec("example.com", DnsCls::IN, DnsRecordType::A)
    .unwrap();
for rr in record.rrs(DnsSection::Answer) {
    if let Some(addr) = rr.get_addr(DnsRrKey::A_ADDR) {
        println!("address: {addr}");
    }
}

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

Initiate a series of DNS queries using a pre-built c_ares::DnsRecord, receiving a parsed c_ares::DnsRecord.

Examples

use c_ares::*;

let resolver = c_ares_resolver::BlockingResolver::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();
let response = resolver.search_dnsrec(&query).unwrap();
for rr in response.rrs(DnsSection::Answer) {
    if let Some(addr) = rr.get_addr(DnsRrKey::A_ADDR) {
        println!("address: {addr}");
    }
}

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.

Trait Implementations

impl Debug for BlockingResolver

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

Formats the value using the given formatter.