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 KeyLocator. More...
 
const MetaInfogetMetaInfo () const noexcept
 Get MetaInfo. More...
 
const NamegetName () const noexcept
 Get name. More...
 
const SignatureInfogetSignatureInfo () const noexcept
 Get SignatureInfo. More...
 
int32_t getSignatureType () const noexcept
 Get SignatureType. More...
 
const BlockgetSignatureValue () const noexcept
 Get SignatureValue. 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 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 (const uint8_t *value, size_t length)
 Set Content by copying from a raw buffer. 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 MetaInfo. More...
 
DatasetName (const Name &name)
 Set name. More...
 
DatasetSignatureInfo (const SignatureInfo &info)
 Set SignatureInfo. More...
 
DatasetSignatureValue (ConstBufferPtr value)
 Set SignatureValue. More...
 
template<typename T >
void setTag (shared_ptr< T > tag) const
 set 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 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
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 322 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() / Block::value_size() or Block::value_begin() / Block::value_end().

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

Definition at line 173 of file data.hpp.

◆ getContentType()

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

Definition at line 273 of file data.hpp.

◆ getFinalBlock()

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

Definition at line 291 of file data.hpp.

◆ getFreshnessPeriod()

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

Definition at line 282 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 KeyLocator.

Definition at line 312 of file data.hpp.

◆ getMetaInfo()

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

Get MetaInfo.

Definition at line 141 of file data.hpp.

◆ getName()

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

Get name.

Definition at line 127 of file data.hpp.

◆ getSignatureInfo()

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

Get SignatureInfo.

Definition at line 227 of file data.hpp.

◆ getSignatureType()

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

Get SignatureType.

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

Definition at line 304 of file data.hpp.

◆ getSignatureValue()

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

Get SignatureValue.

Definition at line 247 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 66 of file tag-host.hpp.

◆ hasContent()

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

Return whether this Data has a Content element.

Definition at line 156 of file data.hpp.

◆ hasWire()

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

Check if this instance has cached wire encoding.

Definition at line 111 of file data.hpp.

◆ removeTag()

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

remove tag item

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

Definition at line 93 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/4]

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/4]

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

Set Content by copying from a raw buffer.

Parameters
valuebuffer with the TLV-VALUE of the content; may be nullptr if length is zero
lengthsize 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.

◆ setContent() [3/4]

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

◆ setContent() [4/4]

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

◆ setFinalBlock()

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

Definition at line 356 of file data.cpp.

◆ setFreshnessPeriod()

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

Definition at line 346 of file data.cpp.

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

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

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

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

◆ setSignatureValue()

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

Set SignatureValue.

Parameters
valuebuffer containing the TLV-VALUE of the SignatureValue; must not be nullptr

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

Returns
a reference to this Data, to allow chaining
Warning
SignatureValue is overwritten when the packet is signed via KeyChain::sign().

Definition at line 310 of file data.cpp.

◆ setTag()

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

set 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 79 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 294 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.