The D2UpdateMessage encapsulates a DNS Update message. More...

#include <d2_update_message.h>

Public Types
enum	Direction { INBOUND , OUTBOUND }
	Indicates if the `D2UpdateMessage` object encapsulates Inbound or Outbound message. More...

enum	QRFlag { REQUEST , RESPONSE }
	Indicates whether DNS Update message is a REQUEST or RESPONSE. More...

enum	UpdateMsgSection { SECTION_ZONE , SECTION_PREREQUISITE , SECTION_UPDATE , SECTION_ADDITIONAL }
	Identifies sections in the DNS Update Message. More...

Public Member Functions
	D2UpdateMessage (const Direction direction=OUTBOUND)
	Constructor used to create an instance of the DNS Update Message (either outgoing or incoming).

Functions returning iterators to RRsets in message sections.
const dns::RRsetIterator	beginSection (const UpdateMsgSection section) const
	Return iterators pointing to the beginning of the list of RRsets, which belong to the specified section.

const dns::RRsetIterator	endSection (const UpdateMsgSection section) const
	Return iterators pointing to the end of the list of RRsets, which belong to the specified section.

void	setZone (const dns::Name &zone, const dns::RRClass &rrclass)
	Sets the Zone record.

D2ZonePtr	getZone () const
	Returns a pointer to the object representing Zone record.

void	addRRset (const UpdateMsgSection section, const dns::RRsetPtr &rrset)
	Adds an RRset to the specified section.

Functions to handle message encoding and decoding.
void	toWire (dns::AbstractMessageRenderer &renderer, dns::TSIGContext *const tsig_ctx=NULL)
	Encode outgoing message into wire format.

void	fromWire (const void received_data, size_t bytes_received, dns::TSIGContext const tsig_context=NULL)
	Decode incoming message from the wire format.

Copy constructor and assignment operator
Copy constructor and assignment operator are private because we assume there will be no need to copy messages on the client side.
QRFlag	getQRFlag () const
	Returns enum value indicating if the message is a REQUEST or RESPONSE.

uint16_t	getId () const
	Returns message ID.

void	setId (const uint16_t id)
	Sets message ID.

const dns::Rcode &	getRcode () const
	Returns an object representing message RCode.

void	setRcode (const dns::Rcode &rcode)
	Sets message RCode.

unsigned int	getRRCount (const UpdateMsgSection section) const
	Returns number of RRsets in the specified message section.

Detailed Description

The D2UpdateMessage encapsulates a DNS Update message.

This class represents the DNS Update message. Functions exposed by this class allow to specify the data sections carried by the message and create an on-wire format of this message. This class is also used to decode messages received from the DNS server in the on-wire format.

Design choice: A dedicated class has been created to encapsulate DNS Update message because existing isc::dns::Message is designed to support regular DNS messages (described in RFC 1035) only. Although DNS Update has the same format, particular sections serve different purposes. In order to avoid rewrite of significant portions of isc::dns::Message class, this class is implemented in-terms-of isc::dns::Message class to reuse its functionality where possible.

Definition at line 89 of file d2_update_message.h.

Member Enumeration Documentation

◆ Direction

enum isc::d2::D2UpdateMessage::Direction

Indicates if the D2UpdateMessage object encapsulates Inbound or Outbound message.

Enumerator
INBOUND
OUTBOUND

Definition at line 94 of file d2_update_message.h.

◆ QRFlag

enum isc::d2::D2UpdateMessage::QRFlag

Indicates whether DNS Update message is a REQUEST or RESPONSE.

Enumerator
REQUEST
RESPONSE

Definition at line 100 of file d2_update_message.h.

◆ UpdateMsgSection

enum isc::d2::D2UpdateMessage::UpdateMsgSection

Identifies sections in the DNS Update Message.

Each message comprises message Header and may contain the following sections:

ZONE
PREREQUISITE
UPDATE
ADDITIONAL

The enum elements are used by functions such as getRRCount (to get the number of records in a corresponding section) and beginSection and endSection (to access data in the corresponding section).

Enumerator
SECTION_ZONE
SECTION_PREREQUISITE
SECTION_UPDATE
SECTION_ADDITIONAL

Definition at line 117 of file d2_update_message.h.

Constructor & Destructor Documentation

◆ D2UpdateMessage()

isc::d2::D2UpdateMessage::D2UpdateMessage ( const Direction direction = OUTBOUND )

Constructor used to create an instance of the DNS Update Message (either outgoing or incoming).

This constructor is used to create an instance of either incoming or outgoing DNS Update message. The boolean argument indicates whether it is incoming (true) or outgoing (false) message. For incoming messages the D2UpdateMessage::fromWire function is used to parse on-wire data. For outgoing messages, modifier functions should be used to set the message contents and D2UpdateMessage::toWire function to create on-wire data.

Parameters

direction indicates if this is an inbound or outbound message.

Definition at line 20 of file d2_update_message.cc.

References isc::dns::Message::HEADERFLAG_QR, isc::dns::Rcode::NOERROR(), OUTBOUND, isc::dns::Message::setHeaderFlag(), isc::dns::Message::setOpcode(), isc::dns::Message::setRcode(), and isc::dns::Opcode::UPDATE_CODE.

Here is the call graph for this function:

Member Function Documentation

◆ addRRset()

void isc::d2::D2UpdateMessage::addRRset	(	const UpdateMsgSection	section,
		const dns::RRsetPtr &	rrset
	)

Adds an RRset to the specified section.

This function may throw exception if the specified section is out of bounds or Zone section update is attempted. For Zone section D2UpdateMessage::setZone function should be used instead. Also, this function expects that rrset argument is non-NULL.

Parameters

section	A message section where the RRset should be added.
rrset	A reference to a RRset which should be added.

Definition at line 95 of file d2_update_message.cc.

References isc::dns::Message::addRRset(), isc_throw, and SECTION_ZONE.

Here is the call graph for this function:

◆ beginSection()

const dns::RRsetIterator isc::d2::D2UpdateMessage::beginSection ( const UpdateMsgSection section ) const

Return iterators pointing to the beginning of the list of RRsets, which belong to the specified section.

Parameters

section An UpdateMsgSection enum specifying a message section for which the iterator should be returned.

Returns: An iterator pointing to the beginning of the list of the RRsets, which belong to the specified section.

Definition at line 65 of file d2_update_message.cc.

References isc::dns::Message::beginSection().

Here is the call graph for this function:

◆ endSection()

const dns::RRsetIterator isc::d2::D2UpdateMessage::endSection ( const UpdateMsgSection section ) const

Return iterators pointing to the end of the list of RRsets, which belong to the specified section.

Parameters

section An UpdateMsgSection enum specifying a message section for which the iterator should be returned.

Returns: An iterator pointing to the end of the list of the RRsets, which belong to the specified section.

Definition at line 70 of file d2_update_message.cc.

References isc::dns::Message::endSection().

Here is the call graph for this function:

◆ fromWire()

void isc::d2::D2UpdateMessage::fromWire	(	const void *	received_data,
		size_t	bytes_received,
		dns::TSIGContext *const	tsig_context = `NULL`
	)

Decode incoming message from the wire format.

This function decodes the DNS Update message stored in the buffer specified by the function argument. If given a TSIG context, then the function will first attempt to use that context to verify the message signature. If verification fails a TSIGVerifyError exception will be thrown. The function then parses message header and extracts the section counters: ZOCOUNT, PRCOUNT, UPCOUNT and ADCOUNT. Using these counters, function identifies message sections, which follow message header. These sections can be later accessed using: D2UpdateMessage::getZone, D2UpdateMessage::beginSection and D2UpdateMessage::endSection functions.

This function is NOT exception safe. It signals message decoding errors through exceptions. Message decoding error may occur if the received message does not conform to the general DNS Message format, specified in RFC 1035. Errors which are specific to DNS Update messages include:

Invalid Opcode - not an UPDATE.
Invalid QR flag - the QR bit should be set to indicate that the message is the server response.
The number of records in the Zone section is greater than 1.

Parameters

received_data	buffer holding DNS Update message to be parsed.
bytes_received	the number of bytes in received_data
tsig_context	A TSIG context that is to be used to verify the message. If NULL TSIG verification will not be attempted.

Definition at line 124 of file d2_update_message.cc.

References isc::dns::Message::beginQuestion(), isc::dns::Message::fromWire(), getRRCount(), isc::dns::Message::getTSIGRecord(), isc_throw, isc::dns::TSIGError::NOERROR(), SECTION_ZONE, and isc::dns::TSIGContext::verify().

Here is the call graph for this function:

◆ getId()

uint16_t isc::d2::D2UpdateMessage::getId ( ) const

Returns message ID.

Returns: message ID.

Definition at line 39 of file d2_update_message.cc.

References isc::dns::Message::getQid().

Here is the call graph for this function:

◆ getQRFlag()

D2UpdateMessage::QRFlag isc::d2::D2UpdateMessage::getQRFlag ( ) const

Returns enum value indicating if the message is a REQUEST or RESPONSE.

The returned value is REQUEST if the message is created as an outgoing message. In such case the QR flag bit in the message header is cleared. The returned value is RESPONSE if the message is created as an incoming message and the QR flag bit was set in the received message header.

Returns: An enum value indicating whether the message is a REQUEST or RESPONSE.

Definition at line 33 of file d2_update_message.cc.

