Kea: isc::util::OutputBuffer Class Reference

| Kea 3.2.0-git

isc::util::OutputBuffer Class Reference

The `OutputBuffer` class is a buffer abstraction for manipulating mutable data. More...

`#include <buffer.h>`

## Public Member Functions
| OutputBuffer (const OutputBuffer &other)
| Copy constructor.
| OutputBuffer (size_t len)
| Constructor.
| ~OutputBuffer ()=default
| Destructor.
void | clear ()
| Clear buffer content.
size_t | getCapacity () const
| Return the current capacity of the buffer.
const uint8_t * | getData () const
| Return a pointer to the head of the data stored in the buffer.
const void * | getDataAsVoidPtr () const
| Return data as a pointer to void.
size_t | getLength () const
| Return the length of data written in the buffer.
const std::vector< uint8_t > & | getVector () const
| Return the buffer.
OutputBuffer & | operator= (const OutputBuffer &other)
| Assignment operator.
uint8_t | operator[] (size_t position) const
| Return the value of the buffer at the specified position.
void | skip (size_t len)
| Insert a specified length of gap at the end of the buffer.
void | trim (size_t len)
| Trim the specified length of data from the end of the buffer.
void | writeData (const void *data, size_t len)
| Copy an arbitrary length of data into the buffer.
void | writeUint16 (uint16_t data)
| Write an unsigned 16-bit integer in host byte order into the buffer in network byte order.
void | writeUint16At (uint16_t data, size_t position)
| Write an unsigned 16-bit integer in host byte order at the specified position of the buffer in network byte order.
void | writeUint32 (uint32_t data)
| Write an unsigned 32-bit integer in host byte order into the buffer in network byte order.
void | writeUint64 (uint64_t data)
| Write an unsigned 64-bit integer in host byte order into the buffer in network byte order.
void | writeUint8 (uint8_t data)
| Write an unsigned 8-bit integer into the buffer.
void | writeUint8At (uint8_t data, size_t position)
| Write an unsigned 8-bit integer into the buffer.

## Detailed Description

The `OutputBuffer` class is a buffer abstraction for manipulating mutable data.

The main purpose of this class is to provide a safe workplace for constructing wire-format data to be sent out to a network. Here, safe means that it automatically allocates necessary memory and avoid buffer overrun.

Like for the `InputBuffer` class, applications normally use this class only in a limited situation. One common usage of this class for an application would be something like this:

OutputBuffer buffer(4096); // give a sufficiently large initial size
// Pass the buffer to a DNS message object to construct a wire-format DNS message.
struct sockaddr to_address;
sendto(s, buffer.getDataAsVoidPtr(), buffer.getLength(), 0, &to_address, sizeof(to_address));
isc::util::OutputBuffer::OutputBuffer
OutputBuffer(size_t len)
Constructor.
Definition buffer.h:351

where the `getData()` (in fact `getDataAsVoidPtr()`) method gives a reference to the internal memory region stored in the `buffer` object. This is a suboptimal design in that it exposes an encapsulated "handle" of an object to its user. Unfortunately, there is no easy way to avoid this without involving expensive data copy if we want to use this object with a legacy API such as a BSD socket interface. And, indeed, this is one major purpose for this object. Applications should use this method only under such a special circumstance. It should also be noted that the memory region returned by `getData()` may be invalidated after a subsequent write operation.

An `OutputBuffer` class object automatically extends its memory region when data is written beyond the end of the current buffer. However, it will involve performance overhead such as reallocating more memory and copying data. It is therefore recommended to construct the buffer object with a sufficiently large initial size. The `getCapacity()` method provides the current maximum size of data (including the portion already written) that can be written into the buffer without causing memory reallocation.

Methods for writing data into the buffer generally work like an output stream: it begins with the head of the buffer, and once some length of data is written into the buffer, the next write operation will take place from the end of the buffer. Other methods to emulate "random access" are also provided (e.g., `writeUint16At()`). The normal write operations are normally exception-free as this class automatically extends the buffer when necessary. However, in extreme cases such as an attempt of writing multi-GB data, a separate exception (e.g., `std::bad_alloc`) may be thrown by the system. This also applies to the constructor with a very large initial size.

Note to developers: it may make more sense to introduce an abstract base class for the `OutputBuffer` and define the simple implementation as a concrete derived class. That way we can provide flexibility for future extension such as more efficient buffer implementation or allowing users to have their own customized version without modifying the source code. We in fact considered that option, but at the moment chose the simpler approach with a single concrete class, because it may make the implementation unnecessarily complicated while we were still not certain if we really want that flexibility. We may revisit the class design as we see more applications of the class. The same considerations apply to the `InputBuffer` and `MessageRenderer` classes.

Definition at line 346 of file buffer.h.

