ndn::Data Class Reference

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 BlockgetContent () const noexcept
 Get the Content element. More...
 
uint32_t getContentType () const
 
const optional< name::Component > & getFinalBlock () const
 
time::milliseconds getFreshnessPeriod () const
 
const NamegetFullName () const
 Get full name including implicit digest. More...
 
optional< KeyLocatorgetKeyLocator () const noexcept
 Get the KeyLocator element. More...
 
const MetaInfogetMetaInfo () const noexcept
 Get the MetaInfo element. More...
 
const NamegetName () const noexcept
 Get the data name. More...
 
const SignatureInfogetSignatureInfo () const noexcept
 Get the SignatureInfo element. More...
 
int32_t getSignatureType () const noexcept
 Get the SignatureType. More...
 
const BlockgetSignatureValue () const noexcept
 Get the SignatureValue element. More...
 
template<typename T >
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...
 
DatasetContent (const Block &block)
 Set Content from a Block. More...
 
DatasetContent (ConstBufferPtr value)
 Set Content from a shared buffer. More...
 
DatasetContent (span< const uint8_t > value)
 Set Content by copying from a contiguous sequence of bytes. More...
 
DatasetContentType (uint32_t type)
 
DatasetFinalBlock (optional< name::Component > finalBlockId)
 
DatasetFreshnessPeriod (time::milliseconds freshnessPeriod)
 
DatasetMetaInfo (const MetaInfo &metaInfo)
 Set the MetaInfo element. More...
 
DatasetName (const Name &name)
 Set the data name. More...
 
DatasetSignatureInfo (const SignatureInfo &info)
 Set the SignatureInfo element. More...
 
DatasetSignatureValue (ConstBufferPtr value)
 Set SignatureValue from a shared buffer. More...
 
DatasetSignatureValue (span< const uint8_t > value)
 Set SignatureValue by copying from a contiguous sequence of bytes. More...
 
template<typename T >
void setTag (shared_ptr< T > tag) const
 Set (add or replace) a tag item. More...
 
DataunsetContent ()
 Remove the Content element. More...
 
void wireDecode (const Block &wire)
 Decode from wire. More...
 
const BlockwireEncode () const
 Encode into a Block. More...
 
const BlockwireEncode (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://named-data.net/doc/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(), 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
wireTLV 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.

Member Function Documentation

◆ extractSignedRanges()

InputBuffers ndn::Data::extractSignedRanges ( ) const

Extract ranges of Data covered by the signature.

Exceptions
ErrorData 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 320 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

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

Definition at line 180 of file data.hpp.

◆ getContentType()

uint32_t ndn::Data::getContentType ( ) const
inline

Definition at line 285 of file data.hpp.

◆ getFinalBlock()

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

Definition at line 303 of file data.hpp.

◆ getFreshnessPeriod()

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

Definition at line 294 of file data.hpp.

◆ getFullName()

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

Get full name including implicit digest.

Precondition
hasWire() == true; i.e. wireEncode() must have been called
Exceptions
ErrorData has no wire encoding

Definition at line 207 of file data.cpp.

◆ getKeyLocator()

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

Get the KeyLocator element.

Definition at line 326 of file data.hpp.

◆ getMetaInfo()

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

Get the MetaInfo element.

Definition at line 145 of file data.hpp.

◆ getName()

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

Get the data name.

Definition at line 129 of file data.hpp.

◆ getSignatureInfo()

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

Get the SignatureInfo element.

Definition at line 224 of file data.hpp.

◆ getSignatureType()

int32_t ndn::Data::getSignatureType ( ) const
inlinenoexcept

Get the SignatureType.

Returns
tlv::SignatureTypeValue, or -1 to indicate the signature is invalid.

Definition at line 317 of file data.hpp.

◆ getSignatureValue()

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

Get the SignatureValue element.

Definition at line 245 of file data.hpp.

◆ getTag()

template<typename T >
shared_ptr< T > ndn::TagHost::getTag
inherited

Get a tag item.

Template Parameters
Ttype of the tag, which must be a subclass of ndn::Tag
Return values
nullptrif no Tag of type T is stored

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

◆ hasContent()

bool ndn::Data::hasContent ( ) const
inlinenoexcept

Return whether this Data has a Content element.

Definition at line 161 of file data.hpp.

◆ hasWire()

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

Check if this instance has cached wire encoding.

Definition at line 112 of file data.hpp.

◆ removeTag()

template<typename T >
void ndn::TagHost::removeTag
inherited

Remove a tag item.

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

Definition at line 94 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 221 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/3]

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

Set Content from a Block.

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

◆ setContent() [2/3]

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

Set Content from a shared buffer.

Parameters
valuebuffer with the TLV-VALUE of the content; must not be nullptr
Returns
A reference to this Data, to allow chaining.

Definition at line 272 of file data.cpp.

◆ setContent() [3/3]

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

Set Content by copying from a contiguous sequence of bytes.

Parameters
valuebuffer with the TLV-VALUE of the content
Returns
A reference to this Data, to allow chaining.

Definition at line 264 of file data.cpp.

◆ setContentType()

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

Definition at line 334 of file data.cpp.

◆ setFinalBlock()

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

Definition at line 354 of file data.cpp.

◆ setFreshnessPeriod()

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

Definition at line 344 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 238 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 228 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 292 of file data.cpp.

◆ setSignatureValue() [1/2]

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

Set SignatureValue from a shared buffer.

Parameters
valuebuffer containing the TLV-VALUE of the SignatureValue; must not be nullptr
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 308 of file data.cpp.

◆ setSignatureValue() [2/2]

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

Set SignatureValue by copying from a contiguous sequence of bytes.

Parameters
valuebuffer 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 300 of file data.cpp.

◆ setTag()

template<typename T >
void ndn::TagHost::setTag ( shared_ptr< T >  tag) const
inherited

Set (add or replace) a tag item.

Template Parameters
Ttype 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 80 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 284 of file data.cpp.

◆ wireDecode()

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

Decode from wire.

Definition at line 125 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 109 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
encoderEncodingBuffer containing Name, MetaInfo, Content, and SignatureInfo, but without SignatureValue and the outermost Type-Length of the Data element.
signatureRaw 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);
Data(const Name &name=Name())
Construct an unsigned Data packet with given name and empty Content.
Definition: data.cpp:34

Definition at line 94 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
encoderEncodingEstimator or EncodingBuffer instance.
wantUnsignedPortionOnlyIf 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
ErrorSignature is not present and wantUnsignedPortionOnly is false.

Definition at line 46 of file data.cpp.