ndn::util::SegmentFetcher Class Reference

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:

Classes
class	Options

Public Types
typedef function< void(ConstBufferPtr data)>	CompleteCallback
typedef function< void(uint32_t code, const std::string &msg)>	ErrorCallback
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...

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

Public Attributes
Signal< SegmentFetcher >	afterSegmentNacked
	Emits whenever an Interest for a data segment is nacked. More...
Signal< SegmentFetcher, Data >	afterSegmentReceived
	Emits whenever a data segment received. More...
Signal< SegmentFetcher >	afterSegmentTimedOut
	Emits whenever an Interest for a data segment times out. More...
Signal< SegmentFetcher, Data >	afterSegmentValidated
	Emits whenever a received data segment has been successfully validated. More...
Signal< SegmentFetcher, ConstBufferPtr >	onComplete
	Emits upon successful retrieval of the complete data. More...
Signal< SegmentFetcher, uint32_t, std::string >	onError
	Emits when the retrieval could not be completed due to an error. 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 receieved.)

The following logic is implemented in SegmentFetcher:

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

Interest: /<prefix>?ndn.CanBePrefix=true&ndn.MustBeFresh=true

1. Infer the latest version of the object: <version> = Data.getName().get(-2)
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:

Interest: /<prefix>/<version>/<segment=(N)>

1. Signal onComplete with a memory block that combines the content of all segments in the object.

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, afterValidationSuccess will be signaled. If a segment fails validation, afterValidationFailure will be signaled.

Examples:

void
afterFetchComplete(ConstBufferPtr data)
{
  ...
}

void
afterFetchError(uint32_t errorCode, const std::string& errorMsg)
{
  ...
}

...
auto fetcher = SegmentFetcher::start(face, Interest("/data/prefix"), validator);
fetcher->onComplete.connect(bind(&afterFetchComplete, this, _1));
fetcher->onError.connect(bind(&afterFetchError, this, _1, _2));

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

Member Typedef Documentation

typedef function<void (ConstBufferPtr data)> ndn::util::SegmentFetcher::CompleteCallback

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

typedef function<void (uint32_t code, const std::string& msg)> ndn::util::SegmentFetcher::ErrorCallback

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

Member Enumeration Documentation

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 112 of file segment-fetcher.hpp.

Member Function Documentation

shared_ptr< SegmentFetcher > ndn::util::SegmentFetcher::fetch ( Face &  face, const Interest &  baseInterest, security::v2::Validator &  validator, const CompleteCallback &  completeCallback, const ErrorCallback &  errorCallback  )

static

Initiates segment fetching.

Deprecated:

Use start

Parameters

face	Reference to the Face that should be used to fetch data
baseInterest	An 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 parameters "CanBePrefix=true" and "MustBeFresh=true", which will be turned off in subsequent Interests.
validator	Reference to the Validator that should be used to validate data. Caller must ensure validator is valid until either completeCallback or errorCallback is invoked.
completeCallback	Callback to be fired when all segments are fetched
errorCallback	Callback to be fired when an error occurs (

See also

Errors)

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 97 of file segment-fetcher.cpp.

shared_ptr< SegmentFetcher > ndn::util::SegmentFetcher::fetch ( Face &  face, const Interest &  baseInterest, shared_ptr< security::v2::Validator >  validator, const CompleteCallback &  completeCallback, const ErrorCallback &  errorCallback  )

static

Initiate segment fetching.

Deprecated:

Use start

Parameters

face	Reference to the Face that should be used to fetch data
baseInterest	An 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 parameters "CanBePrefix=true" and "MustBeFresh=true", which will both be set to false in subsequent Interests.
validator	A shared_ptr to the Validator that should be used to validate data.
completeCallback	Callback to be fired when all segments are fetched
errorCallback	Callback to be fired when an error occurs (

See also

Errors)

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 115 of file segment-fetcher.cpp.

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

static

Initiates segment fetching.

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

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

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

Member Data Documentation

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

Emits whenever an Interest for a data segment is nacked.

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

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

Emits whenever a data segment received.

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

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

Emits whenever an Interest for a data segment times out.

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

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

Emits whenever a received data segment has been successfully validated.

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

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

Emits upon successful retrieval of the complete data.

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

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

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

Handler(s) are provided with an error code and a string error message.

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