Utility class to fetch the latest version of a segmented object. More...

#include <segment-fetcher.hpp>

Inheritance diagram for ndn::util::SegmentFetcher:

Collaboration diagram for ndn::util::SegmentFetcher:

[legend]

Classes
class	Options

Public Types
enum	ErrorCode { INTEREST_TIMEOUT = 1, DATA_HAS_NO_SEGMENT = 2, SEGMENT_VALIDATION_FAIL = 3, NACK_ERROR = 4, FINALBLOCKID_NOT_SEGMENT = 5 }
	Error codes passed to onError. More...

Public Member Functions
void	stop ()
	Stops fetching. More...

Static Public Member Functions
static shared_ptr< SegmentFetcher >	start (Face &face, const Interest &baseInterest, security::Validator &validator, const Options &options=Options())
	Initiates segment fetching. More...

Public Attributes
Signal< SegmentFetcher, ConstBufferPtr >	onComplete
	Emitted upon successful retrieval of the complete object (all segments). More...

Signal< SegmentFetcher, uint32_t, std::string >	onError
	Emitted when the retrieval could not be completed due to an error. More...

Signal< SegmentFetcher, Data >	afterSegmentReceived
	Emitted whenever a data segment received. More...

Signal< SegmentFetcher, Data >	afterSegmentValidated
	Emitted whenever a received data segment has been successfully validated. More...

Signal< SegmentFetcher >	afterSegmentNacked
	Emitted whenever an Interest for a data segment is nacked. More...

Signal< SegmentFetcher >	afterSegmentTimedOut
	Emitted whenever an Interest for a data segment times out. More...

Signal< SegmentFetcher, ConstBufferPtr >	onInOrderData
	Emitted after each data segment in segment order has been validated. More...

Signal< SegmentFetcher >	onInOrderComplete
	Emitted on successful retrieval of all segments in 'in order' mode. More...

Detailed Description

Utility class to fetch the latest version of a segmented object.

SegmentFetcher assumes that segments in the object are named /<prefix>/<version>/<segment>, where:

<prefix> is the specified prefix,
<version> is an unknown version that needs to be discovered, and
<segment> is a segment number (the number of segments in the object is unknown until a Data packet containing the FinalBlockId field is received).

SegmentFetcher implements the following logic:

Express an Interest to discover the latest version of the object:

Interest: /<prefix>?CanBePrefix&MustBeFresh
Infer the latest version of the object: <version> = Data.getName().get(-2).
Keep sending Interests for future segments until an error occurs or the number of segments indicated by the FinalBlockId in a received Data packet is reached. This retrieval will start at segment 1 if segment 0 was received in response to the Interest expressed in step 2; otherwise, retrieval will start at segment 0. By default, congestion control will be used to manage the Interest window size. Interests expressed in this step will follow this Name format: /<prefix>/<version>/<segment=(N)>.
If set to 'block' mode, signal onComplete passing a memory buffer that combines the content of all segments in the object. If set to 'in order' mode, signal onInOrderData is triggered upon validation of each segment in segment order, storing later segments that arrived out of order internally until all earlier segments have arrived and have been validated.

If an error occurs during the fetching process, onError is signaled with one of the error codes from SegmentFetcher::ErrorCode.

A Validator instance must be specified to validate individual segments. Every time a segment has been successfully validated, afterSegmentValidated will be signaled.

Example:

auto fetcher = SegmentFetcher::start(face, Interest("/data/prefix"), validator);
fetcher->onComplete.connect([] (ConstBufferPtr data) {...});
fetcher->onError.connect([] (uint32_t errorCode, const std::string& errorMsg) {...});

Definition at line 80 of file segment-fetcher.hpp.

Member Enumeration Documentation

◆ ErrorCode

enum ndn::util::SegmentFetcher::ErrorCode

Error codes passed to onError.

Enumerator
INTEREST_TIMEOUT	Retrieval timed out because the maximum timeout between the successful receipt of segments was exceeded.
DATA_HAS_NO_SEGMENT	One of the retrieved Data packets lacked a segment number in the last Name component (excl. implicit digest)
SEGMENT_VALIDATION_FAIL	One of the retrieved segments failed user-provided validation.
NACK_ERROR	An unrecoverable Nack was received during retrieval.
FINALBLOCKID_NOT_SEGMENT	A received FinalBlockId did not contain a segment component.

Definition at line 86 of file segment-fetcher.hpp.

Member Function Documentation

◆ start()

shared_ptr< SegmentFetcher > ndn::util::SegmentFetcher::start	(	Face &	face,
		const Interest &	baseInterest,
		security::Validator &	validator,
		const Options &	options = `Options()`
	)

static

Initiates segment fetching.

Transfer completion, failure, and progress are indicated via signals.

Parameters

face	Reference to the Face that should be used to fetch data.
baseInterest	Interest for the initial segment of requested data. This interest may include a custom InterestLifetime and parameters that will propagate to all subsequent Interests. The only exception is that the initial Interest will be forced to include the "CanBePrefix=true" and "MustBeFresh=true" parameters, which will not be included in subsequent Interests.
validator	Reference to the Validator the fetcher will use to validate data. The caller must ensure the validator remains valid until either onComplete or onError has been signaled.
options	Options controlling the transfer.

Returns: A shared_ptr to the constructed SegmentFetcher. This shared_ptr is kept internally for the lifetime of the transfer. Therefore, it does not need to be saved and is provided here so that the SegmentFetcher's signals can be connected to.

Definition at line 77 of file segment-fetcher.cpp.

Referenced by ndn::nfd::Controller::~Controller().

◆ stop()

void ndn::util::SegmentFetcher::stop ( )

Stops fetching.

This cancels all interests that are still pending.

Definition at line 89 of file segment-fetcher.cpp.

References afterSegmentNacked, afterSegmentReceived, afterSegmentTimedOut, afterSegmentValidated, ndn::OBufferStream::buf(), ndn::lp::CONGESTION, DATA_HAS_NO_SEGMENT, ndn::lp::DUPLICATE, FINALBLOCKID_NOT_SEGMENT, ndn::Name::get(), ndn::PacketBase::getCongestionMark(), ndn::Data::getContent(), ndn::Data::getFinalBlock(), ndn::Data::getName(), ndn::Interest::getName(), ndn::Name::getPrefix(), ndn::lp::Nack::getReason(), INTEREST_TIMEOUT, ndn::name::Component::isSegment(), nonstd::optional_lite::std11::move(), NACK_ERROR, ns3::ndn::Name, ndn::time::steady_clock::now(), onComplete, onError, onInOrderComplete, onInOrderData, ndn::Interest::refreshNonce(), SEGMENT_VALIDATION_FAIL, ndn::Interest::setCanBePrefix(), ndn::Interest::setInterestLifetime(), ndn::Interest::setMustBeFresh(), ndn::Interest::setName(), nonstd::span_lite::size(), websocketpp::transport::error::timeout, ndn::name::Component::toSegment(), ndn::Block::value_begin(), ndn::Block::value_end(), and ndn::Block::value_size().

Member Data Documentation

◆ onComplete

Signal<SegmentFetcher, ConstBufferPtr> ndn::util::SegmentFetcher::onComplete

Emitted upon successful retrieval of the complete object (all segments).

Note: Emitted only if SegmentFetcher is operating in 'block' mode.

Definition at line 235 of file segment-fetcher.hpp.

Referenced by stop().

◆ onError

Signal<SegmentFetcher, uint32_t, std::string> ndn::util::SegmentFetcher::onError

Emitted when the retrieval could not be completed due to an error.

Handlers are provided with an error code and a string error message.

Definition at line 242 of file segment-fetcher.hpp.

Referenced by stop().

◆ afterSegmentReceived

Signal<SegmentFetcher, Data> ndn::util::SegmentFetcher::afterSegmentReceived

Emitted whenever a data segment received.

Definition at line 247 of file segment-fetcher.hpp.

Referenced by stop().

◆ afterSegmentValidated

Signal<SegmentFetcher, Data> ndn::util::SegmentFetcher::afterSegmentValidated

Emitted whenever a received data segment has been successfully validated.

Definition at line 252 of file segment-fetcher.hpp.

Referenced by stop().

◆ afterSegmentNacked

Signal<SegmentFetcher> ndn::util::SegmentFetcher::afterSegmentNacked

Emitted whenever an Interest for a data segment is nacked.

Definition at line 257 of file segment-fetcher.hpp.

Referenced by stop().

◆ afterSegmentTimedOut

Signal<SegmentFetcher> ndn::util::SegmentFetcher::afterSegmentTimedOut

Emitted whenever an Interest for a data segment times out.

Definition at line 262 of file segment-fetcher.hpp.

Referenced by stop().

◆ onInOrderData

Signal<SegmentFetcher, ConstBufferPtr> ndn::util::SegmentFetcher::onInOrderData

Emitted after each data segment in segment order has been validated.

Note: Emitted only if SegmentFetcher is operating in 'in order' mode.

Definition at line 268 of file segment-fetcher.hpp.

Referenced by stop().

◆ onInOrderComplete

Signal<SegmentFetcher> ndn::util::SegmentFetcher::onInOrderComplete

Emitted on successful retrieval of all segments in 'in order' mode.

Note: Emitted only if SegmentFetcher is operating in 'in order' mode.

Definition at line 274 of file segment-fetcher.hpp.

Referenced by stop().

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

ndnSIM/ndn-cxx/ndn-cxx/util/segment-fetcher.hpp
ndnSIM/ndn-cxx/ndn-cxx/util/segment-fetcher.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Member Enumeration Documentation

◆ ErrorCode

Member Function Documentation

◆ start()

◆ stop()

Member Data Documentation

◆ onComplete

◆ onError

◆ afterSegmentReceived

◆ afterSegmentValidated

◆ afterSegmentNacked

◆ afterSegmentTimedOut

◆ onInOrderData

◆ onInOrderComplete