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.

	~DNSClient ()
	Virtual destructor, does nothing.

void	stop ()
	Stop the client.

Copy constructor and assignment operator
Copy constructor and assignment operator are private because there are no use cases when a DNSClient instance will need to be copied. Also, it is desired to avoid copying a DNSClient::impl_ pointer and external callbacks.
void	doUpdate (const asiolink::IOServicePtr &io_service, const asiolink::IOAddress &ns_addr, const uint16_t ns_port, D2UpdateMessage &update, const unsigned int wait, const D2TsigKeyPtr &tsig_key=D2TsigKeyPtr())
	Start asynchronous DNS Update with TSIG.

static unsigned int	getMaxTimeout ()
	Returns maximal allowed timeout value accepted by `DNSClient::doUpdate`.

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 47 of file dns_client.h.

Member Enumeration Documentation

◆ Protocol

enum isc::d2::DNSClient::Protocol

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

Enumerator
UDP
TCP

Definition at line 52 of file dns_client.h.

◆ Status

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 58 of file dns_client.h.

Constructor & Destructor Documentation

◆ DNSClient()

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 323 of file dns_client.cc.

◆ ~DNSClient()

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

Virtual destructor, does nothing.

Definition at line 328 of file dns_client.cc.

References stop().

Here is the call graph for this function:

Member Function Documentation

◆ doUpdate()

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

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 `D2TsigKeyPtr` object that will (if not null) be used to sign the DNS Update message and verify the response.

Definition at line 344 of file dns_client.cc.

◆ getMaxTimeout()

unsigned int isc::d2::DNSClient::getMaxTimeout ( )

static

Returns maximal allowed timeout value accepted by DNSClient::doUpdate.

Returns: maximal allowed timeout value accepted by DNSClient::doUpdate

Definition at line 338 of file dns_client.cc.

Referenced by isc::d2::DNSClientImpl::doUpdate().

◆ stop()

void isc::d2::DNSClient::stop ( )

Stop the client.

Definition at line 333 of file dns_client.cc.

Referenced by ~DNSClient().

The documentation for this class was generated from the following files:

Classes

Public Types

Public Member Functions

Copy constructor and assignment operator