ndn::Interest Class Reference

Represents an Interest packet. More...

#include <ndn-cxx/interest.hpp>

+ Inheritance diagram for ndn::Interest:
+ Collaboration diagram for ndn::Interest:

Classes

class  Error
 
class  Nonce
 

Public Member Functions

 Interest (const Block &wire)
 Construct an Interest by decoding from wire. More...
 
 Interest (const Name &name={}, time::milliseconds lifetime=DEFAULT_INTEREST_LIFETIME)
 Construct an Interest with given name and lifetime. More...
 
InputBuffers extractSignedRanges () const
 Extract ranges of Interest covered by the signature in Packet Specification v0.3. More...
 
Block getApplicationParameters () const
 Get the ApplicationParameters element. More...
 
bool getCanBePrefix () const noexcept
 Check whether the CanBePrefix element is present. More...
 
uint64_t getCongestionMark () const
 Get the value of the CongestionMark tag. More...
 
span< const NamegetForwardingHint () const noexcept
 
optional< uint8_t > getHopLimit () const noexcept
 Get the Interest's hop limit. More...
 
time::milliseconds getInterestLifetime () const noexcept
 Get the Interest's lifetime. More...
 
bool getMustBeFresh () const noexcept
 Check whether the MustBeFresh element is present. More...
 
const NamegetName () const noexcept
 
Nonce getNonce () const
 Get nonce value. More...
 
optional< SignatureInfogetSignatureInfo () const
 Get the InterestSignatureInfo element. More...
 
Block getSignatureValue () const
 Get the InterestSignatureValue element. More...
 
template<typename T >
shared_ptr< T > getTag () const
 Get a tag item. More...
 
bool hasApplicationParameters () const noexcept
 Return whether this Interest has any ApplicationParameters element. More...
 
bool hasNonce () const noexcept
 Check if the Nonce element is present. More...
 
bool hasWire () const noexcept
 Check if this instance has cached wire encoding. More...
 
bool isParametersDigestValid () const
 Check if the ParametersSha256DigestComponent in the name is valid. More...
 
bool isSigned () const noexcept
 Return whether the Interest is signed. More...
 
bool matchesData (const Data &data) const
 Check if Interest can be satisfied by data. More...
 
bool matchesInterest (const Interest &other) const
 Check if this Interest matches other. More...
 
void refreshNonce ()
 Change nonce value. More...
 
template<typename T >
void removeTag () const
 Remove a tag item. More...
 
InterestsetApplicationParameters (const Block &block)
 Set ApplicationParameters from a Block. More...
 
InterestsetApplicationParameters (ConstBufferPtr value)
 Set ApplicationParameters from a shared buffer. More...
 
InterestsetApplicationParameters (span< const uint8_t > value)
 Set ApplicationParameters by copying from a contiguous sequence of bytes. More...
 
InterestsetCanBePrefix (bool canBePrefix)
 Add or remove CanBePrefix element. More...
 
void setCongestionMark (uint64_t mark)
 Set the CongestionMark tag to the specified value. More...
 
InterestsetForwardingHint (std::vector< Name > value)
 
InterestsetHopLimit (optional< uint8_t > hopLimit)
 Set the Interest's hop limit. More...
 
InterestsetInterestLifetime (time::milliseconds lifetime)
 Set the Interest's lifetime. More...
 
InterestsetMustBeFresh (bool mustBeFresh)
 Add or remove MustBeFresh element. More...
 
InterestsetName (const Name &name)
 Set the Interest's name. More...
 
InterestsetNonce (optional< Nonce > nonce)
 Set the Interest's nonce. More...
 
InterestsetSignatureInfo (const SignatureInfo &info)
 Set the InterestSignatureInfo element. More...
 
InterestsetSignatureValue (ConstBufferPtr value)
 Set InterestSignatureValue from a shared buffer. More...
 
InterestsetSignatureValue (span< const uint8_t > value)
 Set InterestSignatureValue 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...
 
std::string toUri () const
 Return a URI-like string that represents the Interest. More...
 
InterestunsetApplicationParameters ()
 Remove the ApplicationParameters element from this Interest. More...
 
void wireDecode (const Block &wire)
 Decode from wire. More...
 
const BlockwireEncode () const
 Encode into a Block. More...
 
template<encoding::Tag TAG>
size_t wireEncode (EncodingImpl< TAG > &encoder) const
 Prepend wire encoding to encoder. More...
 

Static Public Member Functions

static bool getAutoCheckParametersDigest ()
 
static void setAutoCheckParametersDigest (bool b)
 

Detailed Description

Represents an Interest packet.

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

Definition at line 49 of file interest.hpp.

Constructor & Destructor Documentation

◆ Interest() [1/2]

ndn::Interest::Interest ( const Name name = {},
time::milliseconds  lifetime = DEFAULT_INTEREST_LIFETIME 
)
explicit

Construct an Interest with given name and lifetime.

Exceptions
std::invalid_argumentname is invalid or lifetime is negative
Warning
In certain contexts that use Interest::shared_from_this(), Interest must be created using make_shared. Otherwise, shared_from_this() will trigger undefined behavior.

Definition at line 45 of file interest.cpp.

◆ Interest() [2/2]

ndn::Interest::Interest ( const Block wire)
explicit

Construct an Interest by decoding from wire.

Warning
In certain contexts that use Interest::shared_from_this(), Interest must be created using make_shared. Otherwise, shared_from_this() will trigger undefined behavior.

Definition at line 51 of file interest.cpp.

Member Function Documentation

◆ extractSignedRanges()

InputBuffers ndn::Interest::extractSignedRanges ( ) const

Extract ranges of Interest covered by the signature in Packet Specification v0.3.

Exceptions
ErrorInterest 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 636 of file interest.cpp.

◆ getApplicationParameters()

Block ndn::Interest::getApplicationParameters ( ) const
inline

Get the ApplicationParameters element.

If the element is not present, an invalid Block will be returned.

See also
hasApplicationParameters()

Definition at line 320 of file interest.hpp.

◆ getAutoCheckParametersDigest()

static bool ndn::Interest::getAutoCheckParametersDigest ( )
inlinestatic

Definition at line 439 of file interest.hpp.

◆ getCanBePrefix()

bool ndn::Interest::getCanBePrefix ( ) const
inlinenoexcept

Check whether the CanBePrefix element is present.

Definition at line 189 of file interest.hpp.

◆ getCongestionMark()

uint64_t ndn::PacketBase::getCongestionMark ( ) const
inherited

Get the value of the CongestionMark tag.

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

◆ getForwardingHint()

span<const Name> ndn::Interest::getForwardingHint ( ) const
inlinenoexcept

Definition at line 228 of file interest.hpp.

◆ getHopLimit()

optional<uint8_t> ndn::Interest::getHopLimit ( ) const
inlinenoexcept

Get the Interest's hop limit.

Definition at line 290 of file interest.hpp.

◆ getInterestLifetime()

time::milliseconds ndn::Interest::getInterestLifetime ( ) const
inlinenoexcept

Get the Interest's lifetime.

Definition at line 274 of file interest.hpp.

◆ getMustBeFresh()

bool ndn::Interest::getMustBeFresh ( ) const
inlinenoexcept

Check whether the MustBeFresh element is present.

Definition at line 210 of file interest.hpp.

◆ getName()

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

Definition at line 173 of file interest.hpp.

◆ getNonce()

Interest::Nonce ndn::Interest::getNonce ( ) const

Get nonce value.

If nonce was not present, it is added and assigned a random value.

Definition at line 404 of file interest.cpp.

◆ getSignatureInfo()

optional< SignatureInfo > ndn::Interest::getSignatureInfo ( ) const

Get the InterestSignatureInfo element.

Return values
nulloptThe element is not present.

Definition at line 531 of file interest.cpp.

◆ getSignatureValue()

Block ndn::Interest::getSignatureValue ( ) const

Get the InterestSignatureValue element.

If the element is not present, an invalid Block will be returned.

Definition at line 575 of file interest.cpp.

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

◆ hasApplicationParameters()

bool ndn::Interest::hasApplicationParameters ( ) const
inlinenoexcept

Return whether this Interest has any ApplicationParameters element.

Definition at line 307 of file interest.hpp.

◆ hasNonce()

bool ndn::Interest::hasNonce ( ) const
inlinenoexcept

Check if the Nonce element is present.

Definition at line 240 of file interest.hpp.

◆ hasWire()

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

Check if this instance has cached wire encoding.

Definition at line 140 of file interest.hpp.

◆ isParametersDigestValid()

bool ndn::Interest::isParametersDigestValid ( ) const

Check if the ParametersSha256DigestComponent in the name is valid.

Returns true if there is a single ParametersSha256DigestComponent in the name and the digest value is correct, or if there is no ParametersSha256DigestComponent in the name and the Interest does not contain any parameters. Returns false otherwise.

Definition at line 671 of file interest.cpp.

◆ isSigned()

bool ndn::Interest::isSigned ( ) const
noexcept

Return whether the Interest is signed.

Warning
This function only determines whether signature information is present in the Interest; it does not verify that the signature is valid.

Definition at line 521 of file interest.cpp.

◆ matchesData()

bool ndn::Interest::matchesData ( const Data data) const

Check if Interest can be satisfied by data.

This method considers Name, CanBePrefix, and MustBeFresh. However, MustBeFresh processing is limited to rejecting Data with zero/omitted FreshnessPeriod.

Definition at line 327 of file interest.cpp.

◆ matchesInterest()

bool ndn::Interest::matchesInterest ( const Interest other) const

Check if this Interest matches other.

Two Interests match if both have the same Name, CanBePrefix, and MustBeFresh.

Definition at line 359 of file interest.cpp.

◆ refreshNonce()

void ndn::Interest::refreshNonce ( )

Change nonce value.

If the Nonce element is present, the new nonce value will differ from the old value. If the Nonce element is not present, this method does nothing.

Definition at line 424 of file interest.cpp.

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

◆ setApplicationParameters() [1/3]

Interest & ndn::Interest::setApplicationParameters ( const Block block)

Set ApplicationParameters from a Block.

Parameters
blockTLV block to be used as ApplicationParameters; must be valid
Returns
A reference to this Interest.

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

This function will also recompute the value of the ParametersSha256DigestComponent in the Interest's name. If the name does not contain a ParametersSha256DigestComponent, one will be appended to it.

Definition at line 478 of file interest.cpp.

◆ setApplicationParameters() [2/3]

Interest & ndn::Interest::setApplicationParameters ( ConstBufferPtr  value)

Set ApplicationParameters from a shared buffer.

Parameters
valuebuffer containing the TLV-VALUE of the parameters; must not be nullptr
Returns
A reference to this Interest.

This function will also recompute the value of the ParametersSha256DigestComponent in the Interest's name. If the name does not contain a ParametersSha256DigestComponent, one will be appended to it.

Definition at line 499 of file interest.cpp.

◆ setApplicationParameters() [3/3]

Interest & ndn::Interest::setApplicationParameters ( span< const uint8_t >  value)

Set ApplicationParameters by copying from a contiguous sequence of bytes.

Parameters
valuebuffer from which the TLV-VALUE of the parameters will be copied
Returns
A reference to this Interest.

This function will also recompute the value of the ParametersSha256DigestComponent in the Interest's name. If the name does not contain a ParametersSha256DigestComponent, one will be appended to it.

Definition at line 493 of file interest.cpp.

◆ setAutoCheckParametersDigest()

static void ndn::Interest::setAutoCheckParametersDigest ( bool  b)
inlinestatic

Definition at line 445 of file interest.hpp.

◆ setCanBePrefix()

Interest& ndn::Interest::setCanBePrefix ( bool  canBePrefix)
inline

Add or remove CanBePrefix element.

Parameters
canBePrefixWhether the element should be present.

Definition at line 199 of file interest.hpp.

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

◆ setForwardingHint()

Interest & ndn::Interest::setForwardingHint ( std::vector< Name value)

Definition at line 387 of file interest.cpp.

◆ setHopLimit()

Interest & ndn::Interest::setHopLimit ( optional< uint8_t >  hopLimit)

Set the Interest's hop limit.

Use setHopLimit(nullopt) to remove any hop limit from the Interest.

Definition at line 451 of file interest.cpp.

◆ setInterestLifetime()

Interest & ndn::Interest::setInterestLifetime ( time::milliseconds  lifetime)

Set the Interest's lifetime.

Exceptions
std::invalid_argumentlifetime is negative

Definition at line 437 of file interest.cpp.

◆ setMustBeFresh()

Interest& ndn::Interest::setMustBeFresh ( bool  mustBeFresh)
inline

Add or remove MustBeFresh element.

Parameters
mustBeFreshWhether the element should be present.

Definition at line 220 of file interest.hpp.

◆ setName()

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

Set the Interest's name.

Exceptions
std::invalid_argumentname is invalid

Definition at line 369 of file interest.cpp.

◆ setNonce()

Interest & ndn::Interest::setNonce ( optional< Nonce nonce)

Set the Interest's nonce.

Use setNonce(nullopt) to remove any nonce from the Interest.

Definition at line 414 of file interest.cpp.

◆ setSignatureInfo()

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

Set the InterestSignatureInfo element.

Definition at line 541 of file interest.cpp.

◆ setSignatureValue() [1/2]

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

Set InterestSignatureValue from a shared buffer.

Parameters
valuebuffer containing the TLV-VALUE of the InterestSignatureValue; must not be nullptr
Returns
A reference to this Interest.
Exceptions
ErrorInterestSignatureInfo is unset

InterestSignatureInfo must be set before setting InterestSignatureValue.

Definition at line 626 of file interest.cpp.

◆ setSignatureValue() [2/2]

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

Set InterestSignatureValue by copying from a contiguous sequence of bytes.

Parameters
valuebuffer from which the TLV-VALUE of the InterestSignatureValue will be copied
Returns
A reference to this Interest.
Exceptions
ErrorInterestSignatureInfo is unset

InterestSignatureInfo must be set before setting InterestSignatureValue.

Definition at line 620 of file interest.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.

◆ toUri()

std::string ndn::Interest::toUri ( ) const

Return a URI-like string that represents the Interest.

The string always starts with getName().toUri(). After the name, if any of the Interest's CanBePrefix, MustBeFresh, Nonce, InterestLifetime, or HopLimit fields are present, their textual representation is appended as a query string. Example: "/test/name?MustBeFresh&Nonce=123456"

Definition at line 317 of file interest.cpp.

◆ unsetApplicationParameters()

Interest & ndn::Interest::unsetApplicationParameters ( )

Remove the ApplicationParameters element from this Interest.

Returns
A reference to this Interest.
Postcondition
hasApplicationParameters() == false

This function will also remove any InterestSignatureInfo and InterestSignatureValue elements in the Interest, as well as any ParametersSha256DigestComponents in the Interest's name.

Definition at line 509 of file interest.cpp.

◆ wireDecode()

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

Decode from wire.

Definition at line 150 of file interest.cpp.

◆ wireEncode() [1/2]

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

Encode into a Block.

Definition at line 134 of file interest.cpp.

◆ wireEncode() [2/2]

template<encoding::Tag TAG>
size_t ndn::Interest::wireEncode ( EncodingImpl< TAG > &  encoder) const

Prepend wire encoding to encoder.

Definition at line 60 of file interest.cpp.