# `Channel` - Ares Channel

class `pycares.``Channel`([flags, timeout, tries, ndots, tcp_port, udp_port, servers, domains, lookups, sock_state_cb, socket_send_buffer_size, socket_receive_buffer_size, rotate, local_ip, local_dev, resolvconf_path])

  Parameters:

  - flags (int) – Flags controlling the behavior of the resolver. See `constants` for available values.
  - timeout (float) – The number of seconds each name server is given to respond to a query on the first try. The default is five seconds.
  - tries (int) – The number of tries the resolver will try contacting each name server before giving up. The default is four tries.
  - ndots (int) – The number of dots which must be present in a domain name for it to be queried for “as is” prior to querying for it with the default domain extensions appended. The default value is 1 unless set otherwise by resolv.conf or the RES_OPTIONS environment variable.
  - tcp_port (int) – The (TCP) port to use for queries. The default is 53.
  - udp_port (int) – The (UDP) port to use for queries. The default is 53.
  - servers (list) – List of nameservers to be used to do the lookups.
  - domains (list) – The domains to search, instead of the domains specified in resolv.conf or the domain derived from the kernel hostname variable.
  - lookup (str) – The lookups to perform for host queries. lookups should be set to a string of the characters “b” or “f”, where “b” indicates a DNS lookup and “f” indicates a lookup in the hosts file.
  - sock_state_cb (callable) – A callback function to be invoked when a socket changes state. Callback signature: `sock_state_cb(self, fd, readable, writable)`
  - socket_send_buffer_size (int) – Size for the created socket’s send buffer.
  - socket_receive_buffer_size (int) – Size for the created socket’s receive buffer.
  - rotate (bool) – If set to True, the nameservers are rotated when doing queries.
  - local_ip (str) – Sets the local IP address for DNS operations.
  - local_dev (str) – Sets the local network adapter to use for DNS operations. Linux only.
  - resolvconf_path (str) – Path to resolv.conf, defaults to /etc/resolv.conf. Unix only.

  The c-ares `Channel` provides asynchronous DNS operations.

  `gethostbyname`(name, family, callback)

    Parameters:

    - name (string) – Name to query.
    - family (int) – Socket family.
    - callback (callable) – Callback to be called with the result of the query.

    Retrieves host information corresponding to a host name from a host database.

    Callback signature: `callback(result, errorno)`

  `gethostbyaddr`(name, callback)

    Parameters:

    - name (string) – Name to query.
    - callback (callable) – Callback to be called with the result of the query.

    Retrieves the host information corresponding to a network address.

    Callback signature: `callback(result, errorno)`

  `getnameinfo`(name, port, flags, callback)

    Parameters:

    - name (string) – Name to query.
    - port (int) – Port of the service to query.
    - flags (int) – Query flags, see the NI flags section.
    - callback (callable) – Callback to be called with the result of the query.

    Provides protocol-independent name resolution from an address to a host name and from a port number to the service name.

    Callback signature: `callback(result, errorno)`

  `query`(name, query_type, callback)

    Parameters:

    - name (string) – Name to query.
    - query_type (int) – Type of query to perform.
    - callback (callable) – Callback to be called with the result of the query.

    Do a DNS query of the specified type. Available types:
      - `QUERY_TYPE_A`
      - `QUERY_TYPE_AAAA`
      - `QUERY_TYPE_ANY`
      - `QUERY_TYPE_CNAME`
      - `QUERY_TYPE_MX`
      - `QUERY_TYPE_NAPTR`
      - `QUERY_TYPE_NS`
      - `QUERY_TYPE_PTR`
      - `QUERY_TYPE_SOA`
      - `QUERY_TYPE_SRV`
      - `QUERY_TYPE_TXT`

    Callback signature: `callback(result, errorno)`. The result type varies depending on the query type:

    > - A: (list of) `ares_query_a_result`, fields:
    >   - host
    >   - ttl
    > - AAAA: (list of) `ares_query_aaaa_result`, fields:
    >   - host
    >   - ttl
    > - CNAME: `ares_query_cname_result`, fields:
    >   - cname
    >   - ttl
    > - MX: (list of) `ares_query_mx_result`, fields:
    >   - host
    >   - priority
    >   - ttl
    > - NAPTR: (list of) `ares_query_naptr_result`, fields:
    >   - order
    >   - preference
    >   - flags
    >   - service
    >   - regex
    >   - replacement
    >   - ttl
    > - NS: (list of) `ares_query_ns_result`, fields:
    >   - host
    >   - ttl
    > - PTR: (list of) `ares_query_ptr_result`, fields:
    >   - name
    >   - ttl
    > - SOA: `ares_query_soa_result`, fields:
    >   - nsmane
    >   - hostmaster
    >   - serial
    >   - refresh
    >   - retry
    >   - expires
    >   - minttl
    >   - ttl
    > - SRV: (list of) `ares_query_srv_result`, fields:
    >   - host
    >   - port
    >   - priority
    >   - weight
    >   - ttl
    > - TXT: (list of) `ares_query_txt_result`, fields:
    >   - text
    >   - ttl
    > - ANY: a list of any of the above.

    Note

    TTL is not implemented for CNAME and NS), so it’s set to -1.

  `search`(name, query_type, callback)

    Parameters:

    - name (string) – Name to query.
    - query_type (int) – Type of query to perform.
    - callback (callable) – Callback to be called with the result of the query.

    Tis function does the same as `query()` but it will honor the `domain` and `search` directives in `resolv.conf`.

  `cancel`()

    Cancel any pending query on this channel. All pending callbacks will be called with ARES_ECANCELLED errorno.

  `process_fd`(read_fd, write_fd)

    Parameters:

    - read_fd (int) – File descriptor ready to read from.
    - write_fd (int) – File descriptor ready to write to.

    Process the given file descriptors for read and/or write events.

  `getsock`()

    Return a tuple containing 2 lists with the file descriptors ready to read and write.

  `timeout`([max_timeout])

    Parameters: | max_timeout (float) – Maximum timeout.

    Determines the maximum time for which the caller should wait before invoking `process_fd` to process timeouts. If the `max_timeout` parameter is specified, it is stored on the channel and the appropriate value is then returned.

  `set_local_ip`(local_ip)

    Parameters: | local_ip (str) – IP address.

    Set the local IPv4 or IPv6 address from which the queries will be sent.

  `set_local_dev`(local_dev)

    Parameters: | local_dev (str) – Network device name.

    Set the local ethernet device from which the queries will be sent.

  `servers`

    List of nameservers to use for DNS queries.