SegmentFetcher is a utility class to the fetch latest version of segmented data. More...

#include <segment-fetcher.hpp>

Inheritance diagram for ndn::SegmentFetcher:

Public Types
enum	ErrorCode { INTEREST_TIMEOUT = 1, DATA_HAS_NO_SEGMENT = 2, SEGMENT_VERIFICATION_FAILED = 3 }

typedef func_lib::function < bool(const ptr_lib::shared_ptr< Data > &data)>	VerifySegment

typedef func_lib::function < void(const Blob &content)>	OnComplete

typedef func_lib::function < void(ErrorCode errorCode, const std::string &message)>	OnError

Static Public Member Functions
static bool	DontVerifySegment (const ptr_lib::shared_ptr< Data > &data)
	DontVerifySegment may be used in fetch to skip validation of Data packets.

static void	fetch (Face &face, const Interest &baseInterest, const VerifySegment &verifySegment, const OnComplete &onComplete, const OnError &onError)
	Initiate segment fetching. More...

static void	fetch (Face &face, const Interest &baseInterest, KeyChain *validatorKeyChain, const OnComplete &onComplete, const OnError &onError)
	Initiate segment fetching. More...

Detailed Description

SegmentFetcher is a utility class to the fetch latest version of segmented data.

SegmentFetcher assumes that the data is named /<prefix>/<version>/<segment>, where:

<prefix> is the specified name prefix,
<version> is an unknown version that needs to be discovered, and
<segment> is a segment number. (The number of segments is unknown and is controlled by the FinalBlockId field in at least the last Data packet.

The following logic is implemented in SegmentFetcher:

Express the first Interest to discover the version:

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

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

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

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

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

Call the OnComplete callback with a blob that concatenates the content from all the segmented objects.

If an error occurs during the fetching process, the OnError callback is called 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 a segment as the last component of the name (not counting the implicit digest)
SEGMENT_VERIFICATION_FAILED: if any retrieved segment fails the user-provided VerifySegment callback or KeyChain verifyData.

In order to validate individual segments, a KeyChain needs to be supplied. If verifyData fails, the fetching process is aborted with SEGMENT_VERIFICATION_FAILED. If data validation is not required, pass a null KeyChain.

Example: void onComplete(const Blob& encodedMessage);

void onError(SegmentFetcher::ErrorCode errorCode, const string& message);

Interest interest(Name("/data/prefix")); interest.setInterestLifetimeMilliseconds(1000);

SegmentFetcher.fetch(face, interest, 0, onComplete, onError);

Member Function Documentation

void ndn::SegmentFetcher::fetch	(	Face &	face,
		const Interest &	baseInterest,
		const VerifySegment &	verifySegment,
		const OnComplete &	onComplete,
		const OnError &	onError
	)

static

Initiate segment fetching.

For more details, see the documentation for the class.

Parameters

face	This calls face.expressInterest to fetch more segments.
baseInterest	An Interest for the initial segment of the requested data, where baseInterest.getName() has the name prefix. This interest may include a custom InterestLifetime and selectors that will propagate to all subsequent Interests. The only exception is that the initial Interest will be forced to include selectors "ChildSelector=1" and "MustBeFresh=true" which will be turned off in subsequent Interests.
verifySegment	When a Data packet is received this calls verifySegment(data). If it returns false then abort fetching and call onError with SEGMENT_VERIFICATION_FAILED. If data validation is not required, use DontVerifySegment. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onComplete	When all segments are received, call onComplete(content) where content is the concatenation of the content of all the segments. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onError	Call onError(errorCode, message) for timeout or an error processing segments. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

void ndn::SegmentFetcher::fetch	(	Face &	face,
		const Interest &	baseInterest,
		KeyChain *	validatorKeyChain,
		const OnComplete &	onComplete,
		const OnError &	onError
	)

static

Initiate segment fetching.

For more details, see the documentation for the class.

Parameters

face	This calls face.expressInterest to fetch more segments.
baseInterest	An Interest for the initial segment of the requested data, where baseInterest.getName() has the name prefix. This interest may include a custom InterestLifetime and selectors that will propagate to all subsequent Interests. The only exception is that the initial Interest will be forced to include selectors "ChildSelector=1" and "MustBeFresh=true" which will be turned off in subsequent Interests.
validatorKeyChain	When a Data packet is received this calls validatorKeyChain->verifyData(data). If validation fails then abort fetching and call onError with SEGMENT_VERIFICATION_FAILED. This does not make a copy of the KeyChain; the object must remain valid while fetching. If validatorKeyChain is null, this does not validate the data packet.
onComplete	When all segments are received, call onComplete(content) where content is the concatenation of the content of all the segments. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onError	Call onError(errorCode, message) for timeout or an error processing segments. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

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

include/ndn-cpp/util/segment-fetcher.hpp
src/util/segment-fetcher.cpp

Public Types

Static Public Member Functions

Detailed Description

Member Function Documentation