aresolve

Aresolve provides asynchronous DNS host resolution.

Aresolve resolves and automatically re-resolves DNS information for requests made via the aresolve_handler’s watch_* methods. Whenever resolution information about the watched name changes, the aresolve_handler’s on_aresolve_host() function is called.

For example, an application may wish to track the IP address of a particular infrastructure hostname (e.g., a syslog receiver we’ll call “loghost”). In this example, an IP address object is created to track the current address of the loghost:

 #include <assert.h>

 #include <eos/agent.h>
 #include <eos/aresolve.h>
 #include <eos/ip.h>
 #include <eos/sdk.h>

 class Aresolver : public eos::aresolve_handler, public eos::agent_handler {
  public:
    explicit Aresolver(eos::sdk & sdk)
       : eos::aresolve_handler(sdk.get_aresolve_mgr()),
         eos::agent_handler(sdk.get_agent_mgr()) {
    }

    void on_initialized() {
       // Register our interest in the IP address of "loghost"
       watch_host("loghost", true);
    }

    virtual void on_aresolve_host(eos::aresolve_record_host const & record) {
       // Called on initial host resolution or updates in host address
       if (record.valid()) {
          // We should only ever see results for "loghost".
          assert(record.qname() == "loghost");
          // Get the IP address; we'll assume there's only one in this case.
          if (record.addr_v4().size() > 0) {  // IPv4
             address = record.addr_v4().front();
          } else if (record.addr_v6().size() > 0) {  // IPv6
             address = record.addr_v6().front();
          }
          // Do something with the new address, like send a syslog message.
       } else {
          // There was a host resolution error. Inspect record.last_error(),
          // which is an EAI_* error from netdb.h.
       }
    }

  private:
    eos::ip_addr_t address;
 };

namespace eos
class aresolve_handler
#include <aresolve.h>

The Aresolve handler.

This handler receives callback notifications about objects that are being resolved via watch_* calls.

Public Functions

aresolve_handler(aresolve_mgr *)
aresolve_mgr * get_aresolve_mgr() const
void watch_host(std::string const & host, bool watch)

Starts or stops watching IPv4 and IPv6 addresses for the provided host name.

When host resolution completes or an error occurs, on_aresolve_host() is called. After host resolution completes initially, watched hosts will be refreshed automatically. When changes in the result happen, your handler’s on_aresolve_host(), method is called. In this way, you need only watch hostnames you’re interested in and implement the on_aresolve_host() method to deal with the changes in results.

Parameters
  • host -

    The hostname to watch

  • watch -

    If true, start watching the hostname, else stop watching.

virtual void on_aresolve_host(aresolve_record_host const & record)

Callback called by Aresolve when host resolution completes.

Called by Aresolve when DNS resolution of a host previously watched by watch_host() completes.

Will be called upon successful updates or otherwise, when either the valid or last update time member attributes change. May be called more than once for a given hostname, if DNS had a temporary failure.

Parameters
  • record -

    A record containing new or updated information about a watched host.

class aresolve_mgr

Public Functions

virtual ~aresolve_mgr()
virtual uint32_t aresolve_short_time() const = 0

Aresolve implementation configuration settings.

The short time defines the minimum period between DNS resolutions. (default: 1s)

virtual uint32_t aresolve_long_time() const = 0

Returns the long timer, or seconds between repeated DNS queries.

You will receive at most one notification per DNS query (watched host) every aresolve_long_time() number of seconds. (default: 300s)

virtual void aresolve_short_time_is(uint32_t) = 0

Sets the Aresolve short timer to the value provided.

virtual void aresolve_long_time_is(uint32_t) = 0

Sets the Aresolve long timer to the value provided.

Protected Functions

aresolve_mgr()

Private Members

aresolve_mgr

Friends

friend class aresolve_handler

Type definitions in aresolve

namespace eos
class aresolve_record_base
#include <aresolve.h>

A base DNS response class.

When receiving an aresolve_record_*, if valid() is false, the last_error() method should be called to receive the EAI_* error (which can be converted to a string with gai_strerror()). If there is no error, accessors in subclasses of aresolve_record_base contain the latest update for the request.

This class is not instantiated or received by user code.

Public Functions

std::string qname() const

Getter for ‘qname’: the DNS query (request) name.

seconds_t last_refresh() const

Getter for ‘last_refresh’: the last refresh time, seconds since boot.

bool valid() const

Getter for ‘valid’: the flag indicating whether the request was successful. If false, last_error() will return a non-zero value.

int last_error() const

Getter for ‘last_error’: error code reporting the last error, or 0 if the record was resolved. Values are EAI_* constants in netdb.h.

std::string to_string() const

Returns a string representation of the current object’s values.

Protected Functions

aresolve_record_base()
virtual ~aresolve_record_base()

Private Members

std::string qname_
seconds_t last_refresh_
bool valid_
int last_error_

Friends

friend class aresolve_internal
friend std::ostream & operator<<

A utility stream operator that adds a string representation of aresolve_record_base to the ostream.

class aresolve_record_host
#include <aresolve.h>

A DNS response for a hostname query containing resolved IP addresses received by the on_aresolve_host() receiver method. A host response contains zero or more IPv4 or IPv6 addresses.

Public Functions

aresolve_record_host()
virtual ~aresolve_record_host()
std::list< ip_addr_t > const & addr_v4() const

Getter for ‘addr_v4’: the resolved IPv4 addresses for the qname().

std::list< ip_addr_t > const & addr_v6() const

Getter for ‘addr_v6’: the resolved IPv6 addresses for the qname().

std::string to_string() const

Returns a string representation of the current object’s values.

Private Members

std::list< ip_addr_t > addr_v4_
std::list< ip_addr_t > addr_v6_

Friends

friend class aresolve_internal
friend std::ostream & operator<<

A utility stream operator that adds a string representation of aresolve_record_host to the ostream.

Table Of Contents

Previous topic

agent

Next topic

base