BinaryStream

Module	ejs
Definition	class BinaryStream
Inheritance	BinaryStream Object
Specified	ejscript-2.5
Stability	Evolving.

BinaryStreams encode and decode various objects onto streams.

A BinaryStream may be stacked atop an underlying stream provider such as ByteArray, File, Http or Socket. The underlying stream must be in sync mode.

Properties

Qualifiers	Property	Type	Description
static const	BigEndian	Number	Big endian byte order 0.
static const	LittleEndian	Number	Little endian byte order.
get set	async	Boolean	The current async mode. Set to true if the stream is in async mode.
get set	encoding	String	Current encoding scheme for serializing strings. Defaults to "utf-8".
get set	endian	Number	Current byte ordering. Set to either LittleEndian or BigEndian.
get	length	Number	The number of bytes available to read without blocking. This is the number of bytes internally buffered in the binary stream and does not include any data buffered downstream.

Inherited Properties

BinaryStream Class Methods

(No own class methods defined)

Qualifiers	Method

Inherited Methods

BinaryStream Instance Methods

Qualifiers	Method
	BinaryStream(stream: Stream)
	Create a new BinaryStream.
	close(): Void
	Close the stream.
	flush(dir: Number = expression): Void
	Flush the stream and underlying streams.
	off(name, observer: Function): Void
	Remove an observer from the stream.8.
	on(name, observer: Function): BinaryStream
	Add an observer to the stream for the named events.
	read(buffer: ByteArray, offset: Number = 0, count: Number = -1): Number
	Read a data from the stream.`.
	readBoolean(): Boolean
	Read a boolean from the stream.
	readByte(): Number
	Read a byte from the stream.
	readDate(): Date
	Read a date from the stream.
	readDouble()
	Read a double from the stream.
	readInteger(): Number
	Read a 32-bit integer from the stream.
	readLong(): Number
	Read a 64-bit long from the stream.The data will be decoded according to the encoding property.
	readString(count: Number = -1): String
	Read a UTF-8 string from the stream.
	readXML(): XML
	Read an XML document from the stream.
	room(): Number
	Return the space available for write data.
	write(items: Array): Number
	Write data to the stream.
	writeByte(data: Number): Void
	Write a byte to the array.
	writeDouble(data: Number): Void
	Write a double to the array.
	writeInteger(data: Number): Void
	Write a 32-bit integer to the array.
	writeLong(data: Number): Void
	Write a 64 bit long integer to the array.
	writeShort(data: Number): Void
	Write a short to the array.

Inherited Methods

Method Detail

BinaryStream(stream: Stream)

Description: Create a new BinaryStream.

Parameters

stream: Stream

Stream to stack upon.

close(): Void

Description: Close the stream.

Events

A close event is issued before closing the stream.

flush(dir: Number = expression): Void

Description: Flush the stream and underlying streams. A supplied flush direction argument modifies the effect of this call. If direction is set to Stream.READ, then all read data is discarded. If direction is set to Stream.WRITE, any buffered data is written. Stream.BOTH will cause both directions to be flushed. If the stream is in sync mode, this call will block until all data is written. If the stream is in async mode, it will attempt to write all data but will return immediately. Defaults to Stream.WRITE.

Parameters

dir: Number

Direction to flush. Set to READ WRITE or BOTH. [default: expression]

off(name, observer: Function): Void

Description: Remove an observer from the stream.8.

Parameters

name	Event name previously used with observe. The name may be an array of events.
observer: Function	Observer function previously used with observe.

on(name, observer: Function): BinaryStream

Description: Add an observer to the stream for the named events.

Parameters

name: [String\|Array]	Name of the event to listen for. The name may be an array of events.
observer: Function	Callback observer function. The function is called with the following signature: function observer(event: String, ...args): Void.

Events

readable	Issued when the stream becomes readable.
writable	Issued when the stream becomes writable.
close	Issued when stream is being closed. 8.

read(buffer: ByteArray, offset: Number = 0, count: Number = -1): Number

Description: Read a data from the stream.`. If data is available, the call will return immediately. If no data is available and the stream is in sync mode, the call will block until data is available. If no data is available and the stream is in async mode, the call will not block and will return immediately. In this case a "readable" event will be issued when data is available for reading.

Parameters

buffer: ByteArray	Destination byte array for read data.
offset: Number	Offset in the byte array to place the data. If the offset is -1, then data is appended to the buffer write position which is then updated. If offset is >= 0, the data is read to the offset and the read pointer is set to the offset and the write pointer to one past the end of the data just read. [default: 0]
count: Number	Read up to this number of bytes. If -1, read as much as the buffer will hold up. If the stream is of fixed and known length (such as a file) and the buffer is of sufficient size or is growable, read the entire stream. If the buffer is of a fixed size, ready only what will fit into the buffer. [default: -1]

Events

readable	Issued when there is new read data available.
writable	Issued when the stream becomes empty. `.

Returns: A count of the bytes actually read. Returns null on EOF or errors.

readBoolean(): Boolean

Description: Read a boolean from the stream.

Returns: A boolean. Returns null on EOF.

Throws: IOError: if an I/O error occurs.

readByte(): Number

Description: Read a byte from the stream.

Returns: A byte. Returns -1 on EOF.

Throws: IOError: if an I/O error occurs.

readDate(): Date

Description: Read a date from the stream.

Returns: A date.

Throws: IOError: if an I/O error occurs or premature EOF

readDouble()

Description: Read a double from the stream. The data will be decoded according to the encoding property.

Returns: A double.

Throws: IOError: if an I/O error occurs or premature EOF

readInteger(): Number

Description: Read a 32-bit integer from the stream. The data will be decoded according to the encoding property.

Returns: An 32-bitinteger.

Throws: IOError: if an I/O error occurs or premature EOF

readLong(): Number

Description: Read a 64-bit long from the stream.The data will be decoded according to the encoding property.

Returns: A 64-bit long number.

Throws: IOError: if an I/O error occurs or premature EOF

readString(count: Number = -1): String

Description: Read a UTF-8 string from the stream.

Parameters

count: Number

Of bytes to read. Returns the entire stream contents if count is -1. [default: -1]

Returns: A string.

Throws: IOError: if an I/O error occurs or premature EOF.

readXML(): XML

Description: Read an XML document from the stream. This assumes the XML document will be the only data until EOF.

Returns: An XML document.

Throws: IOError: if an I/O error occurs or premature EOF

room(): Number

Description: Return the space available for write data. This call can be used to prevent write from blocking or doing partial writes. If it cannot be determined how much room is available, this call will return null.

Returns: The number of bytes that can be written without blocking or null if it cannot be determined.

write(items: Array): Number

Description: Write data to the stream. Write intelligently encodes various data types onto the stream and will encode data in a portable cross-platform manner according to the setting of the endian property. If data is an array, each element of the array will be written.

Parameters

items: Array

Data items to write. The ByteStream class intelligently encodes various data types according to the current setting of the endian property.

Events

0	Ytes that were written. @throws IOError if there is an I/O error. @event 0.

Returns: The total number of bytes that were written.

Throws: IOError: if there is an I/O error.

writeByte(data: Number): Void

Description: Write a byte to the array. Data is written to the current write position pointer.

Parameters

data: Number

Data to write.

Events

readable

Issued when data is written and a consumer can read without blocking.

writeDouble(data: Number): Void

Description: Write a double to the array. Data is written to the current write position pointer.

Parameters

data: Number

Data to write.

Events

readable

Issued when data is written and a consumer can read without blocking.

writeInteger(data: Number): Void

Description: Write a 32-bit integer to the array. Data is written to the current write position pointer.

Parameters

data: Number

Data to write.

Events

readable

Issued when data is written and a consumer can read without blocking.

writeLong(data: Number): Void

Description: Write a 64 bit long integer to the array. Data is written to the current write position pointer.

Parameters

data: Number

Data to write.

Events

readable

Issued when data is written and a consumer can read without blocking.

writeShort(data: Number): Void

Description: Write a short to the array. Data is written to the current write position pointer.

Parameters

data: Number

Data to write.

Events

readable

Issued when data is written and a consumer can read without blocking.