Kea: isc::util::InputBuffer Class Reference

| Kea 3.0.0

isc::util::InputBuffer Class Reference

The `InputBuffer` class is a buffer abstraction for manipulating read-only data. More...

`#include <buffer.h>`

## Public Member Functions
| InputBuffer (const void *data, size_t len)
| Constructor.
size_t | getLength () const
| Return the length of the data stored in the buffer.
size_t | getPosition () const
| Return the current read position.
void | peekData (void *data, size_t len)
| Peek data of the specified length from the buffer and copy it to the caller supplied buffer.
uint16_t | peekUint16 ()
| Peek an unsigned 16-bit integer in network byte order from the buffer, and return it.
uint32_t | peekUint32 ()
| Read an unsigned 32-bit integer in network byte order from the buffer, and return it.
uint8_t | peekUint8 ()
| Peek an unsigned 8-bit integer from the buffer and return it.
void | peekVector (std::vector< uint8_t > &data, size_t len)
| Peek specified number of bytes as a vector.
void | readData (void *data, size_t len)
| Read data of the specified length from the buffer and copy it to the caller supplied buffer.
uint16_t | readUint16 ()
| Read an unsigned 16-bit integer in network byte order from the buffer, and return it.
uint32_t | readUint32 ()
| Read an unsigned 32-bit integer in network byte order from the buffer, and return it.
uint8_t | readUint8 ()
| Read an unsigned 8-bit integer from the buffer and return it.
void | readVector (std::vector< uint8_t > &data, size_t len)
| Read specified number of bytes as a vector.
void | setPosition (size_t position)
| Set the read position of the buffer to the given value.

## Detailed Description

The `InputBuffer` class is a buffer abstraction for manipulating read-only data.

The main purpose of this class is to provide a safe placeholder for examining wire-format data received from a network.

Applications normally use this class only in a limited situation: as an interface between legacy I/O operation (such as receiving data from a BSD socket) and the rest of the Kea DNS library. One common usage of this class for an application would therefore be something like this:

unsigned char buffer[1024];
struct sockaddr address;
socklen_t address_len = sizeof(address);
int cc = recvfrom(s, buffer, sizeof(buffer), 0, &address, &address_len);
InputBuffer buffer(buffer, cc);
// pass the buffer to a DNS message object to parse the message
isc::util::InputBuffer::InputBuffer
InputBuffer(const void *data, size_t len)
Constructor.
Definition buffer.h:90

Other Kea DNS classes will then use methods of this class to get access to the data, but the application normally doesn't have to care about the details.

An `InputBuffer` object internally holds a reference to the given data, rather than make a local copy of the data. Also, it does not have an ownership of the given data. It is application's responsibility to ensure the data remains valid throughout the lifetime of the `InputBuffer` object. Likewise, this object generally assumes the data isn't modified throughout its lifetime; if the application modifies the data while this object retains a reference to it, the result is undefined. The application will also be responsible for releasing the data when it's not needed if it was dynamically acquired.

This is a deliberate design choice: although it's safer to make a local copy of the given data on construction, it would cause unacceptable performance overhead, especially considering that a DNS message can be as large as a few KB. Alternatively, we could allow the object to allocate memory internally and expose it to the application to store network data in it. This is also a bad design, however, in that we would effectively break the abstraction employed in the class, and do so by publishing "read-only" stuff as a writable memory region. Since there doesn't seem to be a perfect solution, we have adopted what we thought a "least bad" one.

Methods for reading data from the buffer generally work like an input stream: it begins with the head of the data, and once some length of data is read from the buffer, the next read operation will take place from the head of the unread data. An object of this class internally holds (a notion of) where the next read operation should start. We call it the current pointer in this document.

The inequality base_ <= current_ <= end_ is enforced, current_ == base_ at the initial state, current_ == end_ when the whole buffer was read. Even the difference of two pointers is a std::ptrdiff_t it is safe to cast to a size_t because of the inequality.

Definition at line 81 of file buffer.h.

## Constructor & Destructor Documentation

## ◆ InputBuffer()

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

Constructor.

It is caller's responsibility to ensure that the data is valid as long as the buffer exists.

Parameters

  data | A pointer to the data stored in the buffer.
  len | The length of the data in bytes.

