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`. More...

const Block &	wireEncode () const
	Encode to a `Block`. More...

void	wireDecode (const Block &wire)
	Decode from `wire` in NDN Packet Format v0.2 or 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	matchesName (const Name &name) const
	Check if Interest, including selectors, matches the given `name`. More...

bool	matchesData (const Data &data) const
	Check if Interest can be satisfied by `data`. More...

bool	matchesInterest (const Interest &other) const
	Check if Interest matches `other` interest. More...

const Name &	getName () const

Interest &	setName (const Name &name)

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

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

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

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

const DelegationList &	getForwardingHint () const

Interest &	setForwardingHint (const DelegationList &value)

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

bool	hasNonce () const
	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

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

bool	hasParameters () const

const Block &	getParameters () const

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

Interest &	setParameters (const uint8_t *buffer, size_t bufferSize)
	Copy parameters from raw buffer. More...

Interest &	setParameters (ConstBufferPtr buffer)
	Set parameters from a wire buffer. More...

Interest &	unsetParameters ()
	Remove the Parameters element from this Interest. More...

bool	hasSelectors () const
	Check if Interest has any selector present. More...

const Selectors &	getSelectors () const

Interest &	setSelectors (const Selectors &selectors)

int	getMinSuffixComponents () const

Interest &	setMinSuffixComponents (int minSuffixComponents)

int	getMaxSuffixComponents () const

Interest &	setMaxSuffixComponents (int maxSuffixComponents)

const KeyLocator &	getPublisherPublicKeyLocator () const

Interest &	setPublisherPublicKeyLocator (const KeyLocator &keyLocator)

const Exclude &	getExclude () const

Interest &	setExclude (const Exclude &exclude)

int	getChildSelector () const

Interest &	setChildSelector (int childSelector)

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

Friends
bool	operator== (const Interest &lhs, const Interest &rhs)

Detailed Description

Represents an Interest packet.

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

References setCanBePrefix().

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

Definition at line 70 of file interest.cpp.

References hasParameters().

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

◆ wireEncode() [2/2]

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

Encode to a Block.

Encodes into NDN Packet Format v0.3 if Parameters element is present. In this case, Selectors are not encoded. Otherwise, encodes into NDN Packet Format v0.2.

Definition at line 202 of file interest.cpp.

References ndn::Block::hasWire().

◆ wireDecode()

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

Decode from wire in NDN Packet Format v0.2 or v0.3.

Definition at line 218 of file interest.cpp.

References getNonce(), hasNonce(), ndn::tlv::Interest, ndn::Block::parse(), setNonce(), ndn::to_string(), and ndn::Block::type().

Referenced by Interest().

◆ hasWire()

bool ndn::Interest::hasWire ( ) const

inline

Check if this instance has cached wire encoding.

Definition at line 90 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 starts with getName().toUri(). If the Interest contains selectors, they are included as a query string. Example: "/test/name?ndn.MustBeFresh=1"

Definition at line 408 of file interest.cpp.

◆ matchesName()

bool ndn::Interest::matchesName ( const Name & name ) const

Check if Interest, including selectors, matches the given name.

Parameters

name	The name to be matched. If this is a Data name, it shall contain the implicit digest component

Definition at line 418 of file interest.cpp.

References ndn::Exclude::empty(), getExclude(), getMaxSuffixComponents(), getMinSuffixComponents(), ndn::Exclude::isExcluded(), ndn::Name::isPrefixOf(), and ndn::Name::size().

◆ matchesData()

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

Check if Interest can be satisfied by data.

This method considers Name, MinSuffixComponents, MaxSuffixComponents, PublisherPublicKeyLocator, and Exclude. This method does not consider ChildSelector and MustBeFresh.

Definition at line 445 of file interest.cpp.

References ndn::Block::elements_end(), ndn::KeyLocator::empty(), ndn::Exclude::empty(), ndn::Block::find(), ndn::Name::get(), getExclude(), ndn::Data::getFullName(), ndn::Signature::getInfo(), getMaxSuffixComponents(), getMinSuffixComponents(), ndn::Data::getName(), getPublisherPublicKeyLocator(), ndn::Data::getSignature(), ndn::Exclude::isExcluded(), ndn::name::Component::isImplicitSha256Digest(), ndn::Name::isPrefixOf(), ndn::tlv::KeyLocator, ndn::Name::size(), and ndn::KeyLocator::wireEncode().

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 Interest matches other interest.

Interest matches other if both have the same name, selectors, and link. Other fields (e.g., Nonce) may be different.

Todo:: Implement distinguishing Interests by forwarding hint. The current implementation checks only name+selectors (Issue #3162).

Definition at line 529 of file interest.cpp.

References getName(), and getSelectors().

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

◆ getName()

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

inline

Definition at line 134 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(), nfd::cs::Cs::find(), ndn::security::v2::CertificateCache::find(), ndn::security::v2::TrustAnchorContainer::find(), ndn::InMemoryStorage::find(), ndn::security::v2::getKeyLocatorName(), nfd::fw::asf::AsfMeasurements::getOrCreateNamespaceInfo(), 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(), ndn::security::v2::Validator::validate(), and nfd::fw::wouldViolateScope().

◆ setName()

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

inline

Definition at line 140 of file interest.hpp.

References ndn::Block::reset().

Referenced by 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 162 of file interest.hpp.

◆ getCanBePrefix()

bool ndn::Interest::getCanBePrefix ( ) const

inline

Check whether the CanBePrefix element is present.

This is a getter for the CanBePrefix element as defined in NDN Packet Format v0.3. In this implementation, it is mapped to the closest v0.2 semantics: MaxSuffixComponents=1 means CanBePrefix is absent.

Definition at line 174 of file interest.hpp.

References ndn::Selectors::getMaxSuffixComponents().

◆ setCanBePrefix()

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

inline

Add or remove CanBePrefix element.

Parameters

canBePrefix whether CanBePrefix element should be present.

This is a setter for the CanBePrefix element as defined in NDN Packet Format v0.3. In this implementation, it is mapped to the closest v0.2 semantics: MaxSuffixComponents=1 means CanBePrefix is absent.

Definition at line 187 of file interest.hpp.

References ndn::Block::reset(), and ndn::Selectors::setMaxSuffixComponents().

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

◆ getMustBeFresh()

bool ndn::Interest::getMustBeFresh ( ) const

inline

Check whether the MustBeFresh element is present.

This is a getter for the MustBeFresh element as defined in NDN Packet Format v0.3. In this implementation, it is mapped to the closest v0.2 semantics and appears as MustBeFresh element under Selectors.

Definition at line 202 of file interest.hpp.

References ndn::Selectors::getMustBeFresh().

Referenced by nfd::cs::Entry::canSatisfy(), ndn::operator<<(), and ndn::InMemoryStorage::selectChild().

◆ setMustBeFresh()

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

inline

Add or remove MustBeFresh element.

Parameters

mustBeFresh whether MustBeFresh element should be present.

This is a setter for the MustBeFresh element as defined in NDN Packet Format v0.3. In this implementation, it is mapped to the closest v0.2 semantics and appears as MustBeFresh element under Selectors.

Definition at line 215 of file interest.hpp.

References ndn::Block::reset(), and ndn::Selectors::setMustBeFresh().

◆ getForwardingHint()

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

inline

Definition at line 223 of file interest.hpp.

Referenced by nfd::fw::Strategy::lookupFib().

◆ setForwardingHint()

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

Definition at line 581 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 243 of file interest.hpp.

References ndn::Block::reset().

◆ hasNonce()

bool ndn::Interest::hasNonce ( ) const

inline

Check if the Nonce element is present.

Definition at line 253 of file interest.hpp.

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

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

References ndn::random::generateWord32().

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

◆ setNonce()

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

Set nonce value.

Definition at line 548 of file interest.cpp.

References ndn::Block::reset().

Referenced by refreshNonce(), and wireDecode().

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

References ndn::random::generateWord32(), getNonce(), hasNonce(), and setNonce().

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

◆ getInterestLifetime()

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

inline

Definition at line 279 of file interest.hpp.

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

◆ setInterestLifetime()

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

Set Interest's lifetime.

Exceptions

std::invalid_argument lifetime is negative

Definition at line 570 of file interest.cpp.

References ndn::Block::reset().

◆ hasParameters()

bool ndn::Interest::hasParameters ( ) const

inline

Definition at line 291 of file interest.hpp.

References ndn::Block::empty().

Referenced by wireEncode().

◆ getParameters()

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

inline

Definition at line 297 of file interest.hpp.

◆ setParameters() [1/3]

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

Set parameters from a Block.

If the block's TLV-TYPE is Parameters, it will be used directly as this Interest's Parameters element. If the block's TLV-TYPE is not Parameters, it will be nested into a Parameters element.

Returns: a reference to this Interest

Definition at line 589 of file interest.cpp.

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

◆ setParameters() [2/3]

Interest & ndn::Interest::setParameters	(	const uint8_t *	buffer,
		size_t	bufferSize
	)

Copy parameters from raw buffer.

Parameters

buffer	pointer to the first octet of parameters
bufferSize	size of the raw buffer

Returns: a reference to this Interest

Definition at line 602 of file interest.cpp.

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

◆ setParameters() [3/3]

Interest & ndn::Interest::setParameters ( ConstBufferPtr buffer )

Set parameters from a wire buffer.

Parameters

buffer containing the Interest parameters

Returns: a reference to this Interest

Definition at line 610 of file interest.cpp.

References ndn::tlv::Parameters, and ndn::Block::reset().

◆ unsetParameters()

Interest & ndn::Interest::unsetParameters ( )

Remove the Parameters element from this Interest.

Postcondition: hasParameters() == false

Definition at line 618 of file interest.cpp.

References ndn::Block::reset().

◆ hasSelectors()

bool ndn::Interest::hasSelectors ( ) const

inline

Check if Interest has any selector present.

Definition at line 340 of file interest.hpp.

References ndn::Selectors::empty().

◆ getSelectors()

const Selectors& ndn::Interest::getSelectors ( ) const

inline

Definition at line 347 of file interest.hpp.

Referenced by nfd::pit::Entry::canMatch(), and matchesInterest().

◆ setSelectors()

Interest& ndn::Interest::setSelectors ( const Selectors & selectors )

inline

Definition at line 354 of file interest.hpp.

References ndn::Block::reset().

◆ getMinSuffixComponents()

int ndn::Interest::getMinSuffixComponents ( ) const

inline

Definition at line 363 of file interest.hpp.

References ndn::Selectors::getMinSuffixComponents().

Referenced by matchesData(), matchesName(), and ndn::operator<<().

◆ setMinSuffixComponents()

Interest& ndn::Interest::setMinSuffixComponents ( int minSuffixComponents )

inline

Definition at line 370 of file interest.hpp.

References ndn::Block::reset(), and ndn::Selectors::setMinSuffixComponents().

◆ getMaxSuffixComponents()

int ndn::Interest::getMaxSuffixComponents ( ) const

inline

Definition at line 379 of file interest.hpp.

References ndn::Selectors::getMaxSuffixComponents().

Referenced by matchesData(), matchesName(), and ndn::operator<<().

◆ setMaxSuffixComponents()

Interest& ndn::Interest::setMaxSuffixComponents ( int maxSuffixComponents )

inline

Definition at line 386 of file interest.hpp.

References ndn::Block::reset(), and ndn::Selectors::setMaxSuffixComponents().

◆ getPublisherPublicKeyLocator()

const KeyLocator& ndn::Interest::getPublisherPublicKeyLocator ( ) const

inline

Definition at line 395 of file interest.hpp.

References ndn::Selectors::getPublisherPublicKeyLocator().

Referenced by matchesData().

◆ setPublisherPublicKeyLocator()

Interest& ndn::Interest::setPublisherPublicKeyLocator ( const KeyLocator & keyLocator )

inline

Definition at line 402 of file interest.hpp.

References ndn::Block::reset(), and ndn::Selectors::setPublisherPublicKeyLocator().

◆ getExclude()

const Exclude& ndn::Interest::getExclude ( ) const

inline

Definition at line 411 of file interest.hpp.

References ndn::Selectors::getExclude().

Referenced by matchesData(), matchesName(), and ndn::operator<<().

◆ setExclude()

Interest& ndn::Interest::setExclude ( const Exclude & exclude )

inline

Definition at line 418 of file interest.hpp.

References ndn::Block::reset(), and ndn::Selectors::setExclude().

◆ getChildSelector()

int ndn::Interest::getChildSelector ( ) const

inline

Definition at line 427 of file interest.hpp.

References ndn::Selectors::getChildSelector().

Referenced by nfd::cs::Cs::find(), ndn::operator<<(), and ndn::InMemoryStorage::selectChild().

◆ setChildSelector()

Interest& ndn::Interest::setChildSelector ( int childSelector )

inline

Definition at line 434 of file interest.hpp.

References ndn::Block::reset(), and ndn::Selectors::setChildSelector().

Friends And Related Function Documentation

◆ operator==

bool operator==	(	const Interest &	lhs,
		const Interest &	rhs
	)

friend

Definition at line 628 of file interest.cpp.

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

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Interest() [1/2]

◆ Interest() [2/2]

Member Function Documentation

◆ wireEncode() [1/2]

◆ wireEncode() [2/2]

◆ wireDecode()

◆ hasWire()

◆ toUri()

◆ matchesName()

◆ matchesData()

◆ matchesInterest()

◆ getName()

◆ setName()

◆ setDefaultCanBePrefix()

◆ getCanBePrefix()

◆ setCanBePrefix()

◆ getMustBeFresh()

◆ setMustBeFresh()

◆ getForwardingHint()

◆ setForwardingHint()

◆ modifyForwardingHint()

◆ hasNonce()

◆ getNonce()

◆ setNonce()

◆ refreshNonce()

◆ getInterestLifetime()

◆ setInterestLifetime()

◆ hasParameters()

◆ getParameters()

◆ setParameters() [1/3]

◆ setParameters() [2/3]

◆ setParameters() [3/3]

◆ unsetParameters()

◆ hasSelectors()

◆ getSelectors()

◆ setSelectors()

◆ getMinSuffixComponents()

◆ setMinSuffixComponents()

◆ getMaxSuffixComponents()

◆ setMaxSuffixComponents()

◆ getPublisherPublicKeyLocator()

◆ setPublisherPublicKeyLocator()

◆ getExclude()

◆ setExclude()

◆ getChildSelector()

◆ setChildSelector()

Friends And Related Function Documentation

◆ operator==