ndn::util::SegmentFetcher Class Reference

Utility class to fetch latest version of the segmented data. More...

#include <segment-fetcher.hpp>

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

Public Types

typedef function< void(const 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
}
 Error codes that can be passed to ErrorCallback. More...
 

Static Public Member Functions

static shared_ptr< SegmentFetcherfetch (Face &face, const Interest &baseInterest, security::v2::Validator &validator, const CompleteCallback &completeCallback, const ErrorCallback &errorCallback)
 Initiates segment fetching. More...
 
static shared_ptr< SegmentFetcherfetch (Face &face, const Interest &baseInterest, shared_ptr< security::v2::Validator > validator, const CompleteCallback &completeCallback, const ErrorCallback &errorCallback)
 Initiate segment fetching. More...
 

Public Attributes

Signal< SegmentFetcher, DataafterSegmentReceived
 Emits whenever a data segment received. More...
 
Signal< SegmentFetcher, DataafterSegmentValidated
 Emits whenever a received data segment has been successfully validated. More...
 

Static Public Attributes

static const uint32_t MAX_INTEREST_REEXPRESS = 3
 Maximum number of times an interest will be reexpressed incase of NackCallback. More...
 

Detailed Description

Utility class to fetch latest version of the segmented data.

SegmentFetcher assumes that the data is 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 (number of segments is unknown and is controlled by FinalBlockId field in at least the last Data packet

The following logic is implemented in SegmentFetcher:

  1. Express first interest to discover version:

Interest: /<prefix>?ChildSelector=1&MustBeFresh=yes

  1. Infer the latest version of Data: <version> = Data.getName().get(-2)
  2. If segment number in the retrieved packet == 0, go to step 5.
  3. Send Interest for segment 0:

Interest: /<prefix>/<version>/<segment=0>

  1. Keep sending Interests for the next segment while the retrieved Data does not have FinalBlockId or FinalBlockId != Data.getName().get(-1).

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

  1. Fire onCompletion callback with memory block that combines content part from all segmented objects.

If an error occurs during the fetching process, an error callback is fired with a proper error code. The following errors are possible:

  • INTEREST_TIMEOUT: if any of the Interests times out
  • DATA_HAS_NO_SEGMENT: if any of the retrieved Data packets don't have segment as a last component of the name (not counting implicit digest)
  • SEGMENT_VALIDATION_FAIL: if any retrieved segment fails user-provided validation

In order to validate individual segments, a Validator instance needs to be specified. If the segment validation is successful, afterValidationSuccess callback is fired, otherwise afterValidationFailure callback.

Examples:

void
afterFetchComplete(const ConstBufferPtr& data)
{
  ...
}

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

...
SegmentFetcher::fetch(face, Interest("/data/prefix", 30_s),
                      validator,
                      bind(&afterFetchComplete, this, _1),
                      bind(&afterFetchError, this, _1, _2));

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

Member Typedef Documentation

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

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

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

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

Member Enumeration Documentation

Error codes that can be passed to ErrorCallback.

Enumerator
INTEREST_TIMEOUT 
DATA_HAS_NO_SEGMENT 
SEGMENT_VALIDATION_FAIL 
NACK_ERROR 

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

Parameters
faceReference to the Face that should be used to fetch data
baseInterestAn Interest for the initial segment of requested data. This interest may include custom InterestLifetime and selectors that will propagate to all subsequent Interests. The only exception is that the initial Interest will be forced to include "ChildSelector=rightmost" and "MustBeFresh=true" selectors, which will be turned off in subsequent Interests.
validatorReference to the Validator that should be used to validate data. Caller must ensure validator is valid until either completeCallback or errorCallback is invoked.
completeCallbackCallback to be fired when all segments are fetched
errorCallbackCallback to be fired when an error occurs (
See also
Errors)
Returns
A shared_ptr to the constructed SegmentFetcher

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

Parameters
faceReference to the Face that should be used to fetch data
baseInterestAn Interest for the initial segment of requested data. This interest may include custom InterestLifetime and selectors that will propagate to all subsequent Interests. The only exception is that the initial Interest will be forced to include "ChildSelector=1" and "MustBeFresh=true" selectors, which will be turned off in subsequent Interests.
validatorA shared_ptr to the Validator that should be used to validate data.
completeCallbackCallback to be fired when all segments are fetched
errorCallbackCallback to be fired when an error occurs (
See also
Errors)
Returns
A shared_ptr to the constructed SegmentFetcher

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

Member Data Documentation

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

Emits whenever a data segment received.

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

const uint32_t ndn::util::SegmentFetcher::MAX_INTEREST_REEXPRESS = 3
static

Maximum number of times an interest will be reexpressed incase of NackCallback.

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