Definition at line 90 of file buffer.h.

## Member Function Documentation

## ◆ getLength()

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

Return the length of the data stored in the buffer.

Definition at line 96 of file buffer.h.

Referenced by isc::dns::Name::Name(), isc::dns::RRClass::RRClass(), isc::dns::RRTTL::RRTTL(), isc::dns::RRType::RRType(), isc::dns::rdata::generic::detail::bufferToCharString(), isc::dhcp::decodeEthernetHeader(), isc::dhcp::decodeIpUdpHeader(), isc::dns::Message::parseHeader(), isc::dns::MessageImpl::parseQuestion(), isc::dns::MessageImpl::parseSection(), isc::dhcp::PktFilterBPF::receive(), isc::dhcp::PktFilterLPF::receive(), and isc::dhcp::Pkt4::unpack().

## ◆ getPosition()

size_t isc::util::InputBuffer::getPosition | ( |  | ) | const
| inline

Return the current read position.

Definition at line 101 of file buffer.h.

Referenced by isc::dns::Name::Name(), isc::dns::RRClass::RRClass(), isc::dns::RRTTL::RRTTL(), isc::dns::RRType::RRType(), isc::dns::MessageImpl::addTSIG(), isc::dns::rdata::generic::detail::bufferToCharString(), isc::dns::rdata::createRdata(), isc::dhcp::decodeEthernetHeader(), isc::dhcp::decodeIpUdpHeader(), isc::dns::Message::parseHeader(), isc::dns::MessageImpl::parseQuestion(), isc::dns::MessageImpl::parseSection(), isc::dhcp::PktFilterBPF::receive(), isc::dhcp::PktFilterLPF::receive(), and isc::dhcp::Pkt4::unpack().

## ◆ peekData()

void isc::util::InputBuffer::peekData | ( | void * | data,
|  | size_t | len )
| inline

Peek data of the specified length from the buffer and copy it to the caller supplied buffer.

The data is copied as stored in the buffer; no conversion is performed. If the remaining length of the buffer is smaller than the specified length, an exception of class `isc::OutOfRange` will be thrown.

Definition at line 210 of file buffer.h.

References isc_throw.

Referenced by peekVector(), and readData().

## ◆ peekUint16()

uint16_t isc::util::InputBuffer::peekUint16 | ( |  | ) |
| inline

Peek an unsigned 16-bit integer in network byte order from the buffer, and return it.

If the remaining length of the buffer is smaller than 16-bit, an exception of class `isc::OutOfRange` will be thrown.

Definition at line 149 of file buffer.h.

References isc_throw.

Referenced by readUint16().

## ◆ peekUint32()

uint32_t isc::util::InputBuffer::peekUint32 | ( |  | ) |
| inline

Read an unsigned 32-bit integer in network byte order from the buffer, and return it.

If the remaining length of the buffer is smaller than 32-bit, an exception of class `isc::OutOfRange` will be thrown.

Definition at line 177 of file buffer.h.

References isc_throw.

Referenced by readUint32().

## ◆ peekUint8()

uint8_t isc::util::InputBuffer::peekUint8 | ( |  | ) |
| inline

Peek an unsigned 8-bit integer from the buffer and return it.

If the remaining length of the buffer is smaller than 8-bit, an exception of class `isc::OutOfRange` will be thrown.

Definition at line 125 of file buffer.h.

References isc_throw.

Referenced by readUint8().

## ◆ peekVector()

void isc::util::InputBuffer::peekVector | ( | std::vector< uint8_t > & | data,
|  | size_t | len )
| inline

Peek specified number of bytes as a vector.

If specified buffer is too short, it will be expanded using vector::resize() method. If the remaining length of the buffer is smaller than the specified length, an exception of class `isc::OutOfRange` will be thrown. Read length zero results in an empty vector.

Parameters

  data | Reference to a buffer (data will be stored there).
  len | Size specified number of bytes to read in a vector.

Definition at line 241 of file buffer.h.

References isc_throw, and peekData().

Referenced by readVector().

Here is the call graph for this function:

## ◆ readData()

void isc::util::InputBuffer::readData | ( | void * | data,
|  | size_t | len )
| inline

Read data of the specified length from the buffer and copy it to the caller supplied buffer.

