Struct Channel

pub struct Channel { /* private fields */ }

A channel for name service lookups.

Implementations

impl Channel

pub fn new() -> Result<Self>

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

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

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

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: Socket, write_fd: 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 SOCKET_BAD 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 get_sock(&self) -> GetSock

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

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(&mut self, servers: &[&str]) -> Result<&mut Self>

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 get_servers(&self) -> AresString

Retrieves the list of servers in comma delimited format.

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) -> &mut Self

Set the local device from which to make queries.

pub fn set_sortlist(&mut self, sortlist: &[&str]) -> Result<&mut Self>

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: FnMut(&str, bool, ServerStateFlags) + Send + '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: FnMut() + Send + '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 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 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.

Trait Implementations

impl Drop for Channel

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Channel

impl Sync for Channel