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. 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 Name >	getForwardingHint () const noexcept
	Get the delegations (names) in the `ForwardingHint`. More...

std::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 Name &	getName () const noexcept
	Get the Interest name. More...

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

std::optional< SignatureInfo >	getSignatureInfo () const
	Get the `InterestSignatureInfo` element. More...

Block	getSignatureValue () const
	Get the `InterestSignatureValue` element. More...

template<typename T >
std::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 this 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...

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

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

Interest &	setApplicationParameters (span< const uint8_t > value)
	Set `ApplicationParameters` by copying from a contiguous sequence of bytes. More...

Interest &	setApplicationParameters (std::nullptr_t)=delete

Interest &	setApplicationParameters (std::string_view value)
	Set `ApplicationParameters` by copying from a string. More...

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

void	setCongestionMark (uint64_t mark)
	Set the CongestionMark tag to the specified value. More...

Interest &	setForwardingHint (std::vector< Name > value)
	Set the `ForwardingHint` delegations (names). More...

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

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

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

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

Interest &	setNonce (std::optional< Nonce > nonce)
	Set the Interest's nonce. More...

Interest &	setSignatureInfo (const SignatureInfo &info)
	Set the `InterestSignatureInfo` element. More...

Interest &	setSignatureValue (ConstBufferPtr value)
	Set `InterestSignatureValue` from a shared buffer. More...

Interest &	setSignatureValue (span< const uint8_t > value)
	Set `InterestSignatureValue` by copying from a contiguous sequence of bytes. More...

Interest &	setSignatureValue (std::nullptr_t)=delete

template<typename T >
void	setTag (std::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...

Interest &	unsetApplicationParameters ()
	Remove the `ApplicationParameters` element from this Interest. More...

void	wireDecode (const Block &wire)
	Decode from `wire`. More...

const Block &	wireEncode () 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://docs.named-data.net/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_argument name is invalid or lifetime is negative.

Warning: In certain contexts that use Interest::shared_from_this(), the Interest must be created using std::make_shared. Otherwise, shared_from_this() will throw std::bad_weak_ptr.

Definition at line 38 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(), the Interest must be created using std::make_shared. Otherwise, shared_from_this() will throw std::bad_weak_ptr.

Definition at line 44 of file interest.cpp.

Member Function Documentation

◆ extractSignedRanges()

InputBuffers ndn::Interest::extractSignedRanges ( ) const

Extract ranges of Interest covered by the signature.

Exceptions

Error Interest 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 657 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 325 of file interest.hpp.

◆ getAutoCheckParametersDigest()

static bool ndn::Interest::getAutoCheckParametersDigest ( )

inlinestatic

Definition at line 462 of file interest.hpp.

◆ getCanBePrefix()

bool ndn::Interest::getCanBePrefix ( ) const

inlinenoexcept

Check whether the CanBePrefix element is present.

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

Get the delegations (names) in the ForwardingHint.

Definition at line 227 of file interest.hpp.

◆ getHopLimit()

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

inlinenoexcept

Get the Interest's hop limit.

Definition at line 295 of file interest.hpp.

◆ getInterestLifetime()

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

noexcept

Get the Interest's lifetime.

If the InterestLifetime element is not present, returns DEFAULT_INTEREST_LIFETIME. If the InterestLifetime value is not representable in the return type, it's clamped to the nearest representable value.

Definition at line 442 of file interest.cpp.

◆ getMustBeFresh()

bool ndn::Interest::getMustBeFresh ( ) const

inlinenoexcept

Check whether the MustBeFresh element is present.

Definition at line 211 of file interest.hpp.

◆ getName()

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

inlinenoexcept

Get the Interest name.

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

◆ getSignatureInfo()

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

Get the InterestSignatureInfo element.

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

◆ getTag()

template<typename T >

std::shared_ptr< T > ndn::TagHost::getTag

inherited

Get a tag item.

Template Parameters

T	type of the tag, which must be a subclass of ndn::Tag

Return values

nullptr if no Tag of type T is stored

Definition at line 72 of file tag-host.hpp.

◆ hasApplicationParameters()

bool ndn::Interest::hasApplicationParameters ( ) const

inlinenoexcept

Return whether this Interest has any ApplicationParameters element.

Definition at line 312 of file interest.hpp.

◆ hasNonce()

bool ndn::Interest::hasNonce ( ) const

inlinenoexcept

Check if the Nonce element is present.

Definition at line 244 of file interest.hpp.

◆ hasWire()

bool ndn::Interest::hasWire ( ) const

inlinenoexcept

Check if this instance has cached wire encoding.

Definition at line 139 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 692 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 542 of file interest.cpp.

◆ matchesData()

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

Check if this Interest can be satisfied by data.

This method considers only Name (including ImplicitSha256Digest if present) and CanBePrefix to determine whether the Data satisfies the Interest.

Definition at line 319 of file interest.cpp.

◆ matchesInterest()

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

Check if this Interest matches other.

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

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

◆ removeTag()

template<typename T >

void ndn::TagHost::removeTag

inherited

Remove a tag item.

Template Parameters

T	type of the tag, which must be a subclass of ndn::Tag

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

Definition at line 98 of file tag-host.hpp.

◆ setApplicationParameters() [1/5]

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

Set ApplicationParameters from a Block.

Parameters

block TLV element 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 493 of file interest.cpp.

◆ setApplicationParameters() [2/5]

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 null

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

◆ setApplicationParameters() [3/5]

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

Set ApplicationParameters by copying from a contiguous sequence of bytes.

Parameters

value buffer 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 508 of file interest.cpp.

◆ setApplicationParameters() [4/5]

Interest& ndn::Interest::setApplicationParameters ( std::nullptr_t )

delete

◆ setApplicationParameters() [5/5]

Interest & ndn::Interest::setApplicationParameters ( std::string_view value )

Set ApplicationParameters by copying from a string.

Parameters

value string 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 514 of file interest.cpp.

◆ setAutoCheckParametersDigest()

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

inlinestatic

Definition at line 468 of file interest.hpp.

◆ setCanBePrefix()

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

Add or remove CanBePrefix element.

Parameters

canBePrefix Whether the element should be present.

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

◆ setForwardingHint()

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

Set the ForwardingHint delegations (names).

To completely remove the ForwardingHint element from the Interest, pass an empty vector.

Definition at line 392 of file interest.cpp.

◆ setHopLimit()

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

Set the Interest's hop limit.

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

Definition at line 466 of file interest.cpp.

◆ setInterestLifetime()

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

Set the Interest's lifetime.

Exceptions

std::invalid_argument lifetime is negative

Definition at line 451 of file interest.cpp.

◆ setMustBeFresh()

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

Add or remove MustBeFresh element.

Parameters

mustBeFresh Whether the element should be present.

Definition at line 382 of file interest.cpp.

◆ setName()

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

Set the Interest name.

Exceptions

std::invalid_argument name is not a valid Interest name

Definition at line 354 of file interest.cpp.

◆ setNonce()

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

Set the Interest's nonce.

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

Definition at line 419 of file interest.cpp.

◆ setSignatureInfo()

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

Set the InterestSignatureInfo element.

Definition at line 562 of file interest.cpp.

◆ setSignatureValue() [1/3]

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

Set InterestSignatureValue from a shared buffer.

Parameters

value buffer containing the TLV-VALUE of the InterestSignatureValue; must not be null

Returns: A reference to this Interest.

Exceptions

Error InterestSignatureInfo is unset

InterestSignatureInfo must be set before setting InterestSignatureValue.

Definition at line 647 of file interest.cpp.

◆ setSignatureValue() [2/3]

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

Set InterestSignatureValue by copying from a contiguous sequence of bytes.

Parameters

value buffer from which the TLV-VALUE of the InterestSignatureValue will be copied

Returns: A reference to this Interest.

Exceptions

Error InterestSignatureInfo is unset

InterestSignatureInfo must be set before setting InterestSignatureValue.

Definition at line 641 of file interest.cpp.

◆ setSignatureValue() [3/3]

Interest& ndn::Interest::setSignatureValue ( std::nullptr_t )

delete

◆ setTag()

template<typename T >

void ndn::TagHost::setTag ( std::shared_ptr< T > tag ) const

inherited

Set (add or replace) a tag item.

Template Parameters

T	type 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 84 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 the Interest's name in URI format. 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 309 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 530 of file interest.cpp.

◆ wireDecode()

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

Decode from wire.

Definition at line 142 of file interest.cpp.

◆ wireEncode() [1/2]

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

Encode into a Block.

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

ndn-cxx: NDN C++ library with eXperimental eXtensions 0.9.0 documentation

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Interest() [1/2]

◆ Interest() [2/2]

Member Function Documentation

◆ extractSignedRanges()

◆ getApplicationParameters()

◆ getAutoCheckParametersDigest()

◆ getCanBePrefix()

◆ getCongestionMark()

◆ getForwardingHint()

◆ getHopLimit()

◆ getInterestLifetime()

◆ getMustBeFresh()

◆ getName()

◆ getNonce()

◆ getSignatureInfo()

◆ getSignatureValue()

◆ getTag()

◆ hasApplicationParameters()

◆ hasNonce()

◆ hasWire()

◆ isParametersDigestValid()

◆ isSigned()

◆ matchesData()

◆ matchesInterest()

◆ refreshNonce()

◆ removeTag()

◆ setApplicationParameters() [1/5]

◆ setApplicationParameters() [2/5]

◆ setApplicationParameters() [3/5]

◆ setApplicationParameters() [4/5]

◆ setApplicationParameters() [5/5]

◆ setAutoCheckParametersDigest()

◆ setCanBePrefix()

◆ setCongestionMark()

◆ setForwardingHint()

◆ setHopLimit()

◆ setInterestLifetime()

◆ setMustBeFresh()

◆ setName()

◆ setNonce()

◆ setSignatureInfo()

◆ setSignatureValue() [1/3]

◆ setSignatureValue() [2/3]

◆ setSignatureValue() [3/3]

◆ setTag()

◆ toUri()

◆ unsetApplicationParameters()

◆ wireDecode()

◆ wireEncode() [1/2]

◆ wireEncode() [2/2]