The data is copied as stored in the buffer; no conversion is performed. If the remaining length of the buffer is smaller than the specified length, an exception of class `isc::OutOfRange` will be thrown.

Definition at line 226 of file buffer.h.

References peekData().

Referenced by isc::dns::rdata::generic::Generic::Generic(), isc::dns::rdata::generic::detail::TXTLikeImpl< TXT, 16 >::TXTLikeImpl(), isc::dns::rdata::generic::detail::bufferToCharString(), and isc::dhcp::Pkt4::unpack().

Here is the call graph for this function:

## ◆ readUint16()

uint16_t isc::util::InputBuffer::readUint16 | ( |  | ) |
| inline

Read an unsigned 16-bit integer in network byte order from the buffer, and return it.

If the remaining length of the buffer is smaller than 16-bit, an exception of class `isc::OutOfRange` will be thrown.

Definition at line 166 of file buffer.h.

References peekUint16().

Referenced by isc::dns::RRClass::RRClass(), isc::dns::RRType::RRType(), isc::dhcp::decodeIpUdpHeader(), isc::dhcp_ddns::NameChangeRequest::fromFormat(), isc::dns::Message::parseHeader(), isc::dns::MessageImpl::parseQuestion(), isc::dns::MessageImpl::parseSection(), and isc::dhcp::Pkt4::unpack().

Here is the call graph for this function:

## ◆ readUint32()

uint32_t isc::util::InputBuffer::readUint32 | ( |  | ) |
| inline

Read an unsigned 32-bit integer in network byte order from the buffer, and return it.

If the remaining length of the buffer is smaller than 32-bit, an exception of class `isc::OutOfRange` will be thrown.

Definition at line 196 of file buffer.h.

References peekUint32().

Referenced by isc::dns::RRTTL::RRTTL(), isc::dhcp::decodeIpUdpHeader(), isc::dns::MessageImpl::parseSection(), and isc::dhcp::Pkt4::unpack().

Here is the call graph for this function:

## ◆ readUint8()

uint8_t isc::util::InputBuffer::readUint8 | ( |  | ) |
| inline

Read an unsigned 8-bit integer from the buffer and return it.

If the remaining length of the buffer is smaller than 8-bit, an exception of class `isc::OutOfRange` will be thrown.

Definition at line 138 of file buffer.h.

References peekUint8().

Referenced by isc::dns::Name::Name(), isc::dns::rdata::generic::detail::TXTLikeImpl< TXT, 16 >::TXTLikeImpl(), isc::dns::rdata::generic::detail::bufferToCharString(), isc::dhcp::decodeIpUdpHeader(), and isc::dhcp::Pkt4::unpack().

Here is the call graph for this function:

## ◆ readVector()

void isc::util::InputBuffer::readVector | ( | std::vector< uint8_t > & | data,
|  | size_t | len )
| inline

Read specified number of bytes as a vector.

If specified buffer is too short, it will be expanded using vector::resize() method. If the remaining length of the buffer is smaller than the specified length, an exception of class `isc::OutOfRange` will be thrown.

Parameters

  data | Reference to a buffer (data will be stored there).
  len | Size specified number of bytes to read in a vector.

Definition at line 262 of file buffer.h.

References peekVector().

Referenced by isc::dhcp::decodeEthernetHeader(), isc::dhcp_ddns::NameChangeRequest::fromFormat(), isc::dhcp::PktFilterBPF::receive(), isc::dhcp::PktFilterLPF::receive(), and isc::dhcp::Pkt4::unpack().

Here is the call graph for this function:

## ◆ setPosition()

void isc::util::InputBuffer::setPosition | ( | size_t | position | ) |
| inline

Set the read position of the buffer to the given value.

The new position must be in the valid range of the buffer; otherwise an exception of class `isc::OutOfRange` will be thrown.

Parameters

  position | The new position (offset from the beginning of the buffer).

Definition at line 112 of file buffer.h.

References isc_throw.

Referenced by isc::dns::Name::Name(), isc::dhcp::decodeEthernetHeader(), isc::dhcp::decodeIpUdpHeader(), isc::dns::Message::fromWire(), and isc::dhcp::PktFilterBPF::receive().

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

- buffer.h