## Constructor & Destructor Documentation

## ◆ OutputBuffer() [1/2]

isc::util::OutputBuffer::OutputBuffer | ( | size_t | len | ) |
| inlineexplicit

Constructor.

Parameters

  len | The initial allocated length of the buffer in bytes.

Definition at line 351 of file buffer.h.

Referenced by OutputBuffer(), and operator=().

## ◆ OutputBuffer() [2/2]

isc::util::OutputBuffer::OutputBuffer | ( | const OutputBuffer & | other | ) |
| inline

Copy constructor.

Parameters

  other | Source object from which to make a copy.

Definition at line 360 of file buffer.h.

References OutputBuffer().

Here is the call graph for this function:

## ◆ ~OutputBuffer()

isc::util::OutputBuffer::~OutputBuffer | ( |  | ) |
| default

Destructor.

## Member Function Documentation

## ◆ clear()

void isc::util::OutputBuffer::clear | ( |  | ) |
| inline

Clear buffer content.

Definition at line 469 of file buffer.h.

Referenced by isc::dhcp::Dhcp6to4Ipc::handler(), isc::perfdhcp::PktTransform::pack(), and isc::dhcp::Dhcp4o6IpcBase::send().

## ◆ getCapacity()

size_t isc::util::OutputBuffer::getCapacity | ( |  | ) | const
| inline

Return the current capacity of the buffer.

Definition at line 387 of file buffer.h.

Referenced by isc::dhcp::Option6Auth::pack(), and isc::dhcp::Option6Auth::packHashInput().

## ◆ getData()

const uint8_t * isc::util::OutputBuffer::getData | ( |  | ) | const
| inline

Return a pointer to the head of the data stored in the buffer.

The caller can assume that the subsequent `getLength()` bytes are identical to the stored data of the buffer.

Note: The pointer returned by this method may be invalidated after a subsequent write operation.

Definition at line 398 of file buffer.h.

Referenced by isc::perfdhcp::LocalizedOption::LocalizedOption(), isc::dns::rdata::generic::detail::TXTLikeImpl< TXT, 16 >::compare(), isc::dns::TSIGContext::TSIGContextImpl::digestDNSMessage(), isc::dns::TSIGContext::TSIGContextImpl::digestPreviousMAC(), isc::dns::TSIGContext::TSIGContextImpl::digestTSIGVariables(), isc::dhcp_ddns::NameChangeUDPSender::doSend(), getDataAsVoidPtr(), isc::config::BaseCommandMgr::getHash(), isc::dhcp::Dhcp4o6IpcBase::send(), isc::dhcp::PktFilterBPF::send(), isc::dhcp::PktFilterLPF::send(), isc::dns::TSIGContext::sign(), isc::gss_tsig::GssTsigContext::sign(), isc::dhcp::LibDHCP::splitOptions4(), isc::dhcp::Option::toBinary(), isc::dhcp::AllocEngine::updateLease6ExtendedInfo(), and isc::dhcp::writeIpUdpHeader().

## ◆ getDataAsVoidPtr()

const void * isc::util::OutputBuffer::getDataAsVoidPtr | ( |  | ) | const
| inline

Return data as a pointer to void.

Definition at line 407 of file buffer.h.

References getData().

Here is the call graph for this function:

## ◆ getLength()

size_t isc::util::OutputBuffer::getLength | ( |  | ) | const
| inline

Return the length of data written in the buffer.

Definition at line 412 of file buffer.h.

Referenced by isc::perfdhcp::LocalizedOption::LocalizedOption(), isc::dns::rdata::generic::detail::TXTLikeImpl< TXT, 16 >::compare(), isc::dns::TSIGContext::TSIGContextImpl::digestDNSMessage(), isc::dns::TSIGContext::TSIGContextImpl::digestPreviousMAC(), isc::dns::TSIGContext::TSIGContextImpl::digestTSIGVariables(), isc::dhcp_ddns::NameChangeUDPSender::doSend(), isc::config::BaseCommandMgr::getHash(), isc::dns::rdata::Rdata::getLength(), pkt4_send(), isc::dhcp::Dhcp4o6IpcBase::send(), isc::dhcp::PktFilterBPF::send(), isc::dhcp::PktFilterLPF::send(), isc::dns::AbstractMessageRenderer::setBuffer(), isc::dhcp::LibDHCP::splitOptions4(), isc::dhcp::Option::toBinary(), isc::dhcp::AllocEngine::updateLease6ExtendedInfo(), and isc::dhcp::writeIpUdpHeader().

## ◆ getVector()

const std::vector< uint8_t > & isc::util::OutputBuffer::getVector | ( |  | ) | const
| inline

Return the buffer.

Note
  The main use is to avoid a copy.

Definition at line 436 of file buffer.h.

Referenced by isc::dhcp::Dhcpv6Srv::createNameChangeRequests(), isc::lease_query::LeaseQueryImpl6::makeRelayOption(), and isc::dhcp::Pkt4o6::pack().

## ◆ operator=()

OutputBuffer & isc::util::OutputBuffer::operator= | ( | const OutputBuffer & | other | ) |
| inline

Assignment operator.

Parameters

  other | Object to copy into "this".

Definition at line 373 of file buffer.h.

References OutputBuffer().

Here is the call graph for this function:

## ◆ operator[]()

uint8_t isc::util::OutputBuffer::operator[] | ( | size_t | position | ) | const
| inline

Return the value of the buffer at the specified position.

`pos` must specify the valid position of the buffer; otherwise an exception class of `isc::OutOfRange` will be thrown.

Parameters

  position | The position in the buffer to be returned.

Definition at line 423 of file buffer.h.

References isc_throw.

## ◆ skip()

void isc::util::OutputBuffer::skip | ( | size_t | len | ) |
| inline

Insert a specified length of gap at the end of the buffer.

The caller should not assume any particular value to be inserted. This method is provided as a shortcut to make a hole in the buffer that is to be filled in later, e.g, by writeUint16At().

Parameters

  len | The length of the gap to be inserted in bytes.

Definition at line 448 of file buffer.h.

## ◆ trim()

void isc::util::OutputBuffer::trim | ( | size_t | len | ) |
| inline

Trim the specified length of data from the end of the buffer.

The specified length must not exceed the current data size of the buffer; otherwise an exception of class `isc::OutOfRange` will be thrown.

Parameters

  len | The length of data that should be trimmed.

Definition at line 459 of file buffer.h.

References isc_throw.

## ◆ writeData()

void isc::util::OutputBuffer::writeData | ( | const void * | data,
|  | size_t | len )
| inline

Copy an arbitrary length of data into the buffer.

No conversion on the copied data is performed.

Parameters

  data | A pointer to the data to be copied into the buffer.
  len | The length of the data in bytes.

Definition at line 559 of file buffer.h.

Referenced by isc::dns::TSIGContext::TSIGContextImpl::digestDNSMessage(), isc::dns::TSIGContext::TSIGContextImpl::digestPreviousMAC(), isc::lease_query::LeaseQueryImpl6::makeRelayOption(), isc::dhcp::OpaqueDataTuple::pack(), isc::dhcp::Option4SlpServiceScope::pack(), isc::dhcp::Option6AddrLst::pack(), isc::dhcp::Option6IAAddr::pack(), isc::dhcp::Option6IAPrefix::pack(), isc::dhcp::Option6PDExclude::pack(), isc::dhcp::Option6StatusCode::pack(), isc::dhcp::Option::pack(), isc::dhcp::OptionClasslessStaticRoute::pack(), isc::dhcp::OptionCustom::pack(), isc::dhcp::OptionString::pack(), isc::perfdhcp::PktTransform::pack(), isc::dhcp::Option6Dnr::packAddresses(), isc::dhcp::DnrInstance::packAdn(), isc::dhcp::Option4ClientFqdn::packDomainName(), isc::dhcp::Option6ClientFqdn::packDomainName(), isc::dhcp::DnrInstance::packSvcParams(), pkt4_send(), isc::dhcp::PktFilterBPF::send(), isc::dhcp::PktFilterLPF::send(), isc::cryptolink::HMACImpl::sign(), isc::dhcp_ddns::NameChangeRequest::toFormat(), isc::dns::Name::toWire(), isc::dns::rdata::generic::detail::TXTLikeImpl< TXT, 16 >::toWire(), isc::dns::rdata::generic::Generic::toWire(), and isc::dhcp::writeEthernetHeader().

## ◆ writeUint16()

void isc::util::OutputBuffer::writeUint16 | ( | uint16_t | data | ) |
| inline

Write an unsigned 16-bit integer in host byte order into the buffer in network byte order.

Parameters

  data | The 16-bit integer to be written into the buffer.

Definition at line 501 of file buffer.h.

Referenced by isc::dns::TSIGContext::TSIGContextImpl::digestDNSMessage(), isc::dns::TSIGContext::TSIGContextImpl::digestPreviousMAC(), isc::dns::TSIGContext::TSIGContextImpl::digestTSIGVariables(), isc::lease_query::LeaseQueryImpl6::makeRelayOption(), isc::dhcp::OpaqueDataTuple::pack(), isc::dhcp::Option4Dnr::pack(), isc::dhcp::Option6AddrLst::pack(), isc::dhcp::Option6Auth::pack(), isc::dhcp::Option6Dnr::pack(), isc::dhcp::Option6IA::pack(), isc::dhcp::Option6IAAddr::pack(), isc::dhcp::Option6IAPrefix::pack(), isc::dhcp::Option6StatusCode::pack(), isc::dhcp::OptionInt< uint8_t >::pack(), isc::dhcp::OptionIntArray< uint8_t >::pack(), isc::dhcp::Option6Auth::packHashInput(), isc::dhcp::Option::packHeader(), isc::dns::TSIGContext::sign(), isc::gss_tsig::GssTsigContext::sign(), isc::dhcp_ddns::NameChangeRequest::toFormat(), isc::dns::RRClass::toWire(), isc::dns::RRType::toWire(), isc::dhcp::writeEthernetHeader(), and isc::dhcp::writeIpUdpHeader().

## ◆ writeUint16At()

void isc::util::OutputBuffer::writeUint16At | ( | uint16_t | data,
|  | size_t | position )
| inline

Write an unsigned 16-bit integer in host byte order at the specified position of the buffer in network byte order.

The buffer must have a sufficient room to store the given data at the given position, that is, `pos + 2 < getLength()`; otherwise an exception of class `isc::OutOfRange` will be thrown. Note also, that this method never extends the buffer.

Parameters

  data | The 16-bit integer to be written into the buffer.
  position | The beginning position in the buffer to write the data.

Definition at line 517 of file buffer.h.

References isc_throw.

Referenced by isc::dhcp::writeIpUdpHeader().

## ◆ writeUint32()

void isc::util::OutputBuffer::writeUint32 | ( | uint32_t | data | ) |
| inline

Write an unsigned 32-bit integer in host byte order into the buffer in network byte order.

Parameters

  data | The 32-bit integer to be written into the buffer.

Definition at line 531 of file buffer.h.

Referenced by isc::dns::TSIGContext::TSIGContextImpl::digestTSIGVariables(), isc::dhcp::Option4AddrLst::pack(), isc::dhcp::Option6IA::pack(), isc::dhcp::Option6IAAddr::pack(), isc::dhcp::Option6IAPrefix::pack(), isc::dhcp::OptionClasslessStaticRoute::pack(), isc::dhcp::OptionInt< uint8_t >::pack(), isc::dhcp::OptionIntArray< uint8_t >::pack(), isc::dhcp::OptionVendor::pack(), isc::dhcp::OptionVendorClass::pack(), isc::dhcp::DnrInstance::packAddresses(), isc::dns::TSIGContext::sign(), isc::gss_tsig::GssTsigContext::sign(), isc::dns::RRTTL::toWire(), and isc::dhcp::writeIpUdpHeader().

## ◆ writeUint64()

void isc::util::OutputBuffer::writeUint64 | ( | uint64_t | data | ) |
| inline

Write an unsigned 64-bit integer in host byte order into the buffer in network byte order.

Parameters

  data | The 64-bit integer to be written into the buffer.

Definition at line 542 of file buffer.h.

Referenced by isc::dhcp::Option6Auth::pack(), and isc::dhcp::Option6Auth::packHashInput().

## ◆ writeUint8()

void isc::util::OutputBuffer::writeUint8 | ( | uint8_t | data | ) |
| inline

Write an unsigned 8-bit integer into the buffer.

Parameters

  data | The 8-bit integer to be written into the buffer.

Definition at line 476 of file buffer.h.

Referenced by isc::lease_query::LeaseQueryImpl6::makeRelayOption(), isc::dhcp::OpaqueDataTuple::pack(), isc::dhcp::Option4AddrLst::pack(), isc::dhcp::Option4ClientFqdn::pack(), isc::dhcp::Option4Dnr::pack(), isc::dhcp::Option4SlpServiceScope::pack(), isc::dhcp::Option6Auth::pack(), isc::dhcp::Option6ClientFqdn::pack(), isc::dhcp::Option6IAPrefix::pack(), isc::dhcp::Option6PDExclude::pack(), isc::dhcp::OptionInt< uint8_t >::pack(), isc::dhcp::OptionIntArray< uint8_t >::pack(), isc::dhcp::OptionVendor::pack(), isc::dhcp::Option6Auth::packHashInput(), isc::dhcp::Option::packHeader(), and isc::dhcp::writeIpUdpHeader().

## ◆ writeUint8At()

void isc::util::OutputBuffer::writeUint8At | ( | uint8_t | data,
|  | size_t | position )
| inline

Write an unsigned 8-bit integer into the buffer.

The position must be lower than the size of the buffer, otherwise an exception of class `isc::OutOfRange` will be thrown.

Parameters

  data | The 8-bit integer to be written into the buffer.
  position | The position in the buffer to write the data.

Definition at line 488 of file buffer.h.

References isc_throw.

Referenced by isc::perfdhcp::PktTransform::pack().

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

- buffer.h