References isc::dns::Message::getHeaderFlag(), isc::dns::Message::HEADERFLAG_QR, REQUEST, and RESPONSE.

Referenced by toWire().

Here is the call graph for this function:

◆ getRcode()

const dns::Rcode & isc::d2::D2UpdateMessage::getRcode ( ) const

Returns an object representing message RCode.

Returns: An object representing message RCode.

Definition at line 50 of file d2_update_message.cc.

References isc::dns::Message::getRcode().

Here is the call graph for this function:

◆ getRRCount()

unsigned int isc::d2::D2UpdateMessage::getRRCount ( const UpdateMsgSection section ) const

Returns number of RRsets in the specified message section.

Parameters

section An UpdateMsgSection enum specifying a message section for which the number of RRsets is to be returned.

Returns: A number of RRsets in the specified message section.

Definition at line 60 of file d2_update_message.cc.

References isc::dns::Message::getRRCount().

Referenced by fromWire(), and toWire().

Here is the call graph for this function:

◆ getZone()

D2ZonePtr isc::d2::D2UpdateMessage::getZone ( ) const

Returns a pointer to the object representing Zone record.

Returns: A pointer to the object representing Zone record.

Definition at line 90 of file d2_update_message.cc.

◆ setId()

void isc::d2::D2UpdateMessage::setId ( const uint16_t id )

Sets message ID.

Parameters

id	16-bit value of the message id.

Definition at line 44 of file d2_update_message.cc.

References isc::dns::Message::setQid().

Here is the call graph for this function:

◆ setRcode()

void isc::d2::D2UpdateMessage::setRcode ( const dns::Rcode & rcode )

Sets message RCode.

Parameters

rcode An object representing message RCode.

Definition at line 55 of file d2_update_message.cc.

References isc::dns::Message::setRcode().

Here is the call graph for this function:

◆ setZone()

void isc::d2::D2UpdateMessage::setZone	(	const dns::Name &	zone,
		const dns::RRClass &	rrclass
	)

Sets the Zone record.

This function creates the D2Zone object, representing a Zone record for the outgoing message. If the Zone record is already set, it is replaced by the new record being set by this function. The RRType for the record is always SOA.

Parameters

zone	A name of the zone being updated.
rrclass	A class of the zone record.

Definition at line 75 of file d2_update_message.cc.

References isc::dns::Message::addQuestion(), isc::dns::Message::clearSection(), isc::dns::Question::getClass(), isc::dns::Question::getName(), isc::dns::Message::getRRCount(), isc::dns::Message::SECTION_QUESTION, and isc::dns::RRType::SOA().

Here is the call graph for this function:

◆ toWire()

void isc::d2::D2UpdateMessage::toWire	(	dns::AbstractMessageRenderer &	renderer,
		dns::TSIGContext *const	tsig_ctx = `NULL`
	)

Encode outgoing message into wire format.

This function encodes the DNS Update into the wire format. The format of such a message is described in the RFC2136, section 2. Some of the sections which belong to encoded message may be empty. If a particular message section is empty (does not comprise any RRs), the corresponding counter in the message header is set to 0. These counters are: PRCOUNT, UPCOUNT, ADCOUNT for the Prerequisites, Update RRs and Additional Data RRs respectively. The ZOCOUNT must be equal to 1 because RFC2136 requires that the message comprises exactly one Zone record.

If given a TSIG context, this method will pass the context down into dns::Message.toWire() method which signs the message using the context.

This function does not guarantee exception safety. However, exceptions should be rare because D2UpdateMessage class API prevents invalid use of the class. The typical case, when this function may throw an exception is when this it is called on the object representing incoming (instead of outgoing) message. In such case, the QR field will be set to RESPONSE, which is invalid setting when calling this function.

Parameters

renderer	A renderer object used to generate the message wire format.
tsig_ctx	A TSIG context that is to be used for signing the message. If NULL the message will not be signed.

Definition at line 105 of file d2_update_message.cc.

References getQRFlag(), getRRCount(), isc_throw, REQUEST, SECTION_ZONE, and isc::dns::Message::toWire().

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

Here is the call graph for this function:

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

Public Types

Public Member Functions

Functions to handle message encoding and decoding.

Copy constructor and assignment operator

Detailed Description

Member Enumeration Documentation

◆ Direction

◆ QRFlag

◆ UpdateMsgSection

Constructor & Destructor Documentation

◆ D2UpdateMessage()

Member Function Documentation

◆ addRRset()

◆ beginSection()

◆ endSection()

◆ fromWire()

◆ getId()

◆ getQRFlag()

◆ getRcode()

◆ getRRCount()

◆ getZone()

◆ setId()

◆ setRcode()

◆ setZone()

◆ toWire()