Represents an Interest packet. More...

#include <interest.hpp>

Inheritance diagram for ndn::Interest:

[legend]

Collaboration diagram for ndn::Interest:

[legend]

Classes
class	Error

Public Member Functions
	Interest (const Name &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` according to NDN Packet Format v0.3. More...

const Block &	wireEncode () const
	Encode into a Block according to NDN Packet Format v0.3. More...

void	wireDecode (const Block &wire)
	Decode from `wire` according to NDN Packet Format v0.3. More...

bool	hasWire () const
	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 Name &	getName () const noexcept

Interest &	setName (const Name &name)
	Set the Interest's name. More...

bool	getCanBePrefix () const noexcept
	Check whether the CanBePrefix element is present. More...

Interest &	setCanBePrefix (bool canBePrefix)
	Add or remove CanBePrefix element. More...

bool	getMustBeFresh () const noexcept
	Check whether the MustBeFresh element is present. More...

Interest &	setMustBeFresh (bool mustBeFresh)
	Add or remove MustBeFresh element. More...

const DelegationList &	getForwardingHint () const noexcept

Interest &	setForwardingHint (const DelegationList &value)

template<typename Modifier >
Interest &	modifyForwardingHint (const Modifier &modifier)
	Modify ForwardingHint in-place. More...

bool	hasNonce () const noexcept
	Check if the Nonce element is present. More...

uint32_t	getNonce () const
	Get nonce value. More...

Interest &	setNonce (uint32_t nonce)
	Set nonce value. More...

void	refreshNonce ()
	Change nonce value. More...

time::milliseconds	getInterestLifetime () const noexcept

Interest &	setInterestLifetime (time::milliseconds lifetime)
	Set the Interest's lifetime. More...

optional< uint8_t >	getHopLimit () const noexcept

Interest &	setHopLimit (optional< uint8_t > hopLimit)
	Set the Interest's hop limit. More...

bool	hasApplicationParameters () const noexcept

Block	getApplicationParameters () const

Interest &	setApplicationParameters (const Block &parameters)
	Set ApplicationParameters from a Block. More...

Interest &	setApplicationParameters (const uint8_t *value, size_t length)
	Set ApplicationParameters by copying from a raw buffer. More...

Interest &	setApplicationParameters (ConstBufferPtr value)
	Set ApplicationParameters from a shared buffer. More...

Interest &	unsetApplicationParameters ()
	Remove the ApplicationParameters element from this Interest. 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 void	setDefaultCanBePrefix (bool canBePrefix)
	Declare the default CanBePrefix setting of the application. More...

static bool	getAutoCheckParametersDigest ()

static void	setAutoCheckParametersDigest (bool b)

Detailed Description

Represents an Interest packet.

Definition at line 43 of file interest.hpp.

Constructor & Destructor Documentation

◆ Interest() [1/2]

ndn::Interest::Interest	(	const Name &	name = `Name()`,
		time::milliseconds	lifetime = `DEFAULT_INTEREST_LIFETIME`
	)

explicit

Construct an Interest with given name and lifetime.

Exceptions

std::invalid_argument name 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 52 of file interest.cpp.

References setCanBePrefix(), 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 62 of file interest.cpp.

References wireDecode().

Member Function Documentation

◆ wireEncode() [1/2]

template<encoding::Tag TAG>

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

Prepend wire encoding to encoder according to NDN Packet Format v0.3.

Definition at line 87 of file interest.cpp.

References ndn::tlv::CanBePrefix, ndn::DEFAULT_INTEREST_LIFETIME, getCanBePrefix(), getForwardingHint(), getHopLimit(), getInterestLifetime(), getMustBeFresh(), getName(), getNonce(), hasApplicationParameters(), ndn::tlv::HopLimit, ndn::tlv::Interest, ndn::tlv::InterestLifetime, ndn::tlv::MustBeFresh, NDN_THROW, ndn::tlv::Nonce, ndn::encoding::prependEmptyBlock(), ndn::encoding::prependNonNegativeIntegerBlock(), ndn::warnOnceCanBePrefixUnset(), ndn::DelegationList::wireEncode(), and ndn::Name::wireEncode().

Referenced by ndn::Face::Impl::asyncExpressInterest(), ndn::Face::Impl::asyncPutNack(), ns3::ndn::L3RateTracer::InNack(), ns3::ndn::L3RateTracer::OutNack(), and ndn::util::DummyClientFace::receive().

◆ wireEncode() [2/2]

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

Encode into a Block according to NDN Packet Format v0.3.

Definition at line 170 of file interest.cpp.

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

◆ wireDecode()

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

Decode from wire according to NDN Packet Format v0.3.

Definition at line 186 of file interest.cpp.

References ndn::tlv::ApplicationParameters, ndn::tlv::CanBePrefix, ndn::DEFAULT_INTEREST_LIFETIME, ndn::Block::elements_begin(), ndn::Block::elements_end(), ndn::Name::empty(), ndn::tlv::ForwardingHint, hasApplicationParameters(), ndn::tlv::HopLimit, ndn::tlv::Interest, ndn::tlv::InterestLifetime, ndn::tlv::isCriticalType(), isParametersDigestValid(), nonstd::optional_lite::std11::move(), ndn::tlv::MustBeFresh, ndn::tlv::Name, NDN_THROW, ndn::tlv::Nonce, ndn::Block::parse(), ndn::encoding::readNonNegativeInteger(), ndn::to_string(), ndn::Block::type(), and ndn::DelegationList::wireDecode().

Referenced by Interest(), and wireEncode().

◆ hasWire()

bool ndn::Interest::hasWire ( ) const

inline

Check if this instance has cached wire encoding.

Definition at line 88 of file interest.hpp.

References ndn::Block::hasWire().

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 323 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 333 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(), 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 365 of file interest.cpp.

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

Referenced by ndn::Face::Impl::nackPendingInterests().

◆ getName()

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

inlinenoexcept

Definition at line 121 of file interest.hpp.

Referenced by nfd::fw::SelfLearningStrategy::afterReceiveNack(), ndn::Face::Impl::asyncExpressInterest(), ndn::Face::Impl::asyncPutNack(), nfd::pit::Entry::canMatch(), ndn::security::v2::ValidationPolicySimpleHierarchy::checkPolicy(), ndn::security::v2::validator_config::ValidationPolicyConfig::checkPolicy(), nfd::ManagerBase::extractRequester(), ndn::security::v2::CertificateCache::find(), ndn::security::v2::TrustAnchorContainer::find(), ndn::InMemoryStorage::find(), ndn::security::v2::getKeyLocatorName(), nfd::fw::asf::AsfMeasurements::getOrCreateNamespaceInfo(), isParametersDigestValid(), nfd::CommandAuthenticator::makeAuthorization(), matchesInterest(), nfd::fw::Strategy::onDroppedInterest(), ns3::ndn::Consumer::OnNack(), ndn::operator<<(), ndn::security::parse(), ndn::InMemoryStorage::selectChild(), ndn::mgmt::StatusDatasetContext::setPrefix(), ndn::security::v2::KeyChain::sign(), ndn::mgmt::StatusDatasetContext::StatusDatasetContext(), unsetApplicationParameters(), ndn::security::v2::Validator::validate(), wireEncode(), and nfd::fw::wouldViolateScope().

◆ setName()

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

Set the Interest's name.

Exceptions

std::invalid_argument name is invalid

Definition at line 375 of file interest.cpp.

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

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

◆ setDefaultCanBePrefix()

static void ndn::Interest::setDefaultCanBePrefix ( bool canBePrefix )

inlinestatic

Declare the default CanBePrefix setting of the application.

As part of transitioning to NDN Packet Format v0.3, the default setting for CanBePrefix will be changed from "true" to "false". Application developers are advised to review all Interests expressed by their application and decide what CanBePrefix setting is appropriate for each Interest, to avoid breaking changes when the transition occurs. Application may either set CanBePrefix on a per-Interest basis, or declare a default CanBePrefix setting for all Interests expressed by the application using this function. If an application neither declares a default nor sets CanBePrefix on every Interest, Interest::wireEncode will print a one-time warning message.

Note: This function should not be used in libraries or in ndn-cxx unit tests.

See also: https://redmine.named-data.net/projects/nfd/wiki/Packet03Transition

Definition at line 147 of file interest.hpp.

◆ getCanBePrefix()

bool ndn::Interest::getCanBePrefix ( ) const

inlinenoexcept

Check whether the CanBePrefix element is present.

Definition at line 155 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

canBePrefix whether CanBePrefix element should be present.

Definition at line 164 of file interest.hpp.

References ndn::Block::reset().

Referenced by Interest(), and ndn::security::CommandInterestSigner::makeCommandInterest().

◆ getMustBeFresh()

bool ndn::Interest::getMustBeFresh ( ) const

inlinenoexcept

Check whether the MustBeFresh element is present.

Definition at line 175 of file interest.hpp.

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

◆ setMustBeFresh()

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

inline

Add or remove MustBeFresh element.

Parameters

mustBeFresh whether MustBeFresh element should be present.

Definition at line 184 of file interest.hpp.

References ndn::Block::reset().

◆ getForwardingHint()

const DelegationList& ndn::Interest::getForwardingHint ( ) const

inlinenoexcept

Definition at line 192 of file interest.hpp.

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

◆ setForwardingHint()

Interest & ndn::Interest::setForwardingHint ( const DelegationList & value )

Definition at line 392 of file interest.cpp.

References ndn::Block::reset().

◆ modifyForwardingHint()

template<typename Modifier >

Interest& ndn::Interest::modifyForwardingHint ( const Modifier & modifier )

inline

Modify ForwardingHint in-place.

Template Parameters

Modifier a unary function that accepts DelegationList&

This is equivalent to, but more efficient (avoids copying) than:

auto fh = interest.getForwardingHint();
modifier(fh);
interest.setForwardingHint(fh);

Definition at line 212 of file interest.hpp.

References ndn::Block::reset().

◆ hasNonce()

bool ndn::Interest::hasNonce ( ) const

inlinenoexcept

Check if the Nonce element is present.

Definition at line 222 of file interest.hpp.

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

◆ getNonce()

uint32_t ndn::Interest::getNonce ( ) const

Get nonce value.

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

Definition at line 400 of file interest.cpp.

References ndn::random::generateWord32(), hasNonce(), and ndn::Block::reset().

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

◆ setNonce()

Interest & ndn::Interest::setNonce ( uint32_t nonce )

Set nonce value.

Definition at line 410 of file interest.cpp.

References ndn::Block::reset().

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

References ndn::random::generateWord32(), hasNonce(), and ndn::Block::reset().

Referenced by ndn::security::v2::CertificateFetcherDirectFetch::doFetch().

◆ getInterestLifetime()

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

inlinenoexcept

Definition at line 248 of file interest.hpp.

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_argument lifetime is negative

Definition at line 433 of file interest.cpp.

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

Referenced by Interest().

◆ getHopLimit()

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

inlinenoexcept

Definition at line 260 of file interest.hpp.

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

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

References ndn::Block::reset().

◆ hasApplicationParameters()

bool ndn::Interest::hasApplicationParameters ( ) const

inlinenoexcept

Definition at line 273 of file interest.hpp.

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

◆ getApplicationParameters()

Block ndn::Interest::getApplicationParameters ( ) const

inline

Definition at line 279 of file interest.hpp.

◆ setApplicationParameters() [1/3]

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

Set ApplicationParameters from a Block.

Returns: a reference to this Interest

If the block is default-constructed, this will set a zero-length ApplicationParameters element. Else, if the block's TLV-TYPE is ApplicationParameters, it will be used directly as this Interest's ApplicationParameters element. Else, 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 469 of file interest.cpp.

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

◆ setApplicationParameters() [2/3]

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

Set ApplicationParameters by copying from a raw buffer.

Parameters

value	points to a buffer from which the TLV-VALUE of the parameters will be copied; may be nullptr if `length` is zero
length	size of the buffer

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

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

◆ setApplicationParameters() [3/3]

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

Set ApplicationParameters from a shared buffer.

Parameters

value buffer 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 498 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.

Postcondition: hasApplicationParameters() == false

This function will also remove any ParametersSha256DigestComponents from the Interest's name.

Definition at line 510 of file interest.cpp.

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

◆ getAutoCheckParametersDigest()

static bool ndn::Interest::getAutoCheckParametersDigest ( )

inlinestatic

Definition at line 336 of file interest.hpp.

◆ setAutoCheckParametersDigest()

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

inlinestatic

Definition at line 342 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 524 of file interest.cpp.

References getName(), and hasApplicationParameters().

Referenced by wireDecode().

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

ndnSIM/ndn-cxx/ndn-cxx/interest.hpp
ndnSIM/ndn-cxx/ndn-cxx/interest.cpp

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Interest() [1/2]

◆ Interest() [2/2]

Member Function Documentation

◆ wireEncode() [1/2]

◆ wireEncode() [2/2]

◆ wireDecode()

◆ hasWire()

◆ toUri()

◆ matchesData()

◆ matchesInterest()

◆ getName()

◆ setName()

◆ setDefaultCanBePrefix()

◆ getCanBePrefix()

◆ setCanBePrefix()

◆ getMustBeFresh()

◆ setMustBeFresh()

◆ getForwardingHint()

◆ setForwardingHint()

◆ modifyForwardingHint()

◆ hasNonce()

◆ getNonce()

◆ setNonce()

◆ refreshNonce()

◆ getInterestLifetime()

◆ setInterestLifetime()

◆ getHopLimit()

◆ setHopLimit()

◆ hasApplicationParameters()

◆ getApplicationParameters()

◆ setApplicationParameters() [1/3]

◆ setApplicationParameters() [2/3]

◆ setApplicationParameters() [3/3]

◆ unsetApplicationParameters()

◆ getAutoCheckParametersDigest()

◆ setAutoCheckParametersDigest()

◆ isParametersDigestValid()