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	element_const_iterator = element_container::const_iterator

using	element_container = std::vector< Block >

using	element_iterator = element_container::iterator

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, Buffer::const_iterator begin, Buffer::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 (const uint8_t *buf, size_t bufSize)
	Parse Block from a raw buffer. 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...

Buffer::const_iterator	begin () const
	Get begin iterator of encoded wire. More...

Block	blockFromValue () const

const element_container &	elements () const
	Get container of sub-elements. More...

element_const_iterator	elements_begin () const
	Equivalent to elements().begin() More...

element_const_iterator	elements_end () const
	Equivalent to elements().end() More...

size_t	elements_size () const
	Equivalent to elements().size() More...

void	encode ()
	Encode sub-elements into TLV-VALUE. More...

Buffer::const_iterator	end () const
	Get end iterator of 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
	Get 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 (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
	Return the size of the encoded wire, i.e. More...

uint32_t	type () const
	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...

Buffer::const_iterator	value_begin () const
	Get begin iterator of TLV-VALUE. More...

Buffer::const_iterator	value_end () const
	Get end iterator of TLV-VALUE. More...

size_t	value_size () const noexcept
	Return the size of TLV-VALUE, aka TLV-LENGTH. More...

const uint8_t *	wire () const
	Return a raw pointer to the beginning of the encoded wire. More...

Static Public Member Functions
static std::tuple< bool, Block >	fromBuffer (const uint8_t *buf, size_t bufSize)
	Try to parse Block from a raw buffer. More...

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...

Detailed Description

Represents a TLV element of the NDN packet format.

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

Definition at line 44 of file block.hpp.

Member Typedef Documentation

◆ element_const_iterator

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

Definition at line 49 of file block.hpp.

◆ element_container

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

Definition at line 47 of file block.hpp.

◆ element_iterator

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

Definition at line 48 of file block.hpp.

Constructor & Destructor Documentation

◆ Block() [1/13]

ndn::Block::Block ( )

default

Create an invalid Block.

Postcondition: isValid() == false

◆ Block() [2/13]

ndn::Block::Block ( const Block & )

default

Copy constructor.

◆ Block() [3/13]

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

inlinedefaultnoexcept

Move constructor.

◆ Block() [4/13]

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 51 of file block.cpp.

◆ Block() [5/13]

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 75 of file block.cpp.

◆ Block() [6/13]

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 80 of file block.cpp.

◆ Block() [7/13]

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 85 of file block.cpp.

◆ Block() [8/13]

ndn::Block::Block	(	const Block &	block,
		Buffer::const_iterator	begin,
		Buffer::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 114 of file block.cpp.

◆ Block() [9/13]

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 120 of file block.cpp.

◆ Block() [10/13]

ndn::Block::Block	(	const uint8_t *	buf,
		size_t	bufSize
	)

Parse Block from a raw buffer.

Parameters

buf	pointer to the first octet of a TLV element
bufSize	size of the raw buffer; may be greater than the actual size of the TLV element

Exceptions

tlv::Error Type-Length parsing fails, or size of TLV-VALUE exceeds bufSize

Note: This constructor copies the TLV element octets to an internal buffer.

Deprecated:

Definition at line 133 of file block.cpp.

◆ Block() [11/13]

ndn::Block::Block ( uint32_t type )

explicit

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

Parameters

type TLV-TYPE

Definition at line 138 of file block.cpp.

◆ Block() [12/13]

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 144 of file block.cpp.

◆ Block() [13/13]

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 155 of file block.cpp.

Member Function Documentation

◆ begin()

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

Get begin iterator of encoded wire.

Precondition: hasWire() == true

Definition at line 278 of file block.cpp.

◆ blockFromValue()

Block ndn::Block::blockFromValue ( ) const

Definition at line 329 of file block.cpp.

◆ elements()

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

inline

Get container of sub-elements.

Precondition: parse() has been executed

Definition at line 402 of file block.hpp.

◆ elements_begin()

element_const_iterator ndn::Block::elements_begin ( ) const

inline

Equivalent to elements().begin()

Definition at line 410 of file block.hpp.

◆ elements_end()

element_const_iterator ndn::Block::elements_end ( ) const

inline

Equivalent to elements().end()

Definition at line 418 of file block.hpp.

◆ elements_size()

size_t ndn::Block::elements_size ( ) const

inline

Equivalent to elements().size()

Definition at line 426 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 368 of file block.cpp.

◆ end()

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

Get end iterator of encoded wire.

Precondition: hasWire() == true

Definition at line 287 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 465 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 458 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 executed

Returns: iterator in elements() to the found sub-element, or elements_end() if no such sub-element exists in elements()

Definition at line 441 of file block.cpp.

◆ fromBuffer() [1/3]

std::tuple< bool, Block > ndn::Block::fromBuffer	(	const uint8_t *	buf,
		size_t	bufSize
	)

static

Try to parse Block from a raw buffer.

Parameters

buf	pointer to the first octet of a TLV element
bufSize	size of the raw buffer; may be greater than the actual size of the TLV element

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.

Deprecated:

Definition at line 225 of file block.cpp.

◆ fromBuffer() [2/3]

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 167 of file block.cpp.

◆ fromBuffer() [3/3]

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 195 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 231 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 executed

Exceptions

tlv::Error a sub-element of the specified type does not exist

Definition at line 429 of file block.cpp.

◆ getBuffer()

ConstBufferPtr ndn::Block::getBuffer ( ) const

inline

Get underlying buffer.

Definition at line 275 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 298 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 241 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 479 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 212 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 487 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 341 of file block.cpp.

◆ push_back()

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

Append a sub-element.

Definition at line 472 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 executed

Postcondition: find(type) == elements_end()

Definition at line 448 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 265 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 271 of file block.cpp.

◆ size()

size_t ndn::Block::size ( ) const

Return the size of the encoded wire, i.e.

of the whole TLV

Precondition: isValid() == true

See also: value_size()

Definition at line 305 of file block.cpp.

◆ type()

uint32_t ndn::Block::type ( ) const

inline

Return the TLV-TYPE of the Block.

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

Definition at line 285 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: wire()

Definition at line 317 of file block.cpp.

◆ value_begin()

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

inline

Get begin iterator of TLV-VALUE.

Precondition: hasValue() == true

Definition at line 307 of file block.hpp.

◆ value_end()

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

inline

Get end iterator of TLV-VALUE.

Precondition: hasValue() == true

Definition at line 316 of file block.hpp.

◆ value_size()

size_t ndn::Block::value_size ( ) const

noexcept

Return the size of TLV-VALUE, aka TLV-LENGTH.

See also: size()

Definition at line 323 of file block.cpp.

◆ wire()

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

Return a raw pointer to the beginning of the encoded wire.

Precondition: hasWire() == true

See also: value()

Definition at line 296 of file block.cpp.

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 501 of file block.cpp.

Member Data Documentation

◆ m_begin

Buffer::const_iterator ndn::Block::m_begin

protected

See also: m_buffer

Definition at line 464 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 463 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 executed.

Definition at line 482 of file block.hpp.

◆ m_end

Buffer::const_iterator ndn::Block::m_end

protected

See also: m_buffer

Definition at line 465 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 476 of file block.hpp.

◆ m_type

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

protected

TLV-TYPE.

Definition at line 470 of file block.hpp.

◆ m_valueBegin

Buffer::const_iterator ndn::Block::m_valueBegin

protected

See also: m_buffer

Definition at line 467 of file block.hpp.

◆ m_valueEnd

Buffer::const_iterator ndn::Block::m_valueEnd

protected

See also: m_buffer

Definition at line 468 of file block.hpp.

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

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ element_const_iterator

◆ element_container

◆ element_iterator

Constructor & Destructor Documentation

◆ Block() [1/13]

◆ Block() [2/13]

◆ Block() [3/13]

◆ Block() [4/13]

◆ Block() [5/13]

◆ Block() [6/13]

◆ Block() [7/13]

◆ Block() [8/13]

◆ Block() [9/13]

◆ Block() [10/13]

◆ Block() [11/13]

◆ Block() [12/13]

◆ Block() [13/13]

Member Function Documentation

◆ begin()

◆ blockFromValue()

◆ elements()

◆ elements_begin()

◆ elements_end()

◆ elements_size()

◆ encode()

◆ end()

◆ erase() [1/2]

◆ erase() [2/2]

◆ find()

◆ fromBuffer() [1/3]

◆ fromBuffer() [2/3]

◆ fromBuffer() [3/3]

◆ fromStream()

◆ get()

◆ getBuffer()

◆ hasValue()

◆ hasWire()

◆ insert()

◆ isValid()

◆ operator boost::asio::const_buffer()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ parse()

◆ push_back()

◆ remove()

◆ reset()

◆ resetWire()

◆ size()

◆ type()

◆ value()

◆ value_begin()

◆ value_end()

◆ value_size()

◆ wire()

Friends And Related Function Documentation

◆ operator<<

Member Data Documentation

◆ m_begin

◆ m_buffer

◆ m_elements

◆ m_end

◆ m_size

◆ m_type

◆ m_valueBegin

◆ m_valueEnd