ndn::Block Class Reference

Represents a TLV element of the NDN packet format. More...

#include <ndn-cxx/encoding/block.hpp>

+ Inheritance diagram for ndn::Block:
+ Collaboration diagram for ndn::Block:

Classes

class  Error
 

Public Types

using const_iterator = Buffer::const_iterator
 
using element_const_iterator = element_container::const_iterator
 
using element_container = std::vector< Block >
 
using element_iterator = element_container::iterator
 
using value_type = Buffer::value_type
 

Public Member Functions

 Block ()
 Create an invalid Block. More...
 
 Block (Block &&) noexcept
 Move constructor. More...
 
 Block (const Block &)
 Copy constructor. More...
 
 Block (const Block &block, Block::const_iterator begin, Block::const_iterator end, bool verifyLength=true)
 Parse Block within boundaries of an existing Block, reusing underlying wire Buffer. More...
 
 Block (const ConstBufferPtr &buffer)
 Parse Block from a wire Buffer. More...
 
 Block (const EncodingBuffer &buffer)
 Parse Block from an EncodingBuffer. More...
 
 Block (ConstBufferPtr buffer, Buffer::const_iterator begin, Buffer::const_iterator end, bool verifyLength=true)
 Parse Block within boundaries of a wire Buffer. More...
 
 Block (ConstBufferPtr buffer, uint32_t type, Buffer::const_iterator begin, Buffer::const_iterator end, Buffer::const_iterator valueBegin, Buffer::const_iterator valueEnd)
 Create a Block from a wire Buffer without parsing. More...
 
 Block (span< const uint8_t > buffer)
 Parse Block from a byte range. More...
 
 Block (uint32_t type)
 Create a zero-length Block with the specified TLV-TYPE. More...
 
 Block (uint32_t type, const Block &value)
 Create a Block with the specified TLV-TYPE and TLV-VALUE. More...
 
 Block (uint32_t type, ConstBufferPtr value)
 Create a Block with the specified TLV-TYPE and TLV-VALUE. More...
 
const_iterator begin () const
 Returns an iterator to the beginning of the encoded wire. More...
 
Block blockFromValue () const
 Return a new Block constructed from the TLV-VALUE of this Block. More...
 
const uint8_t * data () const
 Returns a raw pointer to the beginning of the encoded wire, i.e., the whole TLV. More...
 
const element_containerelements () const noexcept
 Get container of sub-elements. More...
 
element_const_iterator elements_begin () const noexcept
 Equivalent to elements().begin(). More...
 
element_const_iterator elements_end () const noexcept
 Equivalent to elements().end(). More...
 
size_t elements_size () const noexcept
 Equivalent to elements().size(). More...
 
void encode ()
 Encode sub-elements into TLV-VALUE. More...
 
const_iterator end () const
 Returns an iterator past-the-end of the encoded wire. More...
 
element_iterator erase (element_const_iterator first, element_const_iterator last)
 Erase a range of sub-elements. More...
 
element_iterator erase (element_const_iterator position)
 Erase a sub-element. More...
 
element_const_iterator find (uint32_t type) const
 Find the first sub-element of the specified TLV-TYPE. More...
 
const Blockget (uint32_t type) const
 Return the first sub-element of the specified TLV-TYPE. More...
 
ConstBufferPtr getBuffer () const
 Returns the underlying buffer. More...
 
bool hasValue () const noexcept
 Check if the Block has a non-empty TLV-VALUE. More...
 
bool hasWire () const noexcept
 Check if the Block contains a fully encoded wire representation. More...
 
element_iterator insert (element_const_iterator pos, const Block &element)
 Insert a sub-element. More...
 
bool isValid () const noexcept
 Check if the Block is valid. More...
 
 operator boost::asio::const_buffer () const
 Implicit conversion to boost::asio::const_buffer. More...
 
Blockoperator= (Block &&) noexcept
 Move assignment operator. More...
 
Blockoperator= (const Block &)
 Copy assignment operator. More...
 
void parse () const
 Parse TLV-VALUE into sub-elements. More...
 
void push_back (Block &&element)
 Append a sub-element. More...
 
void push_back (const Block &element)
 Append a sub-element. More...
 
void remove (uint32_t type)
 Remove all sub-elements of the specified TLV-TYPE. More...
 
void reset () noexcept
 Reset the Block to a default-constructed state. More...
 
void resetWire () noexcept
 Reset wire buffer but keep TLV-TYPE and sub-elements (if any). More...
 
size_t size () const
 Returns the size of the encoded wire, i.e., of the whole TLV. More...
 
uint32_t type () const noexcept
 Return the TLV-TYPE of the Block. More...
 
const uint8_t * value () const noexcept
 Return a raw pointer to the beginning of TLV-VALUE. More...
 
const_iterator value_begin () const noexcept
 Get begin iterator of TLV-VALUE. More...
 
span< const uint8_t > value_bytes () const noexcept
 Return a read-only view of TLV-VALUE as a contiguous range of bytes. More...
 
const_iterator value_end () const noexcept
 Get end iterator of TLV-VALUE. More...
 
size_t value_size () const noexcept
 Return the size of TLV-VALUE, i.e., the TLV-LENGTH. More...
 

Static Public Member Functions

static std::tuple< bool, BlockfromBuffer (ConstBufferPtr buffer, size_t offset=0)
 Try to parse Block from a wire buffer. More...
 
static std::tuple< bool, BlockfromBuffer (span< const uint8_t > buffer)
 Try to parse Block from a byte range. More...
 
static Block fromStream (std::istream &is)
 Parse Block from an input stream. More...
 

Protected Attributes

Buffer::const_iterator m_begin
 
shared_ptr< const Bufferm_buffer
 Underlying buffer storing TLV-VALUE and possibly TLV-TYPE and TLV-LENGTH fields. More...
 
element_container m_elements
 Contains the sub-elements. More...
 
Buffer::const_iterator m_end
 
size_t m_size = 0
 Total size including Type-Length-Value. More...
 
uint32_t m_type = tlv::Invalid
 TLV-TYPE. More...
 
Buffer::const_iterator m_valueBegin
 
Buffer::const_iterator m_valueEnd
 

Friends

std::ostream & operator<< (std::ostream &os, const Block &block)
 Print block to os. More...
 
bool operator== (const Block &lhs, const Block &rhs) noexcept
 Compare whether two Blocks have the same TLV-TYPE, TLV-LENGTH, and TLV-VALUE. More...
 

Detailed Description

Represents a TLV element of the NDN packet format.

See also
https://docs.named-data.net/NDN-packet-spec/0.3/tlv.html

Definition at line 44 of file block.hpp.

Member Typedef Documentation

◆ const_iterator

using ndn::Block::const_iterator = Buffer::const_iterator

Definition at line 48 of file block.hpp.

◆ element_const_iterator

using ndn::Block::element_const_iterator = element_container::const_iterator

Definition at line 51 of file block.hpp.

◆ element_container

using ndn::Block::element_container = std::vector<Block>

Definition at line 49 of file block.hpp.

◆ element_iterator

using ndn::Block::element_iterator = element_container::iterator

Definition at line 50 of file block.hpp.

◆ value_type

using ndn::Block::value_type = Buffer::value_type

Definition at line 47 of file block.hpp.

Constructor & Destructor Documentation

◆ Block() [1/12]

ndn::Block::Block ( )
default

Create an invalid Block.

Postcondition
isValid() == false

◆ Block() [2/12]

ndn::Block::Block ( const Block )
default

Copy constructor.

◆ Block() [3/12]

ndn::Block::Block ( Block &&  )
inlinedefaultnoexcept

Move constructor.

◆ Block() [4/12]

ndn::Block::Block ( span< const uint8_t >  buffer)
explicit

Parse Block from a byte range.

