XRTLibrary-StreamFetcher2

Introduction

Asynchronize stream data fetcher module (version 2) of XRT library, an improved version of the xrtlibrary-streamfetcher library.

Installation

To install this package, you can use NPM by typing following command:

npm install xrtlibrary-streamfetcher2 --save

Then you can import this library in your JavaScript code:

const XRTLibStreamFetcher2 = require("xrtlibrary-streamfetcher2");

Examples

Download this package and see the "examples" directory.

APIs

(Constant) STMFETCHER_READPACKET

A constant used by fetcher.read() method if a packet is wanted.

(Class) StreamFetcher

Stream fetcher.

Extend(s):

• EventEmitter

new StreamFetcher()

Construct a new object.

(Event) 'change'

Emitted when the size of buffered data changes.

fetcher.getBufferedDataSize()

Get the size of buffered data.

Return value:

• (Number) The size.

fetcher.read(count, [cancellator])

Read data.

Exception(s):

• (StreamFetcher.OperationCancelledError) Raised when the cancellator was activated.
• (StreamFetcher.EndOfStreamError) Raised when the stream was ended.
• (StreamFetcher.InvalidOperationError) Raised when one of following situation(s) occurred:
  • The "count" parameter is incorrect.

Parameter(s):

• count (Number): The byte count of the data (the count or STMFETCHER_READPACKET to read a packet).
• cancellator (ConditionalSynchronizer): The cancellator.

Return value:

• (Promise<Buffer>) The promise object (resolves with the data when succeed, rejects when error occurred).

fetcher.readNoCopy(count, [bufferList], [partial], [cancellator])

Read data with zero-copy mechanism.

Note(s):

• Buffer that has been read would be pushed to the buffer list, the buffer list returned by this function is exactly the same as the one specified by the "bufferList" parameter.
• If the buffer list specified is not empty, it would be cleared.
• Zero-copy mechanism is used by this method to avoid data copying.
• If the value of "partial" parameter is true, this method would return even when only partial data was available. Otherwise (by default), this method would wait until all bytes are available.

Exception(s):

• (StreamFetcher.OperationCancelledError) Raised when the cancellator was activated.
• (StreamFetcher.EndOfStreamError) Raised when the stream was ended.
• (StreamFetcher.InvalidOperationError) Raised when one of following situation(s) occurred:
  • The "count" parameter is incorrect.

Parameter(s):

• count (Number): The byte count of the data (the count or STMFETCHER_READPACKET to read a packet).
• bufferList (Buffer[]): The buffer list.
• partial (Boolean): True if partial data is allowed.
• cancellator (ConditionalSynchronizer): The cancellator.

Return value:

• (Promise<Buffer[]>) The promise object (resolves with the buffer list when succeed, rejects when error occurred).

fetcher.unread(data)

Unread data (rollback the stream).

Exception(s):

• (StreamFetcher.EndOfStreamError) Raised when the stream was ended.

Parameter(s):

• data (Buffer): The data.

fetcher.write(data)

Write data.

Note(s):

• This method can only be called before calling fetcher.end() method.

Exception(s):

• (StreamFetcher.EndOfStreamError) Raised when the stream was ended.

Parameter(s):

• data (Buffer): The data.

fetcher.whenData([cancellator])

Wait for data.

Exception(s):

• StreamFetcher.OperationCancelledError: Raised if the cancellator was activated.

Return value:

• (Promise) The promise object (resolves when data is coming, rejects if error occurred).

fetcher.whenDrain([cancellator])

Wait for the internal buffer to be drained.

Exception(s):

• StreamFetcher.OperationCancelledError: Raised if the cancellator was activated.

Return value:

• (Promise) The promise object (resolves when buffer drained, rejects if error occurred).

fetcher.whenEnded([cancellator])

Wait for the stream to be ended.

Exception(s):

• StreamFetcher.OperationCancelledError: Raised if the cancellator was activated.

Return value:

• (Promise) The promise object (resolves when stream ended, rejects if error occurred).

fetcher.isEnded()

Get whether the stream was ended.

Return value:

• (Boolean) True if so.

fetcher.end()

End the stream.

Exception(s):

• StreamFetcher.EndOfStreamError: Raised when the stream was ended.

(Class) StreamFetcher.Error

Stream fetcher error.

Extend(s):

• Error

(Class) StreamFetcher.EndOfStreamError

Stream fetcher end of stream error.

Extend(s):

• StreamFetcher.Error

(Class) StreamFetcher.InvalidOperationError

Stream fetcher invalid operation error.

Extend(s):

• StreamFetcher.Error

(Class) StreamFetcher.OperationCancelledError

Stream fetcher operation cancelled error.

Extend(s):

• StreamFetcher.Error