IO Class Pattern

The IO Class Pattern builds on the Base Class Pattern to provide a foundation for implementing access to a variety of hardware inputs and outputs.

Constructor

IO()

Creates a new IO object instance.

IO(options)

Parameters

options

An object of properties used to construct the class. The options object contains the specification of the hardware resources to be used by the instance. The following are defined by this abstract class:

format (optional): a string that indicates the type of data used by the read and write methods. IO types may choose to support one or more of the following and may define others.

• number - an ECMAScript number value, typically used for bytes
• buffer - a Byte Buffer. For buffer types with defined byteOffset and byteLength properties, these restrict the bytes accessed in views. Implementations always allocate ArrayBuffer instances for return values.
• object - an ECMAScript object, for data representing a data structure (e.g. JSON)
• string;ascii - an ECMAScript string, for reading from and writing to IO using 7-bit ASCII data
• string;utf8 - an ECMAScript string, for reading from and writing to IO using UTF-8 formatted data

onReadable (optional): A callback function that is invoked when the instance has data available to read, which can be retrieved using the read method.

onWritable (optional): A callback function that is invoked when the instance can accept more data for output, which can be sent using the write method.

onError (optional): A callback function that is invoked when a non-recoverable error occurs. The function may be passed an Error depending on the IO type.

Exceptions

If the constructor requires a resource that is already in use — whether by a script or the native host — an Error exception is thrown.

Instance Properties

This class inherits all instance properties from the Base Class Pattern, along with the following:

format

The string value set by the constructor options or by the script at any time to change how it reads and writes data.

The property is implemented as a getter and setter. Attempting to set the property to an unsupported value does not change the value and instead throws an Error exception.

Instance Methods

This class inherits all instance methods from the Base Class Pattern, along with the following:

read

Returns data from the IO instance.

read()
read(callbackFn)
read(sizeOrBuffer)
read(sizeOrBuffer, callbackFn)

Parameters

callbackFn

callbackFn(error, data)

For asynchronous classes, a function that executes when the data has been read. It will always be last for asynchronous implementations that accept additional arguments.

error The first argument to the completion callback is always a result code. A value of null indicates success; an Error object indicates failure.

data The same expectations of the return value for synchronous reads.

sizeOrBuffer

When the format property is "buffer", the method accepts this argument that is a Number or Byte Buffer. When it is a Number, read allocates the result as an ArrayBuffer with up to as many bytes as the Number argument. When it is a Byte Buffer, read fills in as many bytes as possible and the result is the number of bytes read as a Number.

Return value

For asynchronous reads or if no data is available, it returns undefined.

Otherwise for synchronous reads, the return type depends on the format value set on the instance. For asynchronous reads, the result is passed to the callbackFn argument when invoked.

Exceptions

If the instance does not support reading (because the IO type is inherently unreadable or because it is configured for write-only) an exception is thrown.

write

Sends data to the IO instance.

write(data)
write(data, callbackFn)

Parameters

data

The type of data accepted by this method depends on the value of the format property. When the format property is "buffer", the method accepts a Byte Buffer.

callbackFn

callbackFn(error, data)

A function that executes when the data has been written. It will always be last for asynchronous implementations that accept additional arguments.

error The first argument to the completion callback is always a result code. A value of null indicates success; an Error object indicates failure.

Return value

For asynchronous reads or if no data is available, it returns undefined.

Otherwise for synchronous reads, the return type depends on the format value set on the instance. For asynchronous reads, the result is passed to the callbackFn argument when invoked.

Exceptions

The following conditions cause an Error exception to be thrown:

• the device cannot accept the data because its buffers are full
• the data is incompatible
• hardware error.

Examples

No examples since this class is purely abstract and cannot be instantiated directly.

Specifications

IO Class Pattern