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_container &	elements () 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 Block &	get (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...

Block &	operator= (Block &&) noexcept
	Move assignment operator. More...

Block &	operator= (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, Block >	fromBuffer (ConstBufferPtr buffer, size_t offset=0)
	Try to parse Block from a wire buffer. More...

static std::tuple< bool, Block >	fromBuffer (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 Buffer >	m_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

buffer sequence 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::Error Type-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

buffer an EncodingBuffer containing one TLV element

Exceptions

tlv::Error Type-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

buffer a Buffer containing one TLV element

Exceptions

tlv::Error Type-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

buffer	a Buffer containing a TLV element at [`begin`,`end`)
begin	begin position of the TLV element within `buffer`
end	end position of the TLV element within `buffer`
verifyLength	if true, check TLV-LENGTH equals size of TLV-VALUE

Exceptions

std::invalid_argument	`buffer` is empty, or [`begin`,`end`) range is not within `buffer`
tlv::Error	Type-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

block	a Block whose buffer contains a TLV element at [`begin`,`end`)
begin	begin position of the TLV element within `block`
end	end position of the TLV element within `block`
verifyLength	if true, check TLV-LENGTH equals size of TLV-VALUE

Exceptions

std::invalid_argument	[`begin`,`end`) range is not within `block`
tlv::Error	Type-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

buffer	a Buffer containing a TLV element at [`begin`,`end`)
type	TLV-TYPE
begin	begin position of the TLV element within `buffer`
end	end position of the TLV element within `buffer`
valueBegin	begin position of TLV-VALUE within `buffer`
valueEnd	end 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

type TLV-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

type	TLV-TYPE
value	a 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

type	TLV-TYPE
value	a 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]

Block::element_iterator ndn::Block::erase	(	Block::element_const_iterator	first,
		Block::element_const_iterator	last
	)

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

buffer	a Buffer containing a TLV element at offset `offset`
offset	begin 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

buffer sequence 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::Error TLV-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::Error a 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

pos	position of the new sub-element
element	new 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::Error TLV-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.

ndn-cxx: NDN C++ library with eXperimental eXtensions 0.9.0 documentation

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ const_iterator

◆ element_const_iterator

◆ element_container

◆ element_iterator

◆ value_type

Constructor & Destructor Documentation

◆ Block() [1/12]

◆ Block() [2/12]

◆ Block() [3/12]

◆ Block() [4/12]

◆ Block() [5/12]

◆ Block() [6/12]

◆ Block() [7/12]

◆ Block() [8/12]

◆ Block() [9/12]

◆ Block() [10/12]

◆ Block() [11/12]

◆ Block() [12/12]

Member Function Documentation

◆ begin()

◆ blockFromValue()

◆ data()

◆ elements()

◆ elements_begin()

◆ elements_end()

◆ elements_size()

◆ encode()

◆ end()

◆ erase() [1/2]

◆ erase() [2/2]

◆ find()

◆ fromBuffer() [1/2]

◆ fromBuffer() [2/2]

◆ fromStream()

◆ get()

◆ getBuffer()

◆ hasValue()

◆ hasWire()

◆ insert()

◆ isValid()

◆ operator boost::asio::const_buffer()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ parse()

◆ push_back() [1/2]

◆ push_back() [2/2]

◆ remove()

◆ reset()

◆ resetWire()

◆ size()

◆ type()

◆ value()

◆ value_begin()

◆ value_bytes()

◆ value_end()

◆ value_size()

Friends And Related Function Documentation

◆ operator<<

◆ operator==

Member Data Documentation

◆ m_begin

◆ m_buffer

◆ m_elements

◆ m_end

◆ m_size

◆ m_type

◆ m_valueBegin

◆ m_valueEnd