Represents a Data packet. More...

#include <data.hpp>

Inheritance diagram for ndn::Data:

[legend]

Collaboration diagram for ndn::Data:

Classes
class	Error

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

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

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

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

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

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

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

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

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

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

const MetaInfo &	getMetaInfo () const noexcept
	Get MetaInfo. More...

Data &	setMetaInfo (const MetaInfo &metaInfo)
	Set MetaInfo. More...

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

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

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

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

Data &	setContent (const uint8_t *value, size_t length)
	Set Content by copying from a raw buffer. More...

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

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

const SignatureInfo &	getSignatureInfo () const noexcept
	Get SignatureInfo. More...

Data &	setSignatureInfo (const SignatureInfo &info)
	Set SignatureInfo. More...

const Block &	getSignatureValue () const noexcept
	Get SignatureValue. More...

Data &	setSignatureValue (ConstBufferPtr value)
	Set SignatureValue. More...

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

uint32_t	getContentType () const

Data &	setContentType (uint32_t type)

time::milliseconds	getFreshnessPeriod () const

Data &	setFreshnessPeriod (time::milliseconds freshnessPeriod)

const optional< name::Component > &	getFinalBlock () const

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

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

optional< KeyLocator >	getKeyLocator () const noexcept
	Get KeyLocator. More...

Public Member Functions inherited from ndn::PacketBase
uint64_t	getCongestionMark () const
	get the value of the CongestionMark tag More...

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

Public Member Functions inherited from ndn::TagHost
template<typename T >
shared_ptr< T >	getTag () const
	get a tag item More...

template<typename T >
void	setTag (shared_ptr< T > tag) const
	set a tag item More...

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

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

Detailed Description

Represents a Data packet.

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

Definition at line 37 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(), Data must be created using std::make_shared. Otherwise, shared_from_this() may trigger undefined behavior. One example where this is necessary is storing Data into a subclass of InMemoryStorage.

Definition at line 34 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 block of type tlv::Data; may be signed or unsigned.

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

Definition at line 39 of file data.cpp.

References wireDecode().

Member Function Documentation

◆ wireEncode() [1/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 46 of file data.cpp.

References ndn::SignatureInfo::Data, ndn::tlv::Data, hasContent(), NDN_THROW, ndn::encoding::prependBlock(), ndn::MetaInfo::wireEncode(), ndn::SignatureInfo::wireEncode(), and ndn::Name::wireEncode().

Referenced by ndn::Face::Impl::putData(), ndn::util::DummyClientFace::receive(), ndn::security::v2::KeyChain::sign(), and ndn::security::SafeBag::wireEncode().

◆ 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 94 of file data.cpp.

References ndn::tlv::Data, ndn::tlv::SignatureValue, ndn::Block::size(), and wireDecode().

◆ wireEncode() [3/3]

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

Encode into a Block.

Precondition: Data must be signed.

Definition at line 109 of file data.cpp.

References ndn::Block::hasWire(), and wireDecode().

Referenced by extractSignedRanges().

◆ wireDecode()

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

Decode from wire.

Definition at line 125 of file data.cpp.

References ndn::Name::clear(), ndn::tlv::Content, ndn::tlv::Data, ndn::Block::elements_begin(), ndn::Block::elements_end(), ndn::tlv::isCriticalType(), ndn::Block::isValid(), ndn::tlv::MetaInfo, ndn::tlv::Name, NDN_THROW, ndn::Block::parse(), ndn::tlv::SignatureInfo, ndn::tlv::SignatureValue, ndn::to_string(), ndn::Block::type(), ndn::MetaInfo::wireDecode(), ndn::SignatureInfo::wireDecode(), and ndn::Name::wireDecode().

Referenced by Data(), ndn::Link::wireDecode(), ndn::security::SafeBag::wireDecode(), and wireEncode().

◆ hasWire()

bool ndn::Data::hasWire ( ) const

inlinenoexcept

Check if this instance has cached wire encoding.

Definition at line 111 of file data.hpp.

References getFullName().

◆ getFullName()

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

Get 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 207 of file data.cpp.

References ndn::Name::appendImplicitSha256Digest(), ndn::util::Sha256::computeDigest(), ndn::Name::empty(), ndn::Block::hasWire(), and NDN_THROW.

Referenced by nfd::cs::compareDataWithData(), nfd::cs::compareQueryWithData(), hasWire(), ndn::InMemoryStorage::insert(), and ndn::Interest::matchesData().

◆ getName()

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

inlinenoexcept

Get name.

Definition at line 127 of file data.hpp.

References setName().

◆ setName()

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

Set name.

Returns: a reference to this Data, to allow chaining

Definition at line 228 of file data.cpp.

References resetWire().

Referenced by getName(), and ndn::security::v2::parseLocatorUri().

◆ getMetaInfo()

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

inlinenoexcept

Get MetaInfo.

Definition at line 141 of file data.hpp.

References setMetaInfo().

Referenced by ndn::operator<<(), and ndn::operator==().

◆ setMetaInfo()

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

Set MetaInfo.

Returns: a reference to this Data, to allow chaining

Definition at line 238 of file data.cpp.

References resetWire().

Referenced by getMetaInfo().

◆ hasContent()

bool ndn::Data::hasContent ( ) const

inlinenoexcept

Return whether this Data has a Content element.

Definition at line 156 of file data.hpp.

Referenced by ndn::operator<<(), and wireEncode().

◆ 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 175 of file data.hpp.

References setContent(), and unsetContent().

Referenced by ndn::security::v2::KeyChain::addCertificate(), ndn::security::v2::Certificate::Certificate(), ndn::security::v2::CertificateBundleFetcher::doFetch(), ndn::security::v2::Certificate::getPublicKey(), ndn::security::v2::KeyChain::makeCertificate(), ndn::MetadataObject::MetadataObject(), ndn::security::v2::operator<<(), ndn::operator<<(), ndn::operator==(), ndn::util::SegmentFetcher::stop(), ndn::Link::wireDecode(), and ndn::nfd::Controller::~Controller().

◆ setContent() [1/4]

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

Set Content from a Block.

Parameters

block TLV block 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 246 of file data.cpp.

References ndn::tlv::Content, ndn::Block::encode(), ndn::Block::isValid(), NDN_THROW, resetWire(), and ndn::Block::type().

Referenced by getContent(), ndn::Link::Link(), ndn::MetadataObject::makeData(), ndn::security::v2::parseLocatorUri(), and setContent().

◆ setContent() [2/4]

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 264 of file data.cpp.

References ndn::tlv::Content, ndn::encoding::makeBinaryBlock(), and resetWire().

◆ setContent() [3/4]

Data & ndn::Data::setContent	(	const uint8_t *	value,
		size_t	length
	)

Set Content by copying from a raw buffer.

Parameters

value	buffer with the TLV-VALUE of the content; may be nullptr if `length` is zero
length	size of the buffer

Returns: a reference to this Data, to allow chaining

Deprecated:: Use setContent(span<const uint8_t>)

Definition at line 272 of file data.cpp.

References NDN_THROW, and setContent().

◆ setContent() [4/4]

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 nullptr

Returns: a reference to this Data, to allow chaining

Definition at line 282 of file data.cpp.

References ndn::tlv::Content, nonstd::optional_lite::std11::move(), NDN_THROW, and resetWire().

◆ unsetContent()

Data & ndn::Data::unsetContent ( )

Remove the Content element.

Returns: a reference to this Data, to allow chaining

Postcondition: hasContent() == false

Definition at line 294 of file data.cpp.

References resetWire().

Referenced by getContent().

◆ getSignatureInfo()

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

inlinenoexcept

Get SignatureInfo.

Definition at line 229 of file data.hpp.

References info, and setSignatureInfo().

Referenced by ndn::security::v2::Certificate::getExtension(), ndn::security::v2::getKeyLocatorName(), ndn::security::v2::Certificate::getValidityPeriod(), ndn::security::v2::Certificate::isValid(), ndn::security::v2::operator<<(), ndn::operator==(), and ndn::security::parse().

◆ setSignatureInfo()

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

Set SignatureInfo.

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