The DNSClient class handles communication with the DNS server. More...

#include <dns_client.h>

Classes
class	Callback
	Callback for the `DNSClient` class. More...

Public Types
enum	Protocol { UDP, TCP }
	Transport layer protocol used by a DNS Client to communicate with a server. More...

enum	Status { SUCCESS, TIMEOUT, IO_STOPPED, INVALID_RESPONSE, OTHER }
	A status code of the DNSClient. More...

Public Member Functions
	DNSClient (D2UpdateMessagePtr &response_placeholder, Callback *callback, const Protocol proto=UDP)
	Constructor. More...

	~DNSClient ()
	Virtual destructor, does nothing. More...

void	doUpdate (asiolink::IOService &io_service, const asiolink::IOAddress &ns_addr, const uint16_t ns_port, D2UpdateMessage &update, const unsigned int wait, const dns::TSIGKeyPtr &tsig_key=dns::TSIGKeyPtr())
	Start asynchronous DNS Update with TSIG. More...

Static Public Member Functions
static unsigned int	getMaxTimeout ()
	Returns maximal allowed timeout value accepted by `DNSClient::doUpdate`. More...

Detailed Description

The DNSClient class handles communication with the DNS server.

Communication with the DNS server is asynchronous. Caller must provide a callback, which will be invoked when the response from the DNS server is received, a timeout has occurred or IO service has been stopped for any reason. The caller-supplied callback is called by the internal callback operator implemented by DNSClient. This callback is responsible for initializing the D2UpdateMessage instance which encapsulates the response from the DNS. This initialization does not take place if the response from DNS is not received.

Caller must supply a pointer to the D2UpdateMessage object, which will encapsulate DNS response, through class constructor. An exception will be thrown if the pointer is not initialized by the caller.

Todo:: Ultimately, this class will support both TCP and UDP Transport. Currently only UDP is supported and can be specified as a preferred protocol. DNSClient constructor will throw an exception if TCP is specified. Once both protocols are supported, the DNSClient logic will try to obey caller's preference. However, it may use the other protocol if on its own discretion, when there is a legitimate reason to do so. For example, if communication with the server using preferred protocol fails.

Definition at line 49 of file dns_client.h.

Member Enumeration Documentation

enum isc::d2::DNSClient::Protocol

Transport layer protocol used by a DNS Client to communicate with a server.

Enumerator
UDP
TCP

Definition at line 54 of file dns_client.h.

enum isc::d2::DNSClient::Status

A status code of the DNSClient.

Enumerator
SUCCESS	Response received and is ok.
TIMEOUT	No response, timeout.
IO_STOPPED	IO was stopped.
INVALID_RESPONSE	Response received but invalid.
OTHER	Other, unclassified error.

Definition at line 60 of file dns_client.h.

Constructor & Destructor Documentation

isc::d2::DNSClient::DNSClient	(	D2UpdateMessagePtr &	response_placeholder,
		Callback *	callback,
		const Protocol	proto = `UDP`
	)

Constructor.

Parameters

response_placeholder	Message object pointer which will be updated with dynamically allocated object holding the DNS server's response.
callback	Pointer to an object implementing `DNSClient::Callback` class. This object will be called when DNS message exchange completes or if an error occurs. NULL value disables callback invocation.
proto	caller's preference regarding Transport layer protocol to be used by DNS Client to communicate with a server.

Definition at line 232 of file dns_client.cc.

isc::d2::DNSClient::~DNSClient ( )

Virtual destructor, does nothing.

Definition at line 237 of file dns_client.cc.

Member Function Documentation

void isc::d2::DNSClient::doUpdate	(	asiolink::IOService &	io_service,
		const asiolink::IOAddress &	ns_addr,
		const uint16_t	ns_port,
		D2UpdateMessage &	update,
		const unsigned int	wait,
		const dns::TSIGKeyPtr &	tsig_key = `dns::TSIGKeyPtr()`
	)

Start asynchronous DNS Update with TSIG.

This function starts asynchronous DNS Update and returns. The DNS Update will be executed by the specified IO service. Once the message exchange with a DNS server is complete, timeout occurs or IO operation is interrupted, the caller-supplied callback function will be invoked.

An address and port of the DNS server is specified through the function arguments so as the same instance of the DNSClient can be used to initiate multiple message exchanges.

Parameters

io_service	IO service to be used to run the message exchange.
ns_addr	DNS server address.
ns_port	DNS server port.
update	A DNS Update message to be sent to the server.
wait	A timeout (in milliseconds) for the response. If a response is not received within the timeout, exchange is interrupted. This value must not exceed maximal value for 'int' data type.
tsig_key	A pointer to an `isc::dns::TSIGKey` object that will (if not null) be used to sign the DNS Update message and verify the response.