Parameters
buffersequence of bytes containing a TLV element; the element must be found at the beginning of the buffer but does not need to span the entire buffer
Exceptions
tlv::ErrorType-Length parsing fails, or TLV-LENGTH exceeds the size of buffer
Note
This constructor copies the TLV element octets to an internal buffer.

Definition at line 54 of file block.cpp.

◆ Block() [5/12]

ndn::Block::Block ( const EncodingBuffer &  buffer)
explicit

Parse Block from an EncodingBuffer.

Parameters
bufferan EncodingBuffer containing one TLV element
Exceptions
tlv::ErrorType-Length parsing fails, or TLV-LENGTH does not match size of TLV-VALUE

Definition at line 78 of file block.cpp.

◆ Block() [6/12]

ndn::Block::Block ( const ConstBufferPtr buffer)
explicit

Parse Block from a wire Buffer.

Parameters
buffera Buffer containing one TLV element
Exceptions
tlv::ErrorType-Length parsing fails, or TLV-LENGTH does not match size of TLV-VALUE
Note
This constructor takes shared ownership of buffer.

Definition at line 83 of file block.cpp.

◆ Block() [7/12]

ndn::Block::Block ( ConstBufferPtr  buffer,
Buffer::const_iterator  begin,
Buffer::const_iterator  end,
bool  verifyLength = true 
)

Parse Block within boundaries of a wire Buffer.

Parameters
buffera Buffer containing a TLV element at [begin,end)
beginbegin position of the TLV element within buffer
endend position of the TLV element within buffer
verifyLengthif true, check TLV-LENGTH equals size of TLV-VALUE
Exceptions
std::invalid_argumentbuffer is empty, or [begin,end) range is not within buffer
tlv::ErrorType-Length parsing fails, or TLV-LENGTH does not match size of TLV-VALUE

Definition at line 88 of file block.cpp.

◆ Block() [8/12]

ndn::Block::Block ( const Block block,
Block::const_iterator  begin,
Block::const_iterator  end,
bool  verifyLength = true 
)

Parse Block within boundaries of an existing Block, reusing underlying wire Buffer.

Parameters
blocka Block whose buffer contains a TLV element at [begin,end)
beginbegin position of the TLV element within block
endend position of the TLV element within block
verifyLengthif true, check TLV-LENGTH equals size of TLV-VALUE
Exceptions
std::invalid_argument[begin,end) range is not within block
tlv::ErrorType-Length parsing fails, or TLV-LENGTH does not match size of TLV-VALUE

Definition at line 117 of file block.cpp.

◆ Block() [9/12]

ndn::Block::Block ( ConstBufferPtr  buffer,
uint32_t  type,
Buffer::const_iterator  begin,
Buffer::const_iterator  end,
Buffer::const_iterator  valueBegin,
Buffer::const_iterator  valueEnd 
)

Create a Block from a wire Buffer without parsing.

Parameters
buffera Buffer containing a TLV element at [begin,end)
typeTLV-TYPE
beginbegin position of the TLV element within buffer
endend position of the TLV element within buffer
valueBeginbegin position of TLV-VALUE within buffer
valueEndend position of TLV-VALUE within buffer

Definition at line 123 of file block.cpp.

◆ Block() [10/12]

ndn::Block::Block ( uint32_t  type)
explicit

Create a zero-length Block with the specified TLV-TYPE.

Parameters
typeTLV-TYPE

Definition at line 136 of file block.cpp.

◆ Block() [11/12]

ndn::Block::Block ( uint32_t  type,
ConstBufferPtr  value 
)

Create a Block with the specified TLV-TYPE and TLV-VALUE.

Parameters
typeTLV-TYPE
valuea Buffer containing the TLV-VALUE, must not be nullptr

Definition at line 142 of file block.cpp.

◆ Block() [12/12]

ndn::Block::Block ( uint32_t  type,
const Block value 
)

Create a Block with the specified TLV-TYPE and TLV-VALUE.

Parameters
typeTLV-TYPE
valuea Block to be nested as TLV-VALUE, must be valid

Definition at line 153 of file block.cpp.

Member Function Documentation

◆ begin()

Block::const_iterator ndn::Block::begin ( ) const

Returns an iterator to the beginning of the encoded wire.

Precondition
hasWire() == true

Definition at line 275 of file block.cpp.

◆ blockFromValue()

Block ndn::Block::blockFromValue ( ) const

Return a new Block constructed from the TLV-VALUE of this Block.

Precondition
value_size() > 0

Definition at line 314 of file block.cpp.

◆ data()

const uint8_t * ndn::Block::data ( ) const

Returns a raw pointer to the beginning of the encoded wire, i.e., the whole TLV.

Precondition
hasWire() == true
See also
value()

Definition at line 256 of file block.cpp.

◆ elements()

const element_container& ndn::Block::elements ( ) const
inlinenoexcept

Get container of sub-elements.

Precondition
parse() has been called.

Definition at line 424 of file block.hpp.

◆ elements_begin()

element_const_iterator ndn::Block::elements_begin ( ) const
inlinenoexcept

Equivalent to elements().begin().

Definition at line 433 of file block.hpp.

◆ elements_end()

element_const_iterator ndn::Block::elements_end ( ) const
inlinenoexcept

Equivalent to elements().end().

Definition at line 442 of file block.hpp.

◆ elements_size()

size_t ndn::Block::elements_size ( ) const
inlinenoexcept

Equivalent to elements().size().

Definition at line 451 of file block.hpp.

◆ encode()

void ndn::Block::encode ( )

Encode sub-elements into TLV-VALUE.

Postcondition
TLV-VALUE contains sub-elements from elements()

Definition at line 353 of file block.cpp.

◆ end()

Block::const_iterator ndn::Block::end ( ) const

Returns an iterator past-the-end of the encoded wire.

Precondition
hasWire() == true

Definition at line 284 of file block.cpp.

◆ erase() [1/2]

Erase a range of sub-elements.

Definition at line 449 of file block.cpp.

◆ erase() [2/2]

Block::element_iterator ndn::Block::erase ( Block::element_const_iterator  position)

Erase a sub-element.

Definition at line 442 of file block.cpp.

◆ find()

Block::element_const_iterator ndn::Block::find ( uint32_t  type) const

Find the first sub-element of the specified TLV-TYPE.

Precondition
parse() has been called
Returns
iterator in elements() to the found sub-element, or elements_end() if no such sub-element exists in elements()

Definition at line 425 of file block.cpp.

◆ fromBuffer() [1/2]

std::tuple< bool, Block > ndn::Block::fromBuffer ( ConstBufferPtr  buffer,
size_t  offset = 0 
)
static

Try to parse Block from a wire buffer.

Parameters
buffera Buffer containing a TLV element at offset offset
offsetbegin position of the TLV element within buffer
Returns
true and the parsed Block if parsing succeeds; otherwise false and an invalid Block
Note
This function does not throw upon decoding failure.

Definition at line 165 of file block.cpp.

◆ fromBuffer() [2/2]

std::tuple< bool, Block > ndn::Block::fromBuffer ( span< const uint8_t >  buffer)
static

Try to parse Block from a byte range.

Parameters
buffersequence of bytes containing a TLV element; the element must be found at the beginning of the buffer but does not need to span the entire buffer
Returns
true and the parsed Block if parsing succeeds; otherwise false and an invalid Block
Note
This overload copies the TLV element octets to an internal buffer.
This function does not throw upon decoding failure.

Definition at line 193 of file block.cpp.

◆ fromStream()

Block ndn::Block::fromStream ( std::istream &  is)
static

Parse Block from an input stream.

Exceptions
tlv::ErrorTLV-LENGTH is zero or exceeds upper bound
Warning
If decoding fails, bytes are still consumed from the input stream.

Definition at line 222 of file block.cpp.

◆ get()

const Block & ndn::Block::get ( uint32_t  type) const

Return the first sub-element of the specified TLV-TYPE.

Precondition
parse() has been called
Exceptions
tlv::Errora sub-element of the specified type does not exist

Definition at line 414 of file block.cpp.

◆ getBuffer()

ConstBufferPtr ndn::Block::getBuffer ( ) const
inline

Returns the underlying buffer.

Definition at line 244 of file block.hpp.

◆ hasValue()

bool ndn::Block::hasValue ( ) const
inlinenoexcept

Check if the Block has a non-empty TLV-VALUE.

This property reflects whether the underlying buffer contains a TLV-VALUE. If this is false, TLV-VALUE has zero-length. If this is true, TLV-VALUE may be zero-length.

See also
value_size()

Definition at line 289 of file block.hpp.

◆ hasWire()

bool ndn::Block::hasWire ( ) const
inlinenoexcept

Check if the Block contains a fully encoded wire representation.

A Block has a fully encoded wire if the underlying buffer exists and contains the full Type-Length-Value instead of just the TLV-VALUE field.

Definition at line 205 of file block.hpp.

◆ insert()

Block::element_iterator ndn::Block::insert ( Block::element_const_iterator  pos,
const Block element 
)

Insert a sub-element.

Parameters
posposition of the new sub-element
elementnew sub-element to insert
Returns
iterator in elements() to the new sub-element

Definition at line 470 of file block.cpp.

◆ isValid()

bool ndn::Block::isValid ( ) const
inlinenoexcept

Check if the Block is valid.

A Block is valid unless it has an invalid TLV-TYPE or is default-constructed. In particular, a Block with zero-length TLV-VALUE is valid.

Definition at line 193 of file block.hpp.

◆ operator boost::asio::const_buffer()

ndn::Block::operator boost::asio::const_buffer ( ) const

Implicit conversion to boost::asio::const_buffer.

Definition at line 478 of file block.cpp.

◆ operator=() [1/2]

Block & ndn::Block::operator= ( Block &&  )
inlinedefaultnoexcept

Move assignment operator.

◆ operator=() [2/2]

Block & ndn::Block::operator= ( const Block )
default

Copy assignment operator.

◆ parse()

void ndn::Block::parse ( ) const

Parse TLV-VALUE into sub-elements.

Postcondition
elements() reflects sub-elements found in TLV-VALUE
Exceptions
tlv::ErrorTLV-VALUE is not a sequence of TLV elements
Note
This method does not perform recursive parsing.
This method has no effect if elements() is already populated.
This method is not really const, but it does not modify any data.

Definition at line 326 of file block.cpp.

◆ push_back() [1/2]

void ndn::Block::push_back ( Block &&  element)

Append a sub-element.

Definition at line 463 of file block.cpp.

◆ push_back() [2/2]

void ndn::Block::push_back ( const Block element)

Append a sub-element.

Definition at line 456 of file block.cpp.

◆ remove()

void ndn::Block::remove ( uint32_t  type)

Remove all sub-elements of the specified TLV-TYPE.

Precondition
parse() has been called
Postcondition
find(type) == elements_end()

Definition at line 432 of file block.cpp.

◆ reset()

void ndn::Block::reset ( )
noexcept

Reset the Block to a default-constructed state.

Equivalent to *this = Block().

Postcondition
isValid() == false
See also
resetWire()

Definition at line 293 of file block.cpp.

◆ resetWire()

void ndn::Block::resetWire ( )
noexcept

Reset wire buffer but keep TLV-TYPE and sub-elements (if any).

Postcondition
hasWire() == false
hasValue() == false
See also
reset()

Definition at line 299 of file block.cpp.

◆ size()

size_t ndn::Block::size ( ) const

Returns the size of the encoded wire, i.e., of the whole TLV.

Precondition
isValid() == true
See also
value_size()

Definition at line 265 of file block.cpp.

◆ type()

uint32_t ndn::Block::type ( ) const
inlinenoexcept

Return the TLV-TYPE of the Block.

Note
This will return tlv::Invalid if isValid() is false.

Definition at line 275 of file block.hpp.

◆ value()

const uint8_t * ndn::Block::value ( ) const
noexcept

Return a raw pointer to the beginning of TLV-VALUE.

See also
value_bytes(), data()

Definition at line 308 of file block.cpp.

◆ value_begin()

const_iterator ndn::Block::value_begin ( ) const
inlinenoexcept

Get begin iterator of TLV-VALUE.

Precondition
hasValue() == true

Definition at line 328 of file block.hpp.

◆ value_bytes()

span<const uint8_t> ndn::Block::value_bytes ( ) const
inlinenoexcept

Return a read-only view of TLV-VALUE as a contiguous range of bytes.

Definition at line 308 of file block.hpp.

◆ value_end()

const_iterator ndn::Block::value_end ( ) const
inlinenoexcept

Get end iterator of TLV-VALUE.

Precondition
hasValue() == true

Definition at line 338 of file block.hpp.

◆ value_size()

size_t ndn::Block::value_size ( ) const
inlinenoexcept

Return the size of TLV-VALUE, i.e., the TLV-LENGTH.

See also
size()

Definition at line 299 of file block.hpp.

Friends And Related Function Documentation

◆ operator<<

std::ostream& operator<< ( std::ostream &  os,
const Block block 
)
friend

Print block to os.

Default-constructed Block is printed as: [invalid]. Zero-length Block is printed as: TT[empty], where TT is TLV-TYPE in decimal. Non-zero-length Block on which parse() has not been called is printed as: TT[LL]=VVVV, where LL is TLV-LENGTH in decimal, and VVVV is TLV-VALUE in hexadecimal. Block on which parse() has been called is printed as: TT[LL]={SUB,SUB}, where each SUB is a sub-element printed using this format.

Definition at line 516 of file block.hpp.

◆ operator==

bool operator== ( const Block lhs,
const Block rhs 
)
friend

Compare whether two Blocks have the same TLV-TYPE, TLV-LENGTH, and TLV-VALUE.

Definition at line 501 of file block.hpp.

Member Data Documentation

◆ m_begin

Buffer::const_iterator ndn::Block::m_begin
protected
See also
m_buffer

Definition at line 533 of file block.hpp.

◆ m_buffer

shared_ptr<const Buffer> ndn::Block::m_buffer
protected

Underlying buffer storing TLV-VALUE and possibly TLV-TYPE and TLV-LENGTH fields.

If m_buffer is nullptr, this is an invalid or zero-length Block with TLV-TYPE given in m_type. Otherwise,

  • [m_valueBegin, m_valueEnd) point to the TLV-VALUE inside m_buffer.
  • If m_begin != m_end, [m_begin, m_end) point to Type-Length-Value of this Block in m_buffer. Otherwise, m_buffer does not contain TLV-TYPE and TLV-LENGTH fields.

Definition at line 532 of file block.hpp.

◆ m_elements

element_container ndn::Block::m_elements
mutableprotected

Contains the sub-elements.

This field is valid only if parse() has been called on the Block instance.

Definition at line 553 of file block.hpp.

◆ m_end

Buffer::const_iterator ndn::Block::m_end
protected
See also
m_buffer

Definition at line 534 of file block.hpp.

◆ m_size

size_t ndn::Block::m_size = 0
protected

Total size including Type-Length-Value.

This field is meaningful only if isValid() is true.

Definition at line 546 of file block.hpp.

◆ m_type

uint32_t ndn::Block::m_type = tlv::Invalid
protected

TLV-TYPE.

Definition at line 539 of file block.hpp.

◆ m_valueBegin

Buffer::const_iterator ndn::Block::m_valueBegin
protected
See also
m_buffer

Definition at line 536 of file block.hpp.

◆ m_valueEnd

Buffer::const_iterator ndn::Block::m_valueEnd
protected
See also
m_buffer

Definition at line 537 of file block.hpp.