Represents a Data packet. More...

#include <ndn-cxx/data.hpp>

Inheritance diagram for ndn::Data:

Collaboration diagram for ndn::Data:

Classes
class	Error

Public Member Functions
	Data (const Block &wire)
	Construct a Data packet by decoding from `wire`. More...

	Data (const Name &name=Name())
	Construct an unsigned Data packet with given `name` and empty Content. More...

InputBuffers	extractSignedRanges () const
	Extract ranges of Data covered by the signature. More...

uint64_t	getCongestionMark () const
	Get the value of the CongestionMark tag. More...

const Block &	getContent () const noexcept
	Get the `Content` element. More...

uint32_t	getContentType () const noexcept
	Return the value of `ContentType`. More...

const std::optional< name::Component > &	getFinalBlock () const noexcept
	Return the value of `FinalBlockId`. More...

time::milliseconds	getFreshnessPeriod () const noexcept
	Return the value of `FreshnessPeriod`. More...

const Name &	getFullName () const
	Get the full name (including implicit digest). More...

std::optional< KeyLocator >	getKeyLocator () const noexcept
	Get the `KeyLocator` element. More...

const MetaInfo &	getMetaInfo () const noexcept
	Get the `MetaInfo` element. More...

const Name &	getName () const noexcept
	Get the Data name. More...

const SignatureInfo &	getSignatureInfo () const noexcept
	Get the `SignatureInfo` element. More...

int32_t	getSignatureType () const noexcept
	Get the `SignatureType`. More...

const Block &	getSignatureValue () const noexcept
	Get the `SignatureValue` element. More...

template<typename T >
std::shared_ptr< T >	getTag () const
	Get a tag item. More...

bool	hasContent () const noexcept
	Return whether this Data has a `Content` element. More...

bool	hasWire () const noexcept
	Check if this instance has cached wire encoding. More...

template<typename T >
void	removeTag () const
	Remove a tag item. More...

void	setCongestionMark (uint64_t mark)
	Set the CongestionMark tag to the specified value. More...

Data &	setContent (const Block &block)
	Set `Content` from a Block. More...

Data &	setContent (ConstBufferPtr value)
	Set `Content` from a shared buffer. More...

Data &	setContent (span< const uint8_t > value)
	Set `Content` by copying from a contiguous sequence of bytes. More...

Data &	setContent (std::nullptr_t)=delete

Data &	setContent (std::string_view value)
	Set `Content` by copying from a string. More...

Data &	setContentType (uint32_t type)
	Set the `ContentType`. More...

Data &	setFinalBlock (std::optional< name::Component > finalBlockId)
	Set the `FinalBlockId`. More...

Data &	setFreshnessPeriod (time::milliseconds freshnessPeriod)
	Set the `FreshnessPeriod`. More...

Data &	setMetaInfo (const MetaInfo &metaInfo)
	Set the `MetaInfo` element. More...

Data &	setName (const Name &name)
	Set the Data name. More...

Data &	setSignatureInfo (const SignatureInfo &info)
	Set the `SignatureInfo` element. More...

Data &	setSignatureValue (ConstBufferPtr value)
	Set `SignatureValue` from a shared buffer. More...

Data &	setSignatureValue (span< const uint8_t > value)
	Set `SignatureValue` by copying from a contiguous sequence of bytes. More...

Data &	setSignatureValue (std::nullptr_t)=delete

template<typename T >
void	setTag (std::shared_ptr< T > tag) const
	Set (add or replace) a tag item. More...

Data &	unsetContent ()
	Remove the `Content` element. More...

void	wireDecode (const Block &wire)
	Decode from `wire`. More...

const Block &	wireEncode () const
	Encode into a Block. More...

const Block &	wireEncode (EncodingBuffer &encoder, span< const uint8_t > signature) const
	Finalize Data packet encoding with the specified signature. More...

template<encoding::Tag TAG>
size_t	wireEncode (EncodingImpl< TAG > &encoder, bool wantUnsignedPortionOnly=false) const
	Prepend wire encoding to `encoder`. More...

Protected Member Functions
void	resetWire ()
	Clear wire encoding and cached FullName. More...

Detailed Description

Represents a Data packet.

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

Definition at line 38 of file data.hpp.

Constructor & Destructor Documentation

◆ Data() [1/2]

ndn::Data::Data ( const Name & name = Name() )

explicit

Construct an unsigned Data packet with given name and empty Content.

Warning: In certain contexts that use Data::shared_from_this(), the Data must be created using std::make_shared. Otherwise, shared_from_this() will throw std::bad_weak_ptr. One example where this is necessary is storing Data into a subclass of InMemoryStorage.

Definition at line 27 of file data.cpp.

◆ Data() [2/2]

ndn::Data::Data ( const Block & wire )

explicit

Construct a Data packet by decoding from wire.

Parameters

wire	TLV element of type tlv::Data; may be signed or unsigned.

Warning: In certain contexts that use Data::shared_from_this(), the Data must be created using std::make_shared. Otherwise, shared_from_this() will throw std::bad_weak_ptr. One example where this is necessary is storing Data into a subclass of InMemoryStorage.

Definition at line 32 of file data.cpp.

Member Function Documentation

◆ extractSignedRanges()

InputBuffers ndn::Data::extractSignedRanges ( ) const

Extract ranges of Data covered by the signature.

Exceptions

Error Data cannot be encoded or is missing ranges necessary for signing

Warning: The returned pointers will be invalidated if wireDecode() or wireEncode() are called.

Definition at line 323 of file data.cpp.

◆ getCongestionMark()

uint64_t ndn::PacketBase::getCongestionMark ( ) const

inherited

Get the value of the CongestionMark tag.

Definition at line 28 of file packet-base.cpp.

◆ getContent()

const Block& ndn::Data::getContent ( ) const

inlinenoexcept

Get the Content element.

If the element is not present (hasContent() == false), an invalid Block will be returned.

The value of the returned Content Block (if valid) can be accessed through

Block::value_bytes(), or
Block::value() and Block::value_size(), or
Block::value_begin() and Block::value_end().

See also: hasContent(); Block::value_bytes(), Block::blockFromValue(), Block::parse()

Definition at line 188 of file data.hpp.

◆ getContentType()

uint32_t ndn::Data::getContentType ( ) const

inlinenoexcept

Return the value of ContentType.

If the ContentType element is not present, returns tlv::ContentType_Blob.

Definition at line 312 of file data.hpp.

◆ getFinalBlock()

const std::optional<name::Component>& ndn::Data::getFinalBlock ( ) const

inlinenoexcept

Return the value of FinalBlockId.

Definition at line 342 of file data.hpp.

◆ getFreshnessPeriod()

time::milliseconds ndn::Data::getFreshnessPeriod ( ) const

inlinenoexcept

Return the value of FreshnessPeriod.

If the FreshnessPeriod element is not present, returns DEFAULT_FRESHNESS_PERIOD. If the FreshnessPeriod value is not representable in the return type, it's clamped to the nearest representable value.

Definition at line 327 of file data.hpp.

◆ getFullName()

const Name & ndn::Data::getFullName ( ) const

Get the full name (including implicit digest).

Precondition: hasWire() == true, i.e., wireEncode() must have been called.

Exceptions

Error Data has no wire encoding

Definition at line 200 of file data.cpp.

◆ getKeyLocator()

std::optional<KeyLocator> ndn::Data::getKeyLocator ( ) const

inlinenoexcept

Get the KeyLocator element.

Definition at line 367 of file data.hpp.

◆ getMetaInfo()

const MetaInfo& ndn::Data::getMetaInfo ( ) const

inlinenoexcept

Get the MetaInfo element.

Definition at line 153 of file data.hpp.

◆ getName()

const Name& ndn::Data::getName ( ) const

inlinenoexcept

Get the Data name.

Definition at line 137 of file data.hpp.

◆ getSignatureInfo()

const SignatureInfo& ndn::Data::getSignatureInfo ( ) const

inlinenoexcept

Get the SignatureInfo element.

Definition at line 243 of file data.hpp.

◆ getSignatureType()

int32_t ndn::Data::getSignatureType ( ) const

inlinenoexcept

Get the SignatureType.

Returns: tlv::SignatureTypeValue, or -1 to indicate an invalid SignatureInfo.

Definition at line 358 of file data.hpp.

◆ getSignatureValue()

const Block& ndn::Data::getSignatureValue ( ) const

inlinenoexcept

Get the SignatureValue element.

Definition at line 265 of file data.hpp.

◆ getTag()

template<typename T >

std::shared_ptr< T > ndn::TagHost::getTag

inherited

Get a tag item.

Template Parameters

T	type of the tag, which must be a subclass of ndn::Tag

Return values

nullptr if no Tag of type T is stored

Definition at line 72 of file tag-host.hpp.

◆ hasContent()

bool ndn::Data::hasContent ( ) const

inlinenoexcept

Return whether this Data has a Content element.

Definition at line 169 of file data.hpp.

◆ hasWire()

bool ndn::Data::hasWire ( ) const

inlinenoexcept

Check if this instance has cached wire encoding.

Definition at line 119 of file data.hpp.

◆ removeTag()

template<typename T >

void ndn::TagHost::removeTag

inherited

Remove a tag item.

Template Parameters

T	type of the tag, which must be a subclass of ndn::Tag

Note: Tag can be removed even on a const tag host instance

Definition at line 98 of file tag-host.hpp.

◆ resetWire()

void ndn::Data::resetWire ( )

protected

Clear wire encoding and cached FullName.

Note: This does not clear the SignatureValue.

Definition at line 214 of file data.cpp.

◆ setCongestionMark()

void ndn::PacketBase::setCongestionMark ( uint64_t mark )

inherited

Set the CongestionMark tag to the specified value.

Definition at line 41 of file packet-base.cpp.

◆ setContent() [1/5]

Data & ndn::Data::setContent ( const Block & block )

Set Content from a Block.

Parameters

block TLV element to be used as Content; must be valid

Returns: A reference to this Data, to allow chaining.

If the block's TLV-TYPE is tlv::Content, it will be used directly as this Data's Content element. Otherwise, the block will be nested into a Content element.

Definition at line 239 of file data.cpp.

◆ setContent() [2/5]

Data & ndn::Data::setContent ( ConstBufferPtr value )

Set Content from a shared buffer.

Parameters

value buffer with the TLV-VALUE of the content; must not be null

Returns: A reference to this Data, to allow chaining.

Definition at line 273 of file data.cpp.

◆ setContent() [3/5]

Data & ndn::Data::setContent ( span< const uint8_t > value )

Set Content by copying from a contiguous sequence of bytes.

Parameters

value buffer with the TLV-VALUE of the content

Returns: A reference to this Data, to allow chaining.

Definition at line 257 of file data.cpp.

◆ setContent() [4/5]

Data& ndn::Data::setContent ( std::nullptr_t )

delete

◆ setContent() [5/5]

Data & ndn::Data::setContent ( std::string_view value )

Set Content by copying from a string.

Parameters

value string with the TLV-VALUE of the content

Returns: A reference to this Data, to allow chaining.

Definition at line 265 of file data.cpp.

◆ setContentType()

Data & ndn::Data::setContentType ( uint32_t type )

Set the ContentType.

Parameters

type	A number defined in tlv::ContentTypeValue

Definition at line 337 of file data.cpp.

◆ setFinalBlock()

Data & ndn::Data::setFinalBlock ( std::optional< name::Component > finalBlockId )

Set the FinalBlockId.

Definition at line 357 of file data.cpp.

◆ setFreshnessPeriod()

Data & ndn::Data::setFreshnessPeriod ( time::milliseconds freshnessPeriod )

Set the FreshnessPeriod.

Exceptions

std::invalid_argument specified FreshnessPeriod is negative.

Definition at line 347 of file data.cpp.

◆ setMetaInfo()

Data & ndn::Data::setMetaInfo ( const MetaInfo & metaInfo )

Set the MetaInfo element.

Returns: A reference to this Data, to allow chaining.

Definition at line 231 of file data.cpp.

◆ setName()

Data & ndn::Data::setName ( const Name & name )

Set the Data name.

Returns: A reference to this Data, to allow chaining.

Definition at line 221 of file data.cpp.

◆ setSignatureInfo()

Data & ndn::Data::setSignatureInfo ( const SignatureInfo & info )

Set the SignatureInfo element.

This is a low-level function that should not normally be called directly by applications. Instead, provide a SignatureInfo to the SigningInfo object passed to KeyChain::sign().

Returns: A reference to this Data, to allow chaining.

Warning: SignatureInfo is overwritten when the packet is signed via KeyChain::sign().

See also: SigningInfo

Definition at line 295 of file data.cpp.

◆ setSignatureValue() [1/3]

Data & ndn::Data::setSignatureValue ( ConstBufferPtr value )

Set SignatureValue from a shared buffer.

Parameters

value buffer containing the TLV-VALUE of the SignatureValue; must not be null

Returns: A reference to this Data, to allow chaining.

This is a low-level function that should not normally be called directly by applications. Instead, use KeyChain::sign() to sign the packet.

Warning: SignatureValue is overwritten when the packet is signed via KeyChain::sign().

Definition at line 311 of file data.cpp.

◆ setSignatureValue() [2/3]

Data & ndn::Data::setSignatureValue ( span< const uint8_t > value )

Set SignatureValue by copying from a contiguous sequence of bytes.

Parameters

value buffer from which the TLV-VALUE of the SignatureValue will be copied

Returns: A reference to this Data, to allow chaining.

This is a low-level function that should not normally be called directly by applications. Instead, use KeyChain::sign() to sign the packet.

Warning: SignatureValue is overwritten when the packet is signed via KeyChain::sign().

Definition at line 303 of file data.cpp.

◆ setSignatureValue() [3/3]

Data& ndn::Data::setSignatureValue ( std::nullptr_t )

delete

◆ setTag()

template<typename T >

void ndn::TagHost::setTag ( std::shared_ptr< T > tag ) const

inherited

Set (add or replace) a tag item.

Template Parameters

T	type of the tag, which must be a subclass of ndn::Tag

Note: Tag can be set even on a const tag host instance

Definition at line 84 of file tag-host.hpp.

◆ unsetContent()

Data & ndn::Data::unsetContent ( )

Remove the Content element.

Returns: A reference to this Data, to allow chaining.

Postcondition: hasContent() == false

Definition at line 285 of file data.cpp.

◆ wireDecode()

void ndn::Data::wireDecode ( const Block & wire )

Decode from wire.

Definition at line 118 of file data.cpp.

◆ wireEncode() [1/3]

const Block & ndn::Data::wireEncode ( ) const

Encode into a Block.

Precondition: Data must be signed.

Definition at line 102 of file data.cpp.

◆ wireEncode() [2/3]

const Block & ndn::Data::wireEncode	(	EncodingBuffer &	encoder,
		span< const uint8_t >	signature
	)		const

Finalize Data packet encoding with the specified signature.

Parameters

encoder	EncodingBuffer containing Name, MetaInfo, Content, and SignatureInfo, but without SignatureValue and the outermost Type-Length of the Data element.
signature	Raw signature bytes, without TLV Type and Length; this will become the TLV-VALUE of the SignatureValue element added to the packet.

This method is intended to be used in concert with wireEncode(encoder, true), e.g.:

Data data;
...
EncodingBuffer encoder;
data.wireEncode(encoder, true);
...
auto signature = create_signature_over_signed_portion(encoder.data(), encoder.size());
data.wireEncode(encoder, signature);

Definition at line 87 of file data.cpp.

◆ wireEncode() [3/3]

template<encoding::Tag TAG>

size_t ndn::Data::wireEncode	(	EncodingImpl< TAG > &	encoder,
		bool	wantUnsignedPortionOnly = `false`
	)		const

Prepend wire encoding to encoder.

Parameters

encoder	EncodingEstimator or EncodingBuffer instance.
wantUnsignedPortionOnly	If true, prepend only Name, MetaInfo, Content, and SignatureInfo to `encoder`, but omit SignatureValue and the outermost TLV Type and Length of the Data element. This is intended to be used with wireEncode(EncodingBuffer&, span<const uint8_t>) const.

Exceptions

Error Signature is not present and wantUnsignedPortionOnly is false.

Definition at line 39 of file data.cpp.

ndn-cxx: NDN C++ library with eXperimental eXtensions 0.8.1-102-g0751bba8 documentation

Classes

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Data() [1/2]

◆ Data() [2/2]

Member Function Documentation

◆ extractSignedRanges()

◆ getCongestionMark()

◆ getContent()

◆ getContentType()

◆ getFinalBlock()

◆ getFreshnessPeriod()

◆ getFullName()

◆ getKeyLocator()

◆ getMetaInfo()

◆ getName()

◆ getSignatureInfo()

◆ getSignatureType()

◆ getSignatureValue()

◆ getTag()

◆ hasContent()

◆ hasWire()

◆ removeTag()

◆ resetWire()

◆ setCongestionMark()

◆ setContent() [1/5]

◆ setContent() [2/5]

◆ setContent() [3/5]

◆ setContent() [4/5]

◆ setContent() [5/5]

◆ setContentType()

◆ setFinalBlock()

◆ setFreshnessPeriod()

◆ setMetaInfo()

◆ setName()

◆ setSignatureInfo()

◆ setSignatureValue() [1/3]

◆ setSignatureValue() [2/3]

◆ setSignatureValue() [3/3]

◆ setTag()

◆ unsetContent()

◆ wireDecode()

◆ wireEncode() [1/3]

◆ wireEncode() [2/3]

◆ wireEncode() [3/3]