README
# XRTLibrary-StreamFetcher
Introduction
A library that can help you deal with fetching bytes from a stream asynchronously (with Deferred or JavaScript's native Promise).
Installation
To install this package, you can use NPM by typing following command:
npm install xrtlibrary-streamfetcher --save
Then you can import this library in your JavaScript code:
var XRTLibStreamFetcher = require("xrtlibrary-streamfetcher");
API
StreamByteFetcher() class methods:
| Method | Description | Parameters | Return |
|---|---|---|---|
| readPacket() | Read a packet. | None | Deferred: Callback object. (once triggered, a StreamByteFetcherResult() object will be passed.) |
| readPacketNV() | Read a packet (with JavaScript native promise). | None | Promise<?Buffer>: The promise object (resolve with the packet data on success, resolve with NULL on stream closed. Never reject). |
| readBytes([count]) | Read bytes. | count(Number): The byte count. | Deferred: Callback object. (once triggered, a StreamByteFetcherResult() object will be passed.) |
| readBytesNV([count]) | Read bytes (with JavaScript native promise). | count(Number): The byte count. | Promise<Buffer>: The promise object (resolve with the data on success, reject when failed). |
| writePacket([data]) | Write a packet. | data(Buffer): The packet data. | None |
| end() | End the stream. | None | None |
| getBufferedPacketCount() | Get the count of buffered packets. | None | Number: The count. |
| getBufferedPacketSize() | Get the size of buffered packets. | None | Number: The size. |
StreamByteFetcher() class events:
| Event | Callback Prototype | Description |
|---|---|---|
| change | function() {} | Triggered when buffer changed. |
StreamByteFetcherResult() class methods:
| Method | Description | Parameters | Return |
|---|---|---|---|
| getError() | Get the error. | None | (Nullable)Error: The error. |
| getData() | Get the data. | None | (Nullable)Buffer: The data. |
Example
Example 1: Use deferred-style asynchronous mechanism.
See following example:
// Create a fetcher.
var fetcher = new XRTLibStreamFetcher.StreamByteFetcher();
// Bind events.
fetcher.on("change", function() {
console.log("Fetcher changed:");
console.log(" - Buffered packet count: " + fetcher.getBufferedPacketCount());
console.log(" - Buffered packet size: " + fetcher.getBufferedPacketSize());
});
// Read from the stream.
fetcher.readBytes(4).addCallback(function(result) {
console.log("Request 1:");
console.log(result.getError());
console.log(result.getData());
});
fetcher.readBytes(8).addCallback(function(result) {
console.log("Request 2:");
console.log(result.getError());
console.log(result.getData());
});
fetcher.readPacket().addCallback(function(result) {
console.log("Request 3:");
console.log(result.getError());
console.log(result.getData());
});
fetcher.readBytes(24).addCallback(function(result) {
// An error will occurred because the stream has ended.
console.log("Request 4:");
console.log(result.getError());
console.log(result.getData());
});
fetcher.readPacket().addCallback(function(result) {
// No error occurred, but got NULL as the data because the stream has ended.
console.log("Request 5:");
console.log(result.getError());
console.log(result.getData() /* Got NULL here, indicates that the stream has ended. */);
});
// Write packets to the stream.
fetcher.writePacket(Buffer.from([1, 2, 3]));
fetcher.writePacket(Buffer.from([4, 5]));
fetcher.writePacket(Buffer.from([6, 7, 8]));
fetcher.writePacket(Buffer.from([9, 10, 11, 12, 13, 14, 15, 16, 17]));
// End the stream.
fetcher.end();
Example 2: Use JavaScript's native Promise-based asynchronous mechanism.
See following example:
// Create a fetcher.
var fetcher = new XRTLibStreamFetcher.StreamByteFetcher();
// Bind events.
fetcher.on("change", function() {
console.log("Fetcher changed:");
console.log(" - Buffered packet count: " + fetcher.getBufferedPacketCount());
console.log(" - Buffered packet size: " + fetcher.getBufferedPacketSize());
});
// Read from the stream.
fetcher.readBytesNV(4).then(function(data) {
console.log("Request 1:");
console.log(data);
}, function(error) {
console.log("Request 1 failed.");
console.log(error);
});
fetcher.readBytesNV(8).then(function(data) {
console.log("Request 2:");
console.log(data);
}, function(error) {
console.log("Request 2 failed.");
console.log(error);
});
fetcher.readPacketNV().then(function(packet) {
console.log("Request 3:");
console.log(packet);
});
fetcher.readBytesNV(24).then(function(data) {
console.log("Request 4:");
console.log(data);
}, function(error) {
// An error will occurred because the stream has ended.
console.log("Request 4 failed.");
console.log(error);
});
fetcher.readPacketNV().then(function(packet) {
// Got NULL as the data because the stream has ended.
console.log("Request 5:");
console.log(packet);
});
// Write packets to the stream.
fetcher.writePacket(Buffer.from([1, 2, 3]));
fetcher.writePacket(Buffer.from([4, 5]));
fetcher.writePacket(Buffer.from([6, 7, 8]));
fetcher.writePacket(Buffer.from([9, 10, 11, 12, 13, 14, 15, 16, 17]));
// End the stream.
fetcher.end();
Warning
- Never mix Deferred and Promise.