new SegmentFetcher(face, validatorKeyChain, verifySegment, onComplete, onError)
SegmentFetcher is a utility class to fetch the latest version of segmented data.
SegmentFetcher assumes that the data is named ///,
where:
- is the specified name prefix,
- is an unknown version that needs to be discovered, and
- 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:
1. Express the first Interest to discover the version:
>> Interest: /?ChildSelector=1&MustBeFresh=true
2. Infer the latest version of the Data: = Data.getName().get(-2)
3. If the segment number in the retrieved packet == 0, go to step 5.
4. Send an Interest for segment 0:
>> Interest: ///
5. Keep sending Interests for the next segment while the retrieved Data does
not have a FinalBlockId or the FinalBlockId != Data.getName().get(-1).
>> Interest: ///
6. 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.
- `IO_ERROR`: for I/O errors when sending an Interest.
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 null.
Example:
var onComplete = function(content) { ... }
var onError = function(errorCode, message) { ... }
var interest = new Interest(new Name("/data/prefix"));
interest.setInterestLifetimeMilliseconds(1000);
SegmentFetcher.fetch(face, interest, null, onComplete, onError);
This is a private constructor to create a new SegmentFetcher to use the Face.
An application should use SegmentFetcher.fetch. If validatorKeyChain is not
null, use it and ignore verifySegment. After creating the SegmentFetcher,
call fetchFirstSegment.
Parameters:
| Name | Type | Description |
|---|---|---|
face |
Face | This calls face.expressInterest to fetch more segments. |
validatorKeyChain |
KeyChain | If this is not null, use its verifyData instead of the verifySegment callback. |
verifySegment |
function | When a Data packet is received this calls verifySegment(data) where data is a Data object. If it returns False then abort fetching and call onError with SegmentFetcher.ErrorCode.SEGMENT_VERIFICATION_FAILED. 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 |
function | When all segments are received, call onComplete(content) where content is a Blob which has 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 |
function | Call onError.onError(errorCode, message) for timeout or an error processing segments. errorCode is a value from SegmentFetcher.ErrorCode and message is a related string. 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. |
- Source:
Members
(static) ErrorCode
An ErrorCode value is passed in the onError callback.
- Source:
Methods
(static) DontVerifySegment()
DontVerifySegment may be used in fetch to skip validation of Data packets.
- Source:
(static) endsWithSegmentNumber(name) → {boolean}
Check if the last component in the name is a segment number.
Parameters:
| Name | Type | Description |
|---|---|---|
name |
Name | The name to check. |
- Source:
Returns:
True if the name ends with a segment number, otherwise false.
- Type
- boolean
(static) fetch(face, baseInterest, validatorKeyChain, verifySegment, onComplete, onError)
Initiate segment fetching. For more details, see the documentation for the
class. There are two forms of fetch:
fetch(face, baseInterest, validatorKeyChain, onComplete, onError)
and
fetch(face, baseInterest, verifySegment, onComplete, onError)
Parameters:
| Name | Type | Description |
|---|---|---|
face |
Face | This calls face.expressInterest to fetch more segments. |
baseInterest |
Interest | 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 |
KeyChain | When a Data packet is received this calls validatorKeyChain.verifyData(data). If validation fails then abortfetching 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. |
verifySegment |
function | When a Data packet is received this calls verifySegment(data) where data is a Data object. If it returns False then abort fetching and call onError with SegmentFetcher.ErrorCode.SEGMENT_VERIFICATION_FAILED. If data validation is not required, use SegmentFetcher.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 |
function | When all segments are received, call onComplete(content) where content is a Blob which has 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 |
function | Call onError.onError(errorCode, message) for timeout or an error processing segments. errorCode is a value from SegmentFetcher.ErrorCode and message is a related string. 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. |
- Source: