@ohos.util.stream (Stream Base Class)

The stream module provides APIs to process basic types of streams. With streams, data is read or written by chunk, instead of being loaded to the memory at a time.

There are four fundamental stream types: writable streams (Writable), readable streams (Readable), duplex streams (Duplex), and transform streams (Transform).

NOTE

The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import { stream  } from '@kit.ArkTS';

Writable

Stream to which data can be written. A writable stream allows data to be written to a target, which can be a file, an HTTP response, a standard output, another stream, or the like.

Attributes

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Name	Type	Read-Only	Optional	Description
writableObjectMode	boolean	Yes	No	Whether the writable stream works in object mode. The value true means that the stream is configured in object mode, and false means the opposite. Currently, only raw data (string and Uint8Array) is supported, and the return value is false.
writableHighWatermark	number	Yes	No	High watermark for the data volume in the buffer. This value is not customizable currently. When you call write(), if the data volume in the buffer reaches this watermark, write() will return false. The default value is 16 x 1024, in bytes.
writable	boolean	Yes	No	Whether the writable stream is currently writable. The value true means that the stream is currently writable, and false means that the stream does not accept write operations.
writableLength	number	Yes	No	Number of bytes to be written in the buffer of the writable stream.
writableCorked	number	Yes	No	Count of cork states of the writable stream. If the value is greater than 0, the writable stream buffers all writes. If the value is 0, buffering stops. You can call cork() to increment the count by one, call uncork() to decrement the count by one, and call end() to clear the count.
writableEnded	boolean	Yes	No	Whether end() has been called for the writable stream. This property does not specify whether the data has been flushed. The value true means that end() has been called, and false means the opposite.
writableFinished	boolean	Yes	No	Whether data in the writable stream has been flushed. The value true means that data in the stream has been flushed, and false means the opposite.

constructor

constructor()

A constructor used to create a Writable object.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Example

let writableStream = new stream.Writable();

write

write(chunk?: string|Uint8Array, encoding?: string, callback?: Function): boolean

Writes data to the buffer of the stream. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
chunk	string |Uint8Array	No	Data to write. It cannot be null, undefined, or an empty string.
encoding	string	No	Encoding format. The default value is ‘utf8’. Currently, ‘utf8’, ‘gb18030’, ‘gbk’, and ‘gb2312’ are supported.
callback	Function	No	Callback used to return the result. It is not called by default.

Return value

Type	Description
boolean	Whether there is space in the buffer of the writable stream. The value true means that there is still space in the buffer. The value false means that the buffer is full, and you are not advised to continue writing data.

Error codes

For details about the error codes, see Universal Error Codes and Utils Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200035	The doWrite method has not been implemented.
10200036	The stream has been ended.
10200037	The callback is invoked multiple times consecutively.

Example

class TestWritable extends stream.Writable {
  constructor() {
    super();
  }

  doWrite(chunk: string|Uint8Array, encoding: string, callback: Function) {
    console.info("Writable chunk is", chunk); // Writable chunk is test
    callback();
  }
}

let writableStream = new TestWritable();
writableStream.write('test', 'utf8');

end

end(chunk?: string|Uint8Array, encoding?: string, callback?: Function): Writable

Ends the writing process in a writable stream. This API uses an asynchronous callback to return the result.

If the value of writableCorked is greater than 0, the value is set to 0 and the remaining data in the buffer is output.

If the chunk parameter is passed, it is treated as the final data chunk and written using either the write or doWrite API, based on the current execution context.

If doWrite is used for writing, the validity check of the encoding parameter depends on doWrite.

If end is used alone (without write) and the chunk parameter is passed, the data is written through doWrite.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
chunk	string |Uint8Array	No	Data to write. The default value is undefined.
encoding	string	No	Encoding format. The default value is ‘utf8’. Currently, ‘utf8’, ‘gb18030’, ‘gbk’, and ‘gb2312’ are supported.
callback	Function	No	Callback used to return the result.

Return value

Type	Description
Writable	Current Writable object.

Error codes

For details about the error codes, see Universal Error Codes and Utils Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200035	The doWrite method has not been implemented.

Example

class TestWritable extends stream.Writable {
  constructor() {
    super();
  }

  doWrite(chunk: string|Uint8Array, encoding: string, callback: Function) {
    console.info("Writable chunk is", chunk);
    callback();
  }
/**
 * Writable chunk is test
 * Writable chunk is finish
 * */
}

let writableStream = new TestWritable();
writableStream.write('test', 'utf8');
writableStream.end('finish', 'utf8', () => {
  console.info("Writable is end"); // Writable is end
});

setDefaultEncoding

setDefaultEncoding(encoding?: string): boolean

Sets the default encoding format for the writable stream.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
encoding	string	No	Default encoding format. The default value is ‘utf8’. Currently, ‘utf8’, ‘gb18030’, ‘gbk’, and ‘gb2312’ are supported.

Return value

Type	Description
boolean	Whether the setting is successful. The value true means that the setting is successful, and false means the opposite.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

class TestWritable extends stream.Writable {
  constructor() {
    super();
  }

  doWrite(chunk: string|Uint8Array, encoding: string, callback: Function) {
    callback();
  }
}

let writableStream = new TestWritable();
let result = writableStream.setDefaultEncoding('utf8');
console.info("Writable is result", result); // Writable is result true

cork

cork(): boolean

Forces all written data to be buffered in memory. This API is called to optimize the performance of continuous write operations.

After this API is called, the value of writableCorked is incremented by one. It is recommended that this API be used in pair with uncork().

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Return value

Type	Description
boolean	Whether the corked status is successfully set. The value true means that the setting is successful, and false means the opposite.

Example

class TestWritable extends stream.Writable {
  constructor() {
    super();
  }

  doWrite(chunk: string|Uint8Array, encoding: string, callback: Function) {
    callback();
  }
}

let writableStream = new TestWritable();
let result = writableStream.cork();
console.info("Writable cork result", result); // Writable cork result true

uncork

uncork(): boolean

Flushes all data buffered, and writes the data to the target.

After this API is called, the value of writableCorked is decremented by one. If the value reaches 0, the stream is no longer in the cork state. Otherwise, the stream is still in the cork state. It is recommended that this API be used in pair with cork().

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Return value

Type	Description
boolean	Whether the corked status is successfully removed. The value true means that the corked status is successfully removed, and false means the opposite.

Example

class TestWritable extends stream.Writable {
  constructor() {
    super();
  }

  doWrite(chunk: string|Uint8Array, encoding: string, callback: Function) {
    callback();
  }
}

let writableStream = new TestWritable();
writableStream.cork();
writableStream.write('data1', 'utf8');
writableStream.write('data2', 'utf8');
writableStream.uncork();
writableStream.end();
writableStream.on('finish', () => {
  console.info("all Data is End"); // all Data is End
});

on

on(event: string, callback: Callback): void

Registers an event processing callback to listen for different events on the writable stream.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
event	string	Yes	Type of the event. The following events are supported:
callback	Callback<emitter.EventData>	Yes	Callback function used to return the event data.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

class TestWritable extends stream.Writable {
  constructor() {
    super();
  }

  doWrite(chunk: string|Uint8Array, encoding: string, callback: Function) {
    callback(new Error());
  }
}

let callbackCalled = false;
let writable = new TestWritable();
writable.on('error', () => {
  console.info("Writable event test", callbackCalled.toString()); // Writable event test false
});
writable.write('hello', 'utf8', () => {
});

off

off(event: string, callback?: Callback): void

Unregisters an event processing callback used to listen for different events on the writable stream.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
event	string	Yes	Type of the event. The following events are supported:
callback	Callback<emitter.EventData>	No	Callback function.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

class TestWritable extends stream.Writable {
  constructor() {
    super();
 }

  doWrite(chunk: string|Uint8Array, encoding: string, callback: Function) {
    callback();
  }
}

let writableStream = new TestWritable();
let testListenerCalled = false;
let testListener = () => {
  testListenerCalled = true;
};
writableStream.on('finish', testListener);
writableStream.off('finish');
writableStream.write('test');
writableStream.end();
setTimeout(() => {
  console.info("Writable off test", testListenerCalled.toString()); // Writable off test false
}, 0);

doInitialize

doInitialize(callback: Function): void

You need to implement this API but do not call it directly. It is automatically called during the initialization of the writable stream. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
callback	Function	Yes	Callback function.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

class MyWritable extends stream.Writable {
  doInitialize(callback: Function) {
    super.doInitialize(callback);
    console.info("Writable doInitialize"); // Writable doInitialize
  }

  doWrite(chunk: string|Uint8Array, encoding: string, callback: Function) {
    super.doWrite(chunk, encoding, callback);
  }
}

new MyWritable();

doWrite

doWrite(chunk: string|Uint8Array, encoding: string, callback: Function): void

A data write API. You need to implement this API but do not call it directly. This API is automatically called when data is written. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
chunk	string |Uint8Array	Yes	Data to write.
encoding	string	Yes	Encoding format. Currently, ‘utf8’, ‘gb18030’, ‘gbk’, and ‘gb2312’ are supported.
callback	Function	Yes	Callback function.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

class TestWritable extends stream.Writable {
  constructor() {
    super();
  }

  doWrite(chunk: string|Uint8Array, encoding: string, callback: Function) {
    console.info("Writable chunk is", chunk); // Writable chunk is data
    callback();
  }
}

let writableStream = new TestWritable();
writableStream.write('data', 'utf8');

doWritev

doWritev(chunks: string[]|Uint8Array[], callback: Function): void

A batch data write API. You need to implement this API but do not call it directly. This API is automatically called when data is written. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
chunks	string[] | Uint8Array[]	Yes	Data arrays to write in batches.
callback	Function	Yes	Callback function.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

class TestWritable extends stream.Writable {
  constructor() {
    super();
  }

  doWritev(chunks: string[]|Uint8Array[], callback: Function) {
    console.info("Writable chunk", chunks);
    callback();
  }
/**
 * Writable chunk data1
 * Writable chunk data2
* */
}

let writableStream = new TestWritable();
writableStream.write('data1', 'utf8');
writableStream.write('data2', 'utf8');
writableStream.uncork();
writableStream.end();

ReadableOptions

Describes the options used in the Readable constructor.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Name	Type	Mandatory	Description
encoding	string	No	Encoding format. If an invalid string is input, an exception is thrown in the Readable constructor. The following formats are supported: utf-8, UTF-8, GBK, GB2312, gb2312, GB18030, gb18030, ibm866, iso-8859-2, iso-8859-3, iso-8859-4, iso-8859-5, iso-8859-6, iso-8859-7, iso-8859-8, iso-8859-8-i, iso-8859-10, iso-8859-13, iso-8859-14, iso-8859-15, koi8-r, koi8-u, macintosh, windows-874, windows-1250, windows-1251, windows-1252, windows-1253, windows-1254, windows-1255, windows-1256, windows-1257, windows-1258, gbk, big5, euc-jp, iso-2022-jp, shift_jis, euc-kr, x-mac-cyrillic, utf-16be, and utf-16le. The default value is ‘utf-8’.

Readable

Stream from which data can be read. A readable stream is used to read data from a source, such as a file or a network socket.

Attributes

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Name	Type	Read-Only	Optional	Description
readableObjectMode	boolean	Yes	No	Whether the readable stream works in object mode. The value true means that the stream is configured in object mode, and false means the opposite. Currently, only raw data (string and Uint8Array) is supported, and the return value is false.
readable	boolean	Yes	No	Whether the readable stream is currently readable. The value true means that the stream is currently readable, and false means that no data is available to read from the stream.
readableHighWatermark	number	Yes	No	Maximum amount of data that can be stored in the buffer. The default value is 16 x 1024, in bytes.
readableFlowing	boolean |null	Yes	No	Whether the readable stream is flowing. The value true means that the stream is flowing, and false means the opposite.
readableLength	number	Yes	No	Number of bytes in the buffer.
readableEncoding	string |null	Yes	No	Encoding format. Currently, ‘utf8’, ‘gb18030’, ‘gbk’, and ‘gb2312’ are supported.
readableEnded	boolean	Yes	No	Whether the readable stream ends. The value true means that the stream has no more data to read, and false means the opposite.

constructor

constructor()

A constructor used to create a Readable object.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Example

let readableStream = new stream.Readable();

constructor

constructor(options: ReadableOptions)

A constructor used to create a Readable object.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
options	ReadableOptions	Yes	Options in the Readable constructor.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

let option : stream.ReadableOptions = {
  encoding : 'utf-8'
};
let readableStream = new stream.Readable(option);

read

read(size?: number): string|null

Reads data from the buffer of the readable stream and returns the read data. If no data is read, null is returned.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
size	number	No	Number of bytes to read. The default value is undefined.

Return value

Type	Description
string |null	Data read from the readable stream.

Error codes

For details about the error codes, see Universal Error Codes and Utils Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200038	The doRead method has not been implemented.

Example

class TestReadable extends stream.Readable {
  constructor() {
    super();
  }

  doRead(size: number) {
  }
}

let readableStream = new TestReadable();
readableStream.push('test');
readableStream.pause();
let dataChunk = readableStream.read();
console.info('Readable data is', dataChunk); // Readable data is test

resume

resume(): Readable

Resumes an explicitly paused readable stream. You can use isPaused to check whether the stream is in flowing mode.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Return value

Type	Description
Readable	Current Readable object.

Example

class TestReadable extends stream.Readable {
  constructor() {
    super();
  }

  doRead(size: number) {
  }
}

let readableStream = new TestReadable();
readableStream.resume();
console.info("Readable test resume", !readableStream.isPaused()); // After a successful switching, the log "Readable test resume true" is displayed.

pause

pause(): Readable

Pauses the readable stream in flowing mode. You can use isPaused to check whether the stream is paused.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Return value

Type	Description
Readable	Current Readable object.

Example

class TestReadable extends stream.Readable {
  constructor() {
    super();
  }

  doRead(size: number) {
  }
}

let readableStream = new TestReadable();
readableStream.pause();
console.info("Readable test pause", readableStream.isPaused()); // Readable test pause true

setEncoding

setEncoding(encoding?: string): boolean

Sets an encoding format for the readable stream.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
encoding	string	No	Encoding format. The default value is ‘utf8’. Currently, ‘utf8’, ‘gb18030’, ‘gbk’, and ‘gb2312’ are supported.

Return value

Type	Description
boolean	Whether the setting is successful. The value true means that the setting is successful, and false means the opposite.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

class TestReadable extends stream.Readable {
  constructor() {
    super();
  }

  doRead(size: number) {
  }
}

let readableStream = new TestReadable();
let result = readableStream.setEncoding('utf8');
console.info("Readable result", result); // Readable result true

isPaused

isPaused(): boolean

Checks whether the readable stream is paused. The stream is paused after pause() is called and resumes from the paused state after resume() is called.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Return value

Type	Description
boolean	Whether the stream is paused. The value true means that the stream is paused, and false means the opposite.

Example

class TestReadable extends stream.Readable {
  constructor() {
    super();
  }

  doRead(size: number) {
  }
}

let readableStream = new TestReadable();
console.info("Readable isPaused", readableStream.isPaused()); // Readable isPaused false
readableStream.pause();
console.info("Readable isPaused", readableStream.isPaused()); // Readable isPaused true

pipe

pipe(destination: Writable, options?: Object): Writable

Attaches a writable stream to the readable stream to implement automatic data transmission.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
destination	Writable	Yes	Writable stream that receives data.
options	Object	No	Reserved.

Return value

Type	Description
Writable	Current Writable object.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

class TestReadable extends stream.Readable {
  constructor() {
    super();
  }

  doRead(size: number) {
    readable.push('test');
    readable.push(null);
  }
}

class TestWritable extends stream.Writable {
  constructor() {
    super();
  }

  doWrite(chunk: string|Uint8Array, encoding: string, callback: Function) {
    console.info("Readable test pipe", chunk); // Readable test pipe test
    callback();
  }
}

let readable = new TestReadable();
let writable = new TestWritable();
readable.pipe(writable);

unpipe

unpipe(destination?: Writable): Readable

Detaches a writable stream previously attached to the readable stream.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
destination	Writable	No	Writable stream to detach. The default value is undefined.

Return value

Type	Description
Readable	Current Readable object.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

class TestReadable extends stream.Readable {
  constructor() {
    super();
  }

  doRead(size: number) {
    readable.push('test');
    readable.push(null);
  }
}

class TestWritable extends stream.Writable {
  constructor() {
    super();
  }

  doWrite(chunk: string|Uint8Array, encoding: string, callback: Function) {
    callback();
  }
}

let readable = new TestReadable();
let writable = new TestWritable();
readable.pipe(writable);
readable.unpipe(writable);
readable.on('data', () => {
  console.info("Readable test unpipe data event called");
});
// After successful detaching, the data event is not triggered and "Readable test unpipe data event called" is not printed.

on

on(event: string, callback: Callback): void

Registers an event processing callback to listen for different events on the readable stream.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
event	string	Yes	Type of the event. The following events are supported:
callback	Callback<emitter.EventData>	Yes	Callback function used to return the event data.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

class TestReadable extends stream.Readable {
  constructor() {
    super();
  }

  doRead(size: number) {
    throw new Error('Simulated error');
  }
}

let readable = new TestReadable();
readable.push('test');
readable.on('error', () => {
  console.info("error event called"); // error event called
});

off

off(event: string, callback?: Callback): void

Unregisters an event processing callback used to listen for different events on the readable stream.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
event	string	Yes	Type of the event. The following events are supported:
callback	Callback<emitter.EventData>	No	Callback function.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

class TestReadable extends stream.Readable {
  constructor() {
    super();
  }

  doRead(size: number) {
  }
}

let readable = new TestReadable();

function read() {
  console.info("read() called");
}

readable.setEncoding('utf8');
readable.on('readable', read);
readable.off('readable');
readable.push('test');
// After off is used to unregister the listening of the readable stream events, the read function is not called and "read() called" is not printed.

doInitialize

doInitialize(callback: Function): void

You need to implement this API. It is called when the readable stream calls on for the first time. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
callback	Function	Yes	Callback function.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

class MyReadable extends stream.Readable {
  doInitialize(callback: Function) {
    super.doInitialize(callback);
    console.info("Readable doInitialize"); // Readable doInitialize
}

  doRead(size: number) {
  }
}

let myReadable = new MyReadable();
myReadable.on('data', () => {
});

doRead

doRead(size: number): void

A data read API that needs to be implemented in child classes.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
size	number	Yes	Number of bytes to read.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

class TestReadable extends stream.Readable {
  constructor() {
    super();
  }

  doRead(size: number) {
    console.info("doRead called"); // doRead called
  }
}

let readable = new TestReadable();
readable.on('data', () => {
});

push

push(chunk: Uint8Array|string|null, encoding?: string): boolean

Pushes data into the buffer of the readable stream.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
chunk	Uint8Array |string |null	Yes	Data to read.
encoding	string	No	Encoding format. The default value is ‘utf8’. Currently, ‘utf8’, ‘gb18030’, ‘gbk’, and ‘gb2312’ are supported.

Return value

Type	Description
boolean	Whether there is space in the buffer of the readable stream. The value true means that there is still space in the buffer, and false means that the buffer is full. If null is passed, false is always returned, indicating that no data chunk is available for pushing.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

class TestReadable extends stream.Readable {
  constructor() {
    super();
  }

  doRead(size: number) {
  }
}

let readable = new TestReadable();
let testData = 'Hello world';
readable.push(testData);
console.info("Readable push test", readable.readableLength); // Readable push test 11

Duplex

A stream that is both readable and writable. A duplex stream allows data to be transmitted in two directions, that is, data can be read and written. The Duplex class inherits from Readable and supports all the APIs in Readable.

Attributes

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Name	Type	Read-Only	Optional	Description
writableObjectMode	boolean	Yes	No	Whether the writable side of the duplex stream works in object mode. The value true means that the writable side of the stream is configured in object mode, and false means the opposite. Currently, only raw data (string and Uint8Array) is supported, and the return value is false.
writableHighWatermark	number	Yes	No	High watermark for the data volume in the buffer of the duplex stream in write mode. This value is not customizable currently. When you call write(), if the data volume in the buffer reaches this watermark, write() will return false. The default value is 16 x 1024, in bytes.
writable	boolean	Yes	No	Whether the duplex stream is currently writable. The value true means that the stream is currently writable, and false means that the stream does not accept write operations.
writableLength	number	Yes	No	Number of bytes to be written in the buffer of the duplex stream.
writableCorked	number	Yes	No	Count of cork states of the duplex stream. If the value is greater than 0, the duplex stream buffers all writes. If the value is 0, buffering stops. You can call cork() to increment the count by one, call uncork() to decrement the count by one, and call end() to clear the count.
writableEnded	boolean	Yes	No	Whether end() has been called for the duplex stream. This property does not specify whether the data has been flushed. The value true means that end() has been called, and false means the opposite.
writableFinished	boolean	Yes	No	Whether data in the duplex stream has been flushed. The value true means that data in the stream has been flushed, and false means the opposite.

constructor

constructor()

A constructor used to create a Duplex object.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Example

let duplex = new stream.Duplex();

write

write(chunk?: string|Uint8Array, encoding?: string, callback?: Function): boolean

Writes data to the buffer of the stream. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
chunk	string |Uint8Array	No	Data to write. It cannot be null, undefined, or an empty string.
encoding	string	No	Encoding format. The default value is ‘utf8’. Currently, ‘utf8’, ‘gb18030’, ‘gbk’, and ‘gb2312’ are supported.
callback	Function	No	Callback used to return the result. It is not called by default.

Return value

Type	Description
boolean	Whether there is space in the buffer of the writable stream. The value true means that there is still space in the buffer. The value false means that the buffer is full, and you are not advised to continue writing data.

Error codes

For details about the error codes, see Universal Error Codes and Utils Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200036	The stream has been ended.
10200037	The callback is invoked multiple times consecutively.
10200039	The doTransform method has not been implemented for a class that inherits from Transform.

Example

class TestDuplex extends stream.Duplex {
  constructor() {
    super();
  }

  doRead(size: number) {
  }

  doWrite(chunk: string|Uint8Array, encoding: string, callback: Function) {
    console.info("duplexStream chunk is", chunk); // duplexStream chunk is test
    callback();
  }
}

let duplexStream = new TestDuplex();
let result = duplexStream.write('test', 'utf8');
console.info("duplexStream result", result); // duplexStream result true

end

end(chunk?: string|Uint8Array, encoding?: string, callback?: Function): Writable

Ends the writing process in a duplex stream. This API uses an asynchronous callback to return the result.

If the value of writableCorked is greater than 0, the value is set to 0 and the remaining data in the buffer is output.

If the chunk parameter is passed, it is treated as the final data chunk and written using either the write or doWrite API, based on the current execution context.

If doWrite is used for writing, the validity check of the encoding parameter depends on doWrite.

If end is used alone (without write) and the chunk parameter is passed, the data is written through doWrite.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
chunk	string |Uint8Array	No	Data to write. The default value is undefined.
encoding	string	No	Encoding format. The default value is ‘utf8’. Currently, ‘utf8’, ‘gb18030’, ‘gbk’, and ‘gb2312’ are supported.
callback	Function	No	Callback used to return the result. It is not called by default.

Return value

Type	Description
Writable	Current Duplex object.

Error codes

For details about the error codes, see Universal Error Codes and Utils Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200039	The doTransform method has not been implemented for a class that inherits from Transform.

Example

class TestDuplex extends stream.Duplex {
  constructor() {
    super();
  }

  doRead(size: number) {
  }

  doWrite(chunk: string|Uint8Array, encoding: string, callback: Function) {
  console.info("Duplex chunk is", chunk); // Duplex chunk is test
  callback();
  }
}

let duplexStream = new TestDuplex();
duplexStream.end('test', 'utf8', () => {
  console.info("Duplex is end"); // Duplex is end
});

setDefaultEncoding

setDefaultEncoding(encoding?: string): boolean

Sets the default encoding format for the duplex stream so that characters can be correctly parsed when data is read.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
encoding	string	No	Encoding format. The default value is ‘utf8’. Currently, ‘utf8’, ‘gb18030’, ‘gbk’, and ‘gb2312’ are supported.

Return value

Type	Description
boolean	Whether the setting is successful. The value true means that the setting is successful, and false means the opposite.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

class TestDuplex extends stream.Duplex {
  constructor() {
    super();
  }

  doRead(size: number) {
  }

  doWrite(chunk: string|Uint8Array, encoding: string, callback: Function) {
    callback();
  }
}

let duplexStream = new TestDuplex();
let result = duplexStream.setDefaultEncoding('utf8');
console.info("duplexStream is result", result); // duplexStream is result true

cork

cork(): boolean

Forces all written data to be buffered in memory. This API is called to optimize the performance of continuous write operations.

After this API is called, the value of writableCorked is incremented by one. It is recommended that this API be used in pair with uncork().

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Return value

Type	Description
boolean	Whether the corked status is successfully set. The value true means that the setting is successful, and false means the opposite.

Example

let duplexStream = new stream.Duplex();
let result = duplexStream.cork();
console.info("duplexStream cork result", result); // duplexStream cork result true

uncork

uncork(): boolean

Flushes all data buffered, and writes the data to the target.

After this API is called, the value of writableCorked is decremented by one. If the value reaches 0, the stream is no longer in the cork state. Otherwise, the stream is still in the cork state. It is recommended that this API be used in pair with cork().

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Return value

Type	Description
boolean	Whether the corked status is successfully removed. The value true means that the corked status is successfully removed, and false means the opposite.

Example

class TestDuplex extends stream.Duplex {
  constructor() {
    super();
  }

  doRead(size: number) {
  }

  doWrite(chunk: string|Uint8Array, encoding: string, callback: Function) {
    dataWritten += chunk;
    callback();
  }
}

let dataWritten = '';
let duplexStream = new TestDuplex();
duplexStream.cork();
duplexStream.write('a');
duplexStream.write('b');
duplexStream.uncork();
console.info("Duplex test uncork", dataWritten); // Duplex test uncork ab

doWrite

doWrite(chunk: string|Uint8Array, encoding: string, callback: Function): void

A data write API. You need to implement this API but do not call it directly. This API is automatically called when data is written. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
chunk	string |Uint8Array	Yes	Data to write.
encoding	string	Yes	Encoding format. Currently, ‘utf8’, ‘gb18030’, ‘gbk’, and ‘gb2312’ are supported.
callback	Function	Yes	Callback function.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

class TestDuplex extends stream.Duplex {
  constructor() {
    super();
  }

  doRead(size: number) {
  }

  doWrite(chunk: string|Uint8Array, encoding: string, callback: Function) {
    console.info("duplexStream chunk is", chunk); // duplexStream chunk is data
    callback();
  }
}

let duplexStream = new TestDuplex();
duplexStream.write('data', 'utf8');

doWritev

doWritev(chunks: string[]|Uint8Array[], callback: Function): void

A batch data write API. You need to implement this API but do not call it directly. This API is automatically called when data is written. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
chunks	string[] |Uint8Array[]	Yes	Data arrays to write in batches.
callback	Function	Yes	Callback function.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

class TestDuplex extends stream.Duplex {
  constructor() {
    super();
  }

  doRead(size: number) {
  }

  doWrite(chunk: string|Uint8Array, encoding: string, callback: Function) {
    callback();
  }

  doWritev(chunks: string[]|Uint8Array[], callback: Function) {
    console.info("duplexStream chunk", chunks[0]); // duplexStream chunk data1
    callback();
  }
}

let duplexStream = new TestDuplex();
duplexStream.cork();
duplexStream.write('data1', 'utf8');
duplexStream.write('data2', 'utf8');
duplexStream.uncork();
duplexStream.end();

Transform

A special duplex stream that supports data conversion and result output. The Transform class inherits from Duplex and supports all the APIs in Duplex.

constructor

constructor()

A constructor used to create a Transform object.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Example

let transform = new stream.Transform();

doTransform

doTransform(chunk: string, encoding: string, callback: Function): void

Converts or processes input data chunks and uses a callback to notify that the processing is complete.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
chunk	string	Yes	Data to write.
encoding	string	Yes	Encoding format. Currently, ‘utf8’, ‘gb18030’, ‘gbk’, and ‘gb2312’ are supported.
callback	Function	Yes	Callback function.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

class TestTransform extends stream.Transform {
  constructor() {
    super();
  }

  doTransform(chunk: string, encoding: string, callback: Function) {
    let stringChunk = chunk.toString().toUpperCase();
    console.info("Transform test doTransform", stringChunk); // Transform test doTransform HELLO
    tr.push(stringChunk);
    callback();
  }
}

let tr = new TestTransform();
tr.write("hello");

doFlush

doFlush(callback: Function): void

Called at the end of the stream to process the remaining data. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
callback	Function	Yes	Callback function.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

class TestTransform extends stream.Transform {
  constructor() {
    super();
  }

  doTransform(chunk: string, encoding: string, callback: Function) {
    callback();
  }

  doFlush(callback: Function) {
    callback(null, 'test');
  }
}

let transform = new TestTransform();
transform.end('my test');
transform.on('data', (data) => {
  console.info("data is", data.data); // data is test
});

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArkTS

harmony 鸿蒙Compilation Toolchain Error Codes

harmony 鸿蒙TypeScript Compiler Error Codes

harmony 鸿蒙Utils Error Codes

harmony 鸿蒙js-apis-arkts-collections

harmony 鸿蒙@arkts.math.Decimal (High-Precision Math Library Decimal)

harmony 鸿蒙@arkts.lang (ArkTS Base Capability)

harmony 鸿蒙@arkts.utils (ArkTS Utils)

harmony 鸿蒙@ohos.util.ArrayList (Linear Container ArrayList)

harmony 鸿蒙@ohos.buffer (Buffer)