IoDevice

Description

The IoDevice object is the base interface class of all I/O devices. It provides both a common implementation and an interface for devices that support reading and writing of blocks of data, such as File. It is therefore never used directly.

Before accessing data the device must be configured through the corresponding properties such as readOnly, append and truncate. It can then be opened via open(). Objects interacting with I/O devices (e.g. CsvWriter or EventLogFile) usually open them automatically.

› Inherits:Object
› Inherited by:File, IpSocket, WebSocket

Properties

append

This property holds whether the I/O device should be opened in append mode so that new data is always written to the end of the file. Changing this property on an open I/O device will call close().

› Type:Boolean
› Default:true
› Signal:appendChanged()
› Attributes:Writable

atEnd

This property holds whether the current read and write position is at the end of the device (i.e. there is no more data available for reading on the device).

› Type:Boolean
› Signal:atEndChanged()
› Attributes:Readonly

autoOpen

This property holds whether to call open() on initialization automatically.

This property was introduced in InCore 2.0.

› Type:Boolean
› Default:false
› Signal:autoOpenChanged()
› Attributes:Writable

bytesAvailable

This property holds the number of bytes that are available for reading from the I/O device.

This property was introduced in InCore 2.0.

› Type:SignedBigInteger
› Signal:bytesAvailableChanged()
› Attributes:Readonly

canReadLine

This property holds whether a complete line of data can be read from the device.

This property was introduced in InCore 2.3.

› Type:Boolean
› Signal:canReadLineChanged()
› Attributes:Readonly

deviceErrorString

This property holds a human-readable description of the last device error that occurred.

› Type:String
› Signal:deviceErrorStringChanged()
› Attributes:Readonly

isOpen

This property holds whether the device is open. A device is open if it can be read from and/or written to.

› Type:Boolean
› Signal:isOpenChanged()
› Attributes:Readonly

isWritable

This property holds whether data can be written to the device, i.e. readOnly is false and the specified device or file is writable by the app.

› Type:Boolean
› Signal:isWritableChanged()
› Attributes:Readonly

nameArgument

This property holds the data which is inserted in filenames if they contain a placeholder. This internal property is mainly used by CsvWriter to implement log file rotation.

› Type:String
› Signal:nameArgumentChanged()
› Attributes:Writable

pos

This property holds the current position of the device pointer. The next read or write operation always takes place at this position.

› Type:SignedBigInteger
› Signal:posChanged()
› Attributes:Writable

readOnly

This property holds whether the I/O device should be opened and accessed read-only. Changing this property on an open I/O device will call close().

› Type:Boolean
› Default:false
› Signal:readOnlyChanged()
› Attributes:Writable

size

This property holds the current size of the I/O device.

› Type:SignedBigInteger
› Signal:sizeChanged()
› Attributes:Readonly

truncate

This property holds whether the I/O device should always be truncated when opened. All previous contents of the device are lost. Changing this property on an open I/O device will call close().

› Type:Boolean
› Default:false
› Signal:truncateChanged()
› Attributes:Writable

unbuffered

This property holds whether the I/O device should be opened in unbuffered mode. This will bypass any internal buffers and caches. Reading data will never fetch more data than requested. When writing all data is written to the underlying storage immediately. Changing this property on an open I/O device will call close().

› Type:Boolean
› Default:false
› Signal:unbufferedChanged()
› Attributes:Writable

Methods

close()

This method flushes any buffered data and closes the I/O device.

flush()

This method flushes all write buffers and possibly buffered data of the I/O device to the operating system.

This method was introduced in InCore 2.3.

open()

This method opens the I/O device for reading or writing depending on the corresponding properties. If the device could not be opened, false is returned. Otherwise true is returned. If truncate is set to true the device is also truncated.

› Returns:Boolean

peekAll()

This method reads all data from the I/O device without draining the read buffer. This is useful when implementing communications based on non-trivial protocols.

This method was introduced in InCore 2.0.

› Returns:ArrayBuffer

read(SignedBigInteger maxSize)

This method reads at most the given number of bytes from the I/O device. An empty buffer is returned if either no more data is available for reading or reading failed for some reason.

› Returns:ArrayBuffer

readAll()

This method reads all remaining data from the I/O device.

This method was introduced in InCore 2.0.

› Returns:ArrayBuffer

readLine()

This method reads a line from the device (maximum 65535 characters) and returns the result as a UTF-8 encoded string. This function has no way of reporting errors, i.e. an empty string can mean either that no data was currently available for reading, or that an error occurred.

This method was introduced in InCore 2.3.

› Returns:String

sync()

This method calls IoDevice.flush() and tells the operating system to write all pending data to its storages. Calling this method might block the program execution for a while depending on the amount of data to be written.

write(ArrayBuffer data)

This method writes the given data to the I/O device. If unbuffered is false the data may not actually be written until the device is closed or flush() is called.

› Returns:SignedBigInteger

Signals

lineAvailableForRead()

This signal is emitted once everytime a a complete line of data can be read from the device. It will only be emitted again once new data is available, such as when a new payload of network data has arrived on a network socket, or when a new block of data has been appended to the device.

This signal was introduced in InCore 2.3.

readyRead()

This signal is emitted once everytime new data is available for reading from the device’s current read channel. It will only be emitted again once new data is available, such as when a new payload of network data has arrived on a network socket, or when a new block of data has been appended to the device.

This signal was introduced in InCore 2.0.