Kea 2.7.0
isc::d2::DNSClient Class Reference

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

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

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_placeholderMessage object pointer which will be updated with dynamically allocated object holding the DNS server's response.
callbackPointer 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.
protocaller'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_serviceIO service to be used to run the message exchange.
ns_addrDNS server address.
ns_portDNS server port.
updateA DNS Update message to be sent to the server.
waitA 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_keyA 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: