ndn::util::SegmentFetcher Class Reference

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

#include <ndn-cxx/util/segment-fetcher.hpp>

+ Inheritance diagram for ndn::util::SegmentFetcher:
+ Collaboration diagram for ndn::util::SegmentFetcher:

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< SegmentFetcherstart (Face &face, const Interest &baseInterest, security::v2::Validator &validator, const Options &options=Options())
 Initiates segment fetching. More...
 

Public Attributes

Signal< SegmentFetcherafterSegmentNacked
 Emits whenever an Interest for a data segment is nacked. More...
 
Signal< SegmentFetcher, DataafterSegmentReceived
 Emits whenever a data segment received. More...
 
Signal< SegmentFetcherafterSegmentTimedOut
 Emits whenever an Interest for a data segment times out. More...
 
Signal< SegmentFetcher, DataafterSegmentValidated
 Emits whenever a received data segment has been successfully validated. More...
 
Signal< SegmentFetcher, ConstBufferPtronComplete
 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 received).

SegmentFetcher implements the following logic:

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

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

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

  4. Signal onComplete passing a memory buffer 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, afterSegmentValidated will be signaled.

Example:

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

Member Enumeration Documentation

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

Member Function Documentation

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

Initiates segment fetching.

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

Parameters
faceReference to the Face that should be used to fetch data.
baseInterestInterest 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.
validatorReference 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.
optionsOptions 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 89 of file segment-fetcher.cpp.

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

Stops fetching.

This cancels all interests that are still pending.

Definition at line 101 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 271 of file segment-fetcher.hpp.

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

Emits whenever a data segment received.

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

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

Emits whenever an Interest for a data segment times out.

Definition at line 276 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 266 of file segment-fetcher.hpp.

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

Emits upon successful retrieval of the complete data.

Definition at line 249 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.

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

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