NS-3 based Named Data Networking (NDN) simulator
ndnSIM 2.5: NDN, CCN, CCNx, content centric networks
API Documentation
ndn::Interest Class Reference

Represents an Interest packet. More...

#include <interest.hpp>

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

Classes

class  Error
 
class  Nonce
 

Public Member Functions

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

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

References setInterestLifetime(), and setName().

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

References wireDecode().

Member Function Documentation

◆ wireEncode() [1/2]

◆ wireEncode() [2/2]

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

Encode into a Block.

Definition at line 134 of file interest.cpp.

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

Referenced by extractSignedRanges().

◆ wireDecode()

◆ hasWire()

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

Check if this instance has cached wire encoding.

Definition at line 139 of file interest.hpp.

References matchesData(), matchesInterest(), and toUri().

Referenced by ns3::ndn::L3RateTracer::InNack(), and ns3::ndn::L3RateTracer::OutNack().

◆ 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 315 of file interest.cpp.

Referenced by hasWire().

◆ 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 325 of file interest.cpp.

References ndn::Name::get(), getCanBePrefix(), ndn::Data::getFreshnessPeriod(), ndn::Data::getFullName(), getMustBeFresh(), ndn::Data::getName(), ndn::name::Component::isImplicitSha256Digest(), ndn::Name::isPrefixOf(), and ndn::Name::size().

Referenced by nfd::cs::Entry::canSatisfy(), ndn::security::v2::CertificateCache::find(), ndn::security::v2::TrustAnchorContainer::find(), hasWire(), and ndn::InMemoryStorage::selectChild().

◆ 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 357 of file interest.cpp.

References getCanBePrefix(), getMustBeFresh(), and getName().

Referenced by hasWire(), and ndn::Face::Impl::nackPendingInterests().

◆ getName()

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

Definition at line 172 of file interest.hpp.

References setName().

Referenced by ndn::mgmt::Dispatcher::addStatusDataset(), nfd::fw::asf::AsfStrategy::afterReceiveNack(), nfd::fw::SelfLearningStrategy::afterReceiveNack(), nfd::pit::Entry::canMatch(), ndn::security::v2::ValidationPolicySimpleHierarchy::checkPolicy(), ndn::security::v2::validator_config::ValidationPolicyConfig::checkPolicy(), ndn::security::v2::ValidationPolicyCommandInterest::checkPolicy(), ndn::Face::Impl::expressInterest(), ndn::security::v2::CertificateCache::find(), ndn::security::v2::TrustAnchorContainer::find(), ndn::InMemoryStorage::find(), nfd::Forwarder::Forwarder(), nfd::fw::asf::ProbingModule::getFaceToProbe(), ndn::security::v2::getKeyLocatorName(), nfd::cs::Cs::insert(), isParametersDigestValid(), nfd::CommandAuthenticator::makeAuthorization(), matchesInterest(), nfd::matchFilter(), nfd::Forwarder::onContentStoreHit(), nfd::Forwarder::onContentStoreMiss(), nfd::Forwarder::onDroppedInterest(), nfd::fw::Strategy::onDroppedInterest(), nfd::Forwarder::onIncomingNack(), nfd::Forwarder::onInterestLoop(), nfd::fw::asf::FaceStatsCompare::operator()(), ndn::operator<<(), ndn::security::parse(), nfd::pit::Pit::Pit(), nfd::ManagerBase::registerNotificationStream(), ndn::mgmt::Dispatcher::removeTopPrefix(), ndn::InMemoryStorage::selectChild(), ndn::mgmt::StatusDatasetContext::setPrefix(), ndn::security::v2::KeyChain::sign(), ndn::mgmt::StatusDatasetContext::StatusDatasetContext(), ndn::util::NotificationSubscriberBase::stop(), ndn::util::SegmentFetcher::stop(), unsetApplicationParameters(), wireEncode(), nfd::fw::wouldViolateScope(), ndn::util::DummyClientFace::~DummyClientFace(), and ndn::security::v2::InterestValidationState::~InterestValidationState().

◆ setName()

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

Set the Interest's name.

Exceptions
std::invalid_argumentname is invalid

Definition at line 367 of file interest.cpp.

References hasApplicationParameters(), NDN_THROW, and ndn::Block::reset().

Referenced by getName(), Interest(), ndn::security::InterestSigner::makeCommandInterest(), ndn::security::v2::KeyChain::sign(), and ndn::util::SegmentFetcher::stop().

◆ getCanBePrefix()

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

Check whether the CanBePrefix element is present.

Definition at line 186 of file interest.hpp.

Referenced by nfd::pit::Entry::canMatch(), matchesData(), matchesInterest(), ndn::operator<<(), and wireEncode().

◆ setCanBePrefix()

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

Add or remove CanBePrefix element.

Parameters
canBePrefixwhether CanBePrefix element should be present.

Definition at line 195 of file interest.hpp.

Referenced by ndn::security::v2::CertificateBundleFetcher::doFetch(), and ndn::util::SegmentFetcher::stop().

◆ getMustBeFresh()

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

◆ setMustBeFresh()

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

Add or remove MustBeFresh element.

Parameters
mustBeFreshwhether MustBeFresh element should be present.

Definition at line 214 of file interest.hpp.

Referenced by ndn::security::v2::CertificateBundleFetcher::doFetch(), and ndn::util::SegmentFetcher::stop().

◆ getForwardingHint()

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

Definition at line 222 of file interest.hpp.

References setForwardingHint().

Referenced by nfd::Forwarder::Forwarder(), and nfd::fw::Strategy::lookupFib().

◆ setForwardingHint()

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

Definition at line 385 of file interest.cpp.

References nonstd::optional_lite::std11::move(), and ndn::Block::reset().

Referenced by getForwardingHint().

◆ hasNonce()

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

Check if the Nonce element is present.

Definition at line 233 of file interest.hpp.

References getNonce(), refreshNonce(), and setNonce().

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

◆ 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 402 of file interest.cpp.

References ndn::generateNonce(), hasNonce(), and ndn::Block::reset().

Referenced by nfd::Forwarder::Forwarder(), hasNonce(), nfd::Forwarder::onIncomingNack(), ndn::operator<<(), nfd::pit::OutRecord::setIncomingNack(), nfd::pit::FaceRecord::update(), and wireEncode().

◆ 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 412 of file interest.cpp.

References ndn::Block::reset().

Referenced by hasNonce().

◆ 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 422 of file interest.cpp.

References ndn::generateNonce(), hasNonce(), and ndn::Block::reset().

Referenced by nfd::fw::asf::AsfStrategy::afterReceiveNack(), ndn::security::v2::CertificateFetcherDirectFetch::doFetch(), hasNonce(), and ndn::util::SegmentFetcher::stop().

◆ getInterestLifetime()

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

Definition at line 261 of file interest.hpp.

References setInterestLifetime().

Referenced by ndn::operator<<(), nfd::pit::FaceRecord::update(), and wireEncode().

◆ setInterestLifetime()

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

Set the Interest's lifetime.

Exceptions
std::invalid_argumentlifetime is negative

Definition at line 435 of file interest.cpp.

References NDN_THROW, and ndn::Block::reset().

Referenced by ndn::security::v2::CertificateBundleFetcher::doFetch(), getInterestLifetime(), Interest(), ndn::util::SegmentFetcher::stop(), and ndn::nfd::Controller::~Controller().

◆ getHopLimit()

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

◆ 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 449 of file interest.cpp.

References ndn::tlv::ApplicationParameters, ndn::Block::encode(), nonstd::optional_lite::std11::move(), and ndn::Block::reset().

Referenced by getHopLimit().

◆ hasApplicationParameters()

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

Return whether this Interest has any ApplicationParameters.

Definition at line 289 of file interest.hpp.

Referenced by isParametersDigestValid(), setName(), wireDecode(), and wireEncode().

◆ getApplicationParameters()

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

Get the ApplicationParameters.

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

See also
hasApplicationParameters()

Definition at line 302 of file interest.hpp.

References extractSignedRanges(), getSignatureInfo(), getSignatureValue(), info, isSigned(), setApplicationParameters(), setSignatureInfo(), setSignatureValue(), and unsetApplicationParameters().

◆ setApplicationParameters() [1/4]

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 472 of file interest.cpp.

References ndn::tlv::ApplicationParameters, ndn::Block::isValid(), NDN_THROW, ndn::Block::reset(), and ndn::Block::type().

Referenced by getApplicationParameters(), and setApplicationParameters().

◆ setApplicationParameters() [2/4]

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 490 of file interest.cpp.

References ndn::tlv::ApplicationParameters, ndn::encoding::makeBinaryBlock(), and ndn::Block::reset().

◆ setApplicationParameters() [3/4]

Interest & ndn::Interest::setApplicationParameters ( const uint8_t *  value,
size_t  length 
)

Set ApplicationParameters by copying from a raw buffer.

Parameters
valuepoints to a buffer from which the TLV-VALUE of the parameters will be copied; may be nullptr if length is zero
lengthsize of the buffer
Returns
a reference to this Interest
Deprecated:
Use setApplicationParameters(span<const uint8_t>)

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.

References NDN_THROW, and setApplicationParameters().

◆ setApplicationParameters() [4/4]

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 509 of file interest.cpp.

References ndn::tlv::ApplicationParameters, nonstd::optional_lite::std11::move(), NDN_THROW, and ndn::Block::reset().

◆ 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 522 of file interest.cpp.

References ndn::Name::erase(), getName(), and ndn::Block::reset().

Referenced by getApplicationParameters().

◆ 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 and does not verify that the signature is valid.

Definition at line 534 of file interest.cpp.

References ndn::Name::empty(), getSignatureInfo(), getSignatureValue(), ndn::Block::isValid(), and ndn::tlv::ParametersSha256DigestComponent.

Referenced by getApplicationParameters().

◆ getSignatureInfo()

◆ setSignatureInfo()

◆ getSignatureValue()

Block ndn::Interest::getSignatureValue ( ) const

Get the InterestSignatureValue.

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

Definition at line 588 of file interest.cpp.

References ndn::tlv::InterestSignatureValue.

Referenced by getApplicationParameters(), isSigned(), and ndn::security::parse().

◆ setSignatureValue()

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

Set the InterestSignatureValue.

Parameters
valueBuffer containing the TLV-VALUE of the InterestSignatureValue; must not be nullptr
Exceptions
ErrorInterestSignatureInfo is unset

InterestSignatureInfo must be set before setting InterestSignatureValue

Definition at line 598 of file interest.cpp.

References ndn::tlv::InterestSignatureInfo, ndn::tlv::InterestSignatureValue, nonstd::optional_lite::std11::move(), NDN_THROW, and ndn::Block::reset().

Referenced by getApplicationParameters(), and ndn::security::v2::KeyChain::sign().

◆ 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 638 of file interest.cpp.

References ndn::tlv::ApplicationParameters, bufs, ndn::Name::empty(), ndn::tlv::InterestSignatureInfo, ndn::tlv::InterestSignatureValue, NDN_THROW, ndn::tlv::ParametersSha256DigestComponent, and wireEncode().

Referenced by getApplicationParameters(), ndn::security::parse(), and ndn::security::v2::KeyChain::sign().

◆ getAutoCheckParametersDigest()

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

Definition at line 420 of file interest.hpp.

◆ setAutoCheckParametersDigest()

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

◆ 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 673 of file interest.cpp.

References ndn::OBufferStream::buf(), ndn::security::transform::digestFilter(), getName(), hasApplicationParameters(), nonstd::optional_lite::std11::move(), ndn::tlv::ParametersSha256DigestComponent, ndn::SHA256, ndn::Name::size(), and ndn::security::transform::streamSink().

Referenced by setAutoCheckParametersDigest(), and wireDecode().


The documentation for this class was generated from the following files: