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.

uint32_t hash() const

The hash function for type aresolve_record_base.

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().

uint32_t hash() const

The hash function for type aresolve_record_host.

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.