flash.filesystem

# FileStream - AS3

Package | flash.filesystem
Class | public class FileStream
Inheritance | FileStream EventDispatcher Object
Implements | IDataInput, IDataOutput

Runtime Versions: | AIR 1.0

A FileStream object is used to read and write files. Files can be opened synchronously by calling the `open()` method or asynchronously by calling the `openAsync()` method.

The advantage of opening files asynchronously is that other code can execute while Adobe AIR runs read and write processes in the background. When opened asynchronously, `progress` events are dispatched as operations proceed.

A File object that is opened synchronously behaves much like a ByteArray object; a file opened asynchronously behaves much like a Socket or URLStream object. When a File object is opened synchronously, the caller pauses while the requested data is read from or written to the underlying file. When opened asynchronously, any data written to the stream is immediately buffered and later written to the file.

Whether reading from a file synchronously or asynchronously, the actual read methods are synchronous. In both cases they read from data that is currently "available." The difference is that when reading synchronously all of the data is available at all times, and when reading asynchronously data becomes available gradually as the data streams into a read buffer. Either way, the data that can be synchronously read at the current moment is represented by the `bytesAvailable` property.

An application that is processing asynchronous input typically registers for `progress` events and consumes the data as it becomes available by calling read methods. Alternatively, an application can simply wait until all of the data is available by registering for the `complete` event and processing the entire data set when the `complete` event is dispatched.

More examples

Reading and writing files

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | bytesAvailable : uint [read-only] Returns the number of bytes of data available for reading in the input buffer. | FileStream
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | endian : String The byte order for the data, either the BIG_ENDIAN or LITTLE_ENDIAN constant from the Endian class. | FileStream
|  | objectEncoding : uint Specifies whether the AMF3 or AMF0 format is used when writing or reading binary data by using the readObject() or writeObject() method. | FileStream
|  | position : Number The current position in the file. | FileStream
|  | readAhead : Number The minimum amount of data to read from disk when reading files asynchronously. | FileStream

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | FileStream() Creates a FileStream object. | FileStream
|  | addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event. | EventDispatcher
|  | close():void Closes the FileStream object. | FileStream
|  | dispatchEvent(event:Event):Boolean Dispatches an event into the event flow. | EventDispatcher
|  | hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event. | EventDispatcher
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | open(file:File, fileMode:String):void Opens the FileStream object synchronously, pointing to the file specified by the file parameter. | FileStream
|  | openAsync(file:File, fileMode:String):void Opens the FileStream object asynchronously, pointing to the file specified by the file parameter. | FileStream
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | readBoolean():Boolean Reads a Boolean value from the file stream, byte stream, or byte array. | FileStream
|  | readByte():int Reads a signed byte from the file stream, byte stream, or byte array. | FileStream
|  | readBytes(bytes:ByteArray, offset:uint = 0, length:uint = 0):void Reads the number of data bytes, specified by the length parameter, from the file stream, byte stream, or byte array. | FileStream
|  | readDouble():Number Reads an IEEE 754 double-precision floating point number from the file stream, byte stream, or byte array. | FileStream
|  | readFloat():Number Reads an IEEE 754 single-precision floating point number from the file stream, byte stream, or byte array. | FileStream
|  | readInt():int Reads a signed 32-bit integer from the file stream, byte stream, or byte array. | FileStream
|  | readMultiByte(length:uint, charSet:String):String Reads a multibyte string of specified length from the file stream, byte stream, or byte array using the specified character set. | FileStream
|  | readObject():* Reads an object from the file stream, byte stream, or byte array, encoded in AMF serialized format. | FileStream
|  | readShort():int Reads a signed 16-bit integer from the file stream, byte stream, or byte array. | FileStream
|  | readUnsignedByte():uint Reads an unsigned byte from the file stream, byte stream, or byte array. | FileStream
|  | readUnsignedInt():uint Reads an unsigned 32-bit integer from the file stream, byte stream, or byte array. | FileStream
|  | readUnsignedShort():uint Reads an unsigned 16-bit integer from the file stream, byte stream, or byte array. | FileStream
|  | readUTF():String Reads a UTF-8 string from the file stream, byte stream, or byte array. | FileStream
|  | readUTFBytes(length:uint):String Reads a sequence of UTF-8 bytes from the byte stream or byte array and returns a string. | FileStream
|  | removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object. | EventDispatcher
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | truncate():void Truncates the file at the position specified by the position property of the FileStream object. | FileStream
|  | valueOf():Object Returns the primitive value of the specified object. | Object
|  | willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. | EventDispatcher
|  | writeBoolean(value:Boolean):void Writes a Boolean value. | FileStream
|  | writeByte(value:int):void Writes a byte. | FileStream
|  | writeBytes(bytes:ByteArray, offset:uint = 0, length:uint = 0):void Writes a sequence of bytes from the specified byte array, bytes, starting at the byte specified by offset (using a zero-based index) with a length specified by length, into the file stream, byte stream, or byte array. | FileStream
|  | writeDouble(value:Number):void Writes an IEEE 754 double-precision (64-bit) floating point number. | FileStream
|  | writeFloat(value:Number):void Writes an IEEE 754 single-precision (32-bit) floating point number. | FileStream
|  | writeInt(value:int):void Writes a 32-bit signed integer. | FileStream
|  | writeMultiByte(value:String, charSet:String):void Writes a multibyte string to the file stream, byte stream, or byte array, using the specified character set. | FileStream
|  | writeObject(object:*):void Writes an object to the file stream, byte stream, or byte array, in AMF serialized format. | FileStream
|  | writeShort(value:int):void Writes a 16-bit integer. | FileStream
|  | writeUnsignedInt(value:uint):void Writes a 32-bit unsigned integer. | FileStream
|  | writeUTF(value:String):void Writes a UTF-8 string to the file stream, byte stream, or byte array. | FileStream
|  | writeUTFBytes(value:String):void Writes a UTF-8 string. | FileStream

Events
Click for more information on events
Hide Inherited Events
Show Inherited Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | activate | [broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active. | EventDispatcher
|  | close | Indicates that the stream has been closed by an explicit call to the close() method. | FileStream
|  | complete | Signals that the end of the stream has been reached. | FileStream
|  | deactivate | [broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive. | EventDispatcher
|  | ioError | Indicates that an error occurred during an asynchronous file I/O operation. | FileStream
|  | outputProgress | Signals that buffered data has been written to the file. | FileStream
|  | progress | Signals the availability of new data on the stream. | FileStream

Property Detail

### bytesAvailable

property

`bytesAvailable:uint` [read-only]

Runtime Versions: | AIR 1.0

Returns the number of bytes of data available for reading in the input buffer. User code must call `bytesAvailable` to ensure that sufficient data is available before trying to read it with one of the read methods.

Implementation
`public function get bytesAvailable():uint`

### endian

property

`endian:String`

Runtime Versions: | AIR 1.0

The byte order for the data, either the `BIG_ENDIAN` or `LITTLE_ENDIAN` constant from the Endian class.

Implementation
`public function get endian():String`
`public function set endian(value:String):void`

### objectEncoding

property

`objectEncoding:uint`

Runtime Versions: | AIR 1.0

Specifies whether the AMF3 or AMF0 format is used when writing or reading binary data by using the `readObject()` or `writeObject()` method.

The value is a constant from the ObjectEncoding class. By default, the AMF3 format is used.

Implementation
`public function get objectEncoding():uint`
`public function set objectEncoding(value:uint):void`

Related API Elements

ObjectEncoding
readObject()
writeObject()

### position

property

`position:Number`

Runtime Versions: | AIR 1.0

The current position in the file.

This value is modified in any of the following ways:

- When you set the property explicitly
- When reading from the FileStream object (by using one of the read methods)
- When writing to the FileStream object

The position is defined as a Number (instead of uint) in order to support files larger than 232 bytes in length. The value of this property is always a whole number less than 253. If you set this value to a number with a fractional component, the value is rounded down to the nearest integer.

When reading a file asyncronously, if you set the `position` property, the application begins filling the read buffer with the data starting at the specified position, and the `bytesAvailable` property may be set to 0. Wait for a `complete` event before using a read method to read data; or wait for a `progress` event and check the `bytesAvailable` property before using a read method.

Implementation
`public function get position():Number`
`public function set position(value:Number):void`

More examples

The position property of a FileStream object
The read buffer and the bytesAvailable property of a FileStream object
Example ( How to use this example )
The following code shows how a `position` property of the FileStream object is updated as the application reads data from a file.
Copy

    import flash.fileSystem.*;
    import flash.utils.ByteArray;
    import flash.events.Event;

    var sourceFile:File = File.documentsDirectory.resolvePath("Apollo Test/test.txt");
    var stream:FileStream = new FileStream();
    stream.addEventListener(Event.COMPLETE, readBytes);
    stream.openAsync(sourceFile, FileMode.READ);

    function readBytes(e:Event):void {
        var bytes:ByteArray = new ByteArray();
        trace("position 0:", stream.position); // 0
        bytes[0] = stream.readByte();
        trace("position 1:", stream.position); // 1
        fileStream.readBytes(bytes, stream.position, 4);
        trace("position 2:", stream.position); // 5
        stream.close();
    }

### readAhead

property

`readAhead:Number`

Runtime Versions: | AIR 1.0

The minimum amount of data to read from disk when reading files asynchronously.

This property specifies how much data an asynchronous stream attempts to read beyond the current position. Data is read in blocks based on the file system page size. Thus if you set `readAhead` to 9,000 on a computer system with an 8KB (8192 byte) page size, the runtime reads ahead 2 blocks, or 16384 bytes at a time. The default value of this property is infinity: by default a file that is opened to read asynchronously reads as far as the end of the file.

Reading data from the read buffer does not change the value of the `readAhead` property. When you read data from the buffer, new data is read in to refill the read buffer.

The `readAhead` property has no effect on a file that is opened synchronously.

As data is read in asynchronously, the FileStream object dispatches `progress` events. In the event handler method for the `progress` event, check to see that the required number of bytes is available (by checking the `bytesAvailable` property), and then read the data from the read buffer by using a read method.

Implementation
`public function get readAhead():Number`
`public function set readAhead(value:Number):void`
Example ( How to use this example )
The following code shows how to use the `readAhead` property to limit the amount of data read into a file to 100 bytes:
Copy

    import flash.filesystem.*;

    var file:File = File.desktopDirectory.resolvePath("test.txt");
    var fileStream:FileStream = new FileStream();
    fileStream.readAhead = 100;
    fileStream.addEventListener(ProgressEvent.PROGRESS, readProgressHandler)
    fileStream.openAsync(file, FileMode.READ);
    var results:ByteArray;

    function readProgressHandler(event:ProgressEvent):void {
        if (fileStream.bytesAvailable >= 100) {
            fileStream.readBytes(results, 0, 100);
        }
    }

Constructor Detail

### FileStream

()
Constructor

`public function FileStream()`

Runtime Versions: | AIR 1.0

Creates a FileStream object. Use the `open()` or `openAsync()` method to open a file.

Related API Elements

open()
openAsync()
Method Detail

### close

()
method

`public function close():void`

Runtime Versions: | AIR 1.0

Closes the FileStream object.

You cannot read or write any data after you call the `close()` method. If the file was opened asynchronously (the FileStream object used the `openAsync()` method to open the file), calling the `close()` method causes the object to dispatch the `close` event.

Closing the application automatically closes all files associated with FileStream objects in the application. However, it is best to register for a `closed` event on all FileStream objects opened asynchronously that have pending data to write, before closing the application (to ensure that data is written).

You can reuse the FileStream object by calling the `open()` or the `openAsync()` method. This closes any file associated with the FileStream object, but the object does not dispatch the `close` event.

For a FileStream object opened asynchronously (by using the `openAsync()` method), even if you call the `close()` event for a FileStream object and delete properties and variables that reference the object, the FileStream object is not garbage collected as long as there are pending operations and event handlers are registered for their completion. In particular, an otherwise unreferenced FileStream object persists as long as any of the following are still possible:

- For file reading operations, the end of the file has not been reached (and the `complete` event has not been dispatched).
- Output data is still available to written, and output-related events (such as the `outputProgress` event or the `ioError` event) have registered event listeners.

Events

| `close:`Event`` — The file, which was opened asynchronously, is closed.

Related API Elements

open()
close event
Example ( How to use this example )
The following code opens a FileStream object asynchronously and writes a text file named test.txt to the Apollo Test subdirectory of the user's documents directory. A call to the `close()` method of the FileStream object closes the file when the data is written.
Copy

    import flash.filesystem.*;
    import flash.events.Event;

    var file:File = File.documentsDirectory;
    file = file.resolvePath("Apollo Test/test.txt");
    var fileStream:FileStream = new FileStream();
    fileStream.openAsync(file, FileMode.WRITE);
    fileStream.writeUTFBytes("Hello");
    fileStream.addEventListener(Event.CLOSE, fileClosed);
    fileStream.close();

    function fileClosed(event:Event):void {
        trace("closed");
    }

The following code opens a FileStream object synchronously and writes a text file named test.txt to the Apollo Test subdirectory of the user's documents directory. A call to the `close()` method of the FileStream object closes the file when the data is written.
Copy

    import flash.filesystem.*;

    var file:File = File.documentsDirectory;
    file = file.resolvePath("Apollo Test/test.txt");
    var fileStream:FileStream = new FileStream();
    fileStream.open(file, FileMode.WRITE);
    fileStream.writeUTF("Hello");
    fileStream.close();

### open

()
method

`public function open(file:File, fileMode:String):void`

Runtime Versions: | AIR 1.0

Opens the FileStream object synchronously, pointing to the file specified by the `file` parameter.

If the FileStream object is already open, calling the method closes the file before opening and no further events (including `close`) are delivered for the previously opened file.

On systems that support file locking, a file opened in "write" or "update" mode (`FileMode.WRITE` or `FileMode.UPDATE`) is not readable until it is closed.

Once you are done performing operations on the file, call the `close()` method of the FileStream object. Some operating systems limit the number of concurrently open files.

Parameters

| `file:File` — The File object specifying the file to open.
| `fileMode:String` — A string from the FileMode class that defines the capabilities of the FileStream, such as the ability to read from or write to the file.

Throws

| `IOError` — The file does not exist; you do not have adequate permissions to open the file; you are opening a file for read access, and you do not have read permissions; or you are opening a file for write access, and you do not have write permissions.
| `SecurityError` — The file location is in the application directory, and the `fileMode` parameter is set to "append", "update", or "write" mode.

More examples

Initializing a FileStream object, and opening and closing files
Example: Reading an XML file into an XML object
Example: Reading and writing data with random access

Related API Elements

close()
File
FileMode
Example ( How to use this example )
The following code shows how to synchronously open a test.txt file in the Apollo Test subdirectory of the user's documents directory and then read the file into a string, using the system character set as the text encoding.
Copy

    import flash.filesystem.*;

    var file:File = File.documentsDirectory;
    file = file.resolvePath("Apollo Test/test.txt");
    var fileStream:FileStream = new FileStream();
    fileStream.open(file, FileMode.READ);
    var str:String = fileStream.readMultiByte(file.size, File.systemCharset);
    trace(str);
    fileStream.close();

### openAsync

()
method

`public function openAsync(file:File, fileMode:String):void`

Runtime Versions: | AIR 1.0

Opens the FileStream object asynchronously, pointing to the file specified by the `file` parameter.

If the FileStream object is already open, calling the method closes the file before opening and no further events (including `close`) are delivered for the previously opened file.

If the `fileMode` parameter is set to `FileMode.READ` or `FileMode.UPDATE`, AIR reads data into the input buffer as soon as the file is opened, and `progress` and `open` events are dispatched as the data is read to the input buffer.

On systems that support file locking, a file opened in "write" or "update" mode (`FileMode.WRITE` or `FileMode.UPDATE`) is not readable until it is closed.

Once you are done performing operations on the file, call the `close()` method of the FileStream object. Some operating systems limit the number of concurrently open files.

`

Parameters

| `file:File` — The File object specifying the file to open.
| `fileMode:String` — A string from the FileMode class that defines the capabilities of the FileStream, such as the ability to read from or write to the file.

Events

| `ioError:`IOErrorEvent`` — The file does not exist; you do not have adequate permissions to open the file; you are opening a file for read access, and you do not have read permissions; or you are opening a file for write access, and you do not have write permissions.
| `progress:`ProgressEvent`` — Dispatched as data is read to the input buffer. (The file must be opened with the `fileMode` parameter set to `FileMode.READ` or `FileMode.UPDATE`.)
| `complete:`Event`` — The file data has been read to the input buffer. (The file must be opened with the `fileMode` parameter set to `FileMode.READ` or `FileMode.UPDATE`.)

Throws

| `SecurityError` — The file location is in the application directory, and the `fileMode` parameter is set to "append", "update", or "write" mode.

More examples

Asynchronous programming and the events generated by a FileStream object opened asynchronously

Related API Elements

close()
complete event
ioError event
progress event
FileMode
Example ( How to use this example )
The following code shows how to asynchronously open a test.txt file in the Apollo Test subdirectory of the user's documents directory and then read the file into a string, using the system character set as the text encoding.
Copy

    import flash.filesystem.*;
    import flash.events.Event;

    var file:File = File.documentsDirectory;
    file = file.resolvePath("Apollo Test/test.txt");
    var fileStream:FileStream = new FileStream();
    fileStream.addEventListener(Event.COMPLETE, fileCompleteHandler)
    fileStream.openAsync(file, FileMode.READ);

    function fileCompleteHandler(event:Event):void {
        var str:String = fileStream.readMultiByte(fileStream.bytesAvailable, File.systemCharset);
        trace(str);
        fileStream.close();
    }

### readBoolean

()
method

`public function readBoolean():Boolean`

Runtime Versions: | AIR 1.0

Reads a Boolean value from the file stream, byte stream, or byte array. A single byte is read and `true` is returned if the byte is nonzero, `false` otherwise.

Returns

| `Boolean` — A Boolean value, `true` if the byte is nonzero, `false` otherwise.

Events

| `ioError:`IOErrorEvent`` — The file cannot be read or the file is not open. This event is dispatched only for files opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `IOError` — The file has not been opened; the file has been opened, but it was not opened with read capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be read (for example, because the file is missing).
| `EOFError` — The position specfied for reading data exceeds the number of bytes available (specified by the `bytesAvailable` property).

### readByte

()
method

`public function readByte():int`

Runtime Versions: | AIR 1.0

Reads a signed byte from the file stream, byte stream, or byte array.

Returns

| `int` — The returned value is in the range -128 to 127.

Events

| `ioError:`IOErrorEvent`` — The file cannot be read or the file is not open. This event is dispatched only for files opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `IOError` — The file has not been opened; the file has been opened, but it was not opened with read capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be read (for example, because the file is missing).
| `EOFError` — The position specfied for reading data exceeds the number of bytes available (specified by the `bytesAvailable` property).

### readBytes

()
method

`public function readBytes(bytes:ByteArray, offset:uint = 0, length:uint = 0):void`

Runtime Versions: | AIR 1.0

Reads the number of data bytes, specified by the `length` parameter, from the file stream, byte stream, or byte array. The bytes are read into the ByteArray objected specified by the `bytes` parameter, starting at the position specified by `offset`.

Parameters

| `bytes:ByteArray` — The `ByteArray` object to read data into.
| `offset:uint` (default = `0`)`` — The offset into the `bytes` parameter at which data read should begin.
| `length:uint` (default = `0`)`` — The number of bytes to read. The default value of 0 causes all available data to be read.

Events

| `ioError:`IOErrorEvent`` — The file cannot be read or the file is not open. This event is dispatched only for files opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `IOError` — The file has not been opened; the file has been opened, but it was not opened with read capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be read (for example, because the file is missing).
| `EOFError` — The position specfied for reading data exceeds the number of bytes available (specified by the `bytesAvailable` property).

More examples

The read buffer and the bytesAvailable property of a FileStream object

### readDouble

()
method

`public function readDouble():Number`

Runtime Versions: | AIR 1.0

Reads an IEEE 754 double-precision floating point number from the file stream, byte stream, or byte array.

Returns

| `Number` — An IEEE 754 double-precision floating point number.

Events

| `ioError:`IOErrorEvent`` — The file cannot be read or the file is not open. This event is dispatched only for files opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `IOError` — The file has not been opened; the file has been opened, but it was not opened with read capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be read (for example, because the file is missing).
| `EOFError` — The position specfied for reading data exceeds the number of bytes available (specified by the `bytesAvailable` property).

### readFloat

()
method

`public function readFloat():Number`

Runtime Versions: | AIR 1.0

Reads an IEEE 754 single-precision floating point number from the file stream, byte stream, or byte array.

Returns

| `Number` — An IEEE 754 single-precision floating point number.

Events

| `ioError:`IOErrorEvent`` — The file cannot be read or the file is not open. This event is dispatched only for files opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `IOError` — The file has not been opened; the file has been opened, but it was not opened with read capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be read (for example, because the file is missing).
| `EOFError` — The position specfied for reading data exceeds the number of bytes available (specified by the `bytesAvailable` property).

### readInt

()
method

`public function readInt():int`

Runtime Versions: | AIR 1.0

Reads a signed 32-bit integer from the file stream, byte stream, or byte array.

Returns

| `int` — The returned value is in the range -2147483648 to 2147483647.

Events

| `ioError:`IOErrorEvent`` — The file cannot be read or the file is not open. This event is dispatched only for files opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `IOError` — The file has not been opened; the file has been opened, but it was not opened with read capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be read (for example, because the file is missing).
| `EOFError` — The position specfied for reading data exceeds the number of bytes available (specified by the `bytesAvailable` property).

### readMultiByte

()
method

`public function readMultiByte(length:uint, charSet:String):String`

Runtime Versions: | AIR 1.0

Reads a multibyte string of specified length from the file stream, byte stream, or byte array using the specified character set.

Parameters

| `length:uint` — The number of bytes from the byte stream to read.
| `charSet:String` — The string denoting the character set to use to interpret the bytes. Possible character set strings include `"shift-jis"`, `"cn-gb"`, `"iso-8859-1"`, and others. For a complete list, see Supported Character Sets. Note: If the value for the `charSet` parameter is not recognized by the current system, then Adobe® Flash® Player or Adobe® AIR® uses the system's default code page as the character set. For example, a value for the `charSet` parameter, as in `myTest.readMultiByte(22, "iso-8859-01")`, that uses `01` instead of `1` might work on your development system, but not on another system. On the other system, Flash Player or the AIR runtime will use the system's default code page.

Returns

| `String` — UTF-8 encoded string.

Events

| `ioError:`IOErrorEvent`` — The file cannot be read or the file is not open. This event is dispatched only for files opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `IOError` — The file has not been opened; the file has been opened, but it was not opened with read capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be read (for example, because the file is missing).
| `EOFError` — The position specfied for reading data exceeds the number of bytes available (specified by the `bytesAvailable` property).

Related API Elements

File.systemCharset

### readObject

()
method

`public function readObject():*`

Runtime Versions: | AIR 1.0

Reads an object from the file stream, byte stream, or byte array, encoded in AMF serialized format.

Returns

| `*` — The deserialized object

Events

| `ioError:`IOErrorEvent`` — The file cannot be read or the file is not open. This event is dispatched only for files opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `IOError` — The file has not been opened; the file has been opened, but it was not opened with read capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be read (for example, because the file is missing).
| `EOFError` — The position specfied for reading data exceeds the number of bytes available (specified by the `bytesAvailable` property).

Related API Elements

flash.net.registerClassAlias()

### readShort

()
method

`public function readShort():int`

Runtime Versions: | AIR 1.0

Reads a signed 16-bit integer from the file stream, byte stream, or byte array.

Returns

| `int` — The returned value is in the range -32768 to 32767.

Events

| `ioError:`IOErrorEvent`` — The file cannot be read or the file is not open. This event is dispatched only for files opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `IOError` — The file has not been opened; the file has been opened, but it was not opened with read capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be read (for example, because the file is missing).
| `EOFError` — The position specfied for reading data exceeds the number of bytes available (specified by the `bytesAvailable` property).

### readUnsignedByte

()
method

`public function readUnsignedByte():uint`

Runtime Versions: | AIR 1.0

Reads an unsigned byte from the file stream, byte stream, or byte array.

Returns

| `uint` — The returned value is in the range 0 to 255.

Events

| `ioError:`IOErrorEvent`` — The file cannot be read or the file is not open. This event is dispatched only for files opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `IOError` — The file has not been opened; the file has been opened, but it was not opened with read capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be read (for example, because the file is missing).
| `EOFError` — The position specfied for reading data exceeds the number of bytes available (specified by the `bytesAvailable` property).

### readUnsignedInt

()
method

`public function readUnsignedInt():uint`

Runtime Versions: | AIR 1.0

Reads an unsigned 32-bit integer from the file stream, byte stream, or byte array.

Returns

| `uint` — The returned value is in the range 0 to 4294967295.

Events

| `ioError:`IOErrorEvent`` — The file cannot be read or the file is not open. This event is dispatched only for files opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `IOError` — The file has not been opened; the file has been opened, but it was not opened with read capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be read (for example, because the file is missing).
| `EOFError` — The position specfied for reading data exceeds the number of bytes available (specified by the `bytesAvailable` property).

### readUnsignedShort

()
method

`public function readUnsignedShort():uint`

Runtime Versions: | AIR 1.0

Reads an unsigned 16-bit integer from the file stream, byte stream, or byte array.

Returns

| `uint` — The returned value is in the range 0 to 65535.

Events

| `ioError:`IOErrorEvent`` — The file cannot be read or the file is not open. This event is dispatched only for files opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `IOError` — The file has not been opened; the file has been opened, but it was not opened with read capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be read (for example, because the file is missing).
| `EOFError` — The position specfied for reading data exceeds the number of bytes available (specified by the `bytesAvailable` property).

### readUTF

()
method

`public function readUTF():String`

Runtime Versions: | AIR 1.0

Reads a UTF-8 string from the file stream, byte stream, or byte array. The string is assumed to be prefixed with an unsigned short indicating the length in bytes.

This method is similar to the `readUTF()` method in the Java® IDataInput interface.

Returns

| `String` — A UTF-8 string produced by the byte representation of characters.

Events

| `ioError:`IOErrorEvent`` — The file cannot be read or the file is not open. This event is dispatched only for files opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `IOError` — The file has not been opened; the file has been opened, but it was not opened with read capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be read (for example, because the file is missing).
| `EOFError` — The position specfied for reading data exceeds the number of bytes available (specified by the `bytesAvailable` property).

### readUTFBytes

()
method

`public function readUTFBytes(length:uint):String`

Runtime Versions: | AIR 1.0

Reads a sequence of UTF-8 bytes from the byte stream or byte array and returns a string.

Parameters

| `length:uint` — The number of bytes to read.

Returns

| `String` — A UTF-8 string produced by the byte representation of characters of the specified length.

Events

| `ioError:`IOErrorEvent`` — The file cannot be read or the file is not open. This event is dispatched only for files opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `IOError` — The file has not been opened; the file has been opened, but it was not opened with read capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be read (for example, because the file is missing).
| `EOFError` — The position specfied for reading data exceeds the number of bytes available (specified by the `bytesAvailable` property).

### truncate

()
method

`public function truncate():void`

Runtime Versions: | AIR 1.0

Truncates the file at the position specified by the `position` property of the FileStream object.

Bytes from the position specified by the `position` property to the end of the file are deleted. The file must be open for writing.

Throws

| `IllegalOperationError` — The file is not open for writing.

Related API Elements

position
Example ( How to use this example )
The following code synchronously opens a test.txt file in the Apollo Test subdirectory of the user's documents directory and then trims the file to 100 characters in length if it is longer than 100 characters.
Copy

    import flash.filesystem.*;

    var file:File = File.documentsDirectory;
    file = file.resolvePath("Apollo Test/test.txt");
    var fileStream:FileStream = new FileStream();
    fileStream.open(file, FileMode.UPDATE);
    if (file.size > 100) {
        fileStream.position = 100;
        fileStream.truncate();
    }
    fileStream.close();

The following code asynchronously opens a test.txt file in the Apollo Test subdirectory of the user's documents directory, and then trims the file to 100 characters in length if it is longer than 100 characters.
Copy

    var file:File = File.documentsDirectory;
    file = file.resolvePath("Apollo Test/test.txt");
    var fileStream:FileStream = new FileStream();
    fileStream.openAsync(file, FileMode.UPDATE);
    trace("start", file.size)
    if (file.size > 100) {
        fileStream.position = 100;
        fileStream.truncate();
    }
    fileStream.addEventListener(Event.CLOSE, fileClosed);
    fileStream.close();
    function fileClosed(event:Event):void {
        trace("closed", file.size);
    }

### writeBoolean

()
method

`public function writeBoolean(value:Boolean):void`

Runtime Versions: | AIR 1.0

Writes a Boolean value. A single byte is written according to the `value` parameter, either 1 if `true` or 0 if `false`.

Parameters

| `value:Boolean` — A Boolean value determining which byte is written. If the parameter is `true`, 1 is written; if `false`, 0 is written.

Events

| `ioError:`IOErrorEvent`` — You cannot write to the file (for example, because the file is missing). This event is dispatched only for files that have been opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `IOError` — The file has not been opened; the file has been opened, but it was not opened with write capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be written (for example, because the file is missing).

### writeByte

()
method

`public function writeByte(value:int):void`

Runtime Versions: | AIR 1.0

Writes a byte. The low 8 bits of the parameter are used; the high 24 bits are ignored.

Parameters

| `value:int` — A byte value as an integer.

Events

| `ioError:`IOErrorEvent`` — You cannot write to the file (for example, because the file is missing). This event is dispatched only for files that have been opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `IOError` — The file has not been opened; the file has been opened, but it was not opened with write capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be written (for example, because the file is missing).

### writeBytes

()
method

`public function writeBytes(bytes:ByteArray, offset:uint = 0, length:uint = 0):void`

Runtime Versions: | AIR 1.0

Writes a sequence of bytes from the specified byte array, `bytes`, starting at the byte specified by `offset` (using a zero-based index) with a length specified by `length`, into the file stream, byte stream, or byte array.

If the `length` parameter is omitted, the default length of 0 is used and the entire buffer starting at `offset` is written. If the `offset` parameter is also omitted, the entire buffer is written.

If the `offset` or `length` parameter is out of range, they are clamped to the beginning and end of the `bytes` array.

Parameters

| `bytes:ByteArray` — The byte array to write.
| `offset:uint` (default = `0`)`` — A zero-based index specifying the position into the array to begin writing.
| `length:uint` (default = `0`)`` — An unsigned integer specifying how far into the buffer to write.

Events

| `ioError:`IOErrorEvent`` — You cannot write to the file (for example, because the file is missing). This event is dispatched only for files that have been opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `IOError` — The file has not been opened; the file has been opened, but it was not opened with write capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be written (for example, because the file is missing).

### writeDouble

()
method

`public function writeDouble(value:Number):void`

Runtime Versions: | AIR 1.0

Writes an IEEE 754 double-precision (64-bit) floating point number.

Parameters

| `value:Number` — A double-precision (64-bit) floating point number.

Events

| `ioError:`IOErrorEvent`` — You cannot write to the file (for example, because the file is missing). This event is dispatched only for files that have been opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `IOError` — The file has not been opened; the file has been opened, but it was not opened with write capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be written (for example, because the file is missing).

### writeFloat

()
method

`public function writeFloat(value:Number):void`

Runtime Versions: | AIR 1.0

Writes an IEEE 754 single-precision (32-bit) floating point number.

Parameters

| `value:Number` — A single-precision (32-bit) floating point number.

Events

| `ioError:`IOErrorEvent`` — You cannot write to the file (for example, because the file is missing). This event is dispatched only for files that have been opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `IOError` — The file has not been opened; the file has been opened, but it was not opened with write capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be written (for example, because the file is missing).

### writeInt

()
method

`public function writeInt(value:int):void`

Runtime Versions: | AIR 1.0

Writes a 32-bit signed integer.

Parameters

| `value:int` — A byte value as a signed integer.

Events

| `ioError:`IOErrorEvent`` — You cannot write to the file (for example, because the file is missing). This event is dispatched only for files that have been opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `IOError` — The file has not been opened; the file has been opened, but it was not opened with write capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be written (for example, because the file is missing).

### writeMultiByte

()
method

`public function writeMultiByte(value:String, charSet:String):void`

Runtime Versions: | AIR 1.0

Writes a multibyte string to the file stream, byte stream, or byte array, using the specified character set.

Parameters

| `value:String` — The string value to be written.
| `charSet:String` — The string denoting the character set to use. Possible character set strings include `"shift-jis"`, `"cn-gb"`, `"iso-8859-1"`, and others. For a complete list, see Supported Character Sets.

Events

| `ioError:`IOErrorEvent`` — You cannot write to the file (for example, because the file is missing). This event is dispatched only for files that have been opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `IOError` — The file has not been opened; the file has been opened, but it was not opened with write capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be written (for example, because the file is missing).

Related API Elements

File.systemCharset

### writeObject

()
method

`public function writeObject(object:*):void`

Runtime Versions: | AIR 1.0

Writes an object to the file stream, byte stream, or byte array, in AMF serialized format.

Parameters

| `object:*` — The object to be serialized.

Events

| `ioError:`IOErrorEvent`` — You cannot write to the file (for example, because the file is missing). This event is dispatched only for files that have been opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `IOError` — The file has not been opened; the file has been opened, but it was not opened with write capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be written (for example, because the file is missing).

Related API Elements

flash.net.registerClassAlias()

### writeShort

()
method

`public function writeShort(value:int):void`

Runtime Versions: | AIR 1.0

Writes a 16-bit integer. The low 16 bits of the parameter are used; the high 16 bits are ignored.

Parameters

| `value:int` — A byte value as an integer.

Events

| `ioError:`IOErrorEvent`` — You cannot write to the file (for example, because the file is missing). This event is dispatched only for files that have been opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `IOError` — The file has not been opened; the file has been opened, but it was not opened with write capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be written (for example, because the file is missing).

### writeUnsignedInt

()
method

`public function writeUnsignedInt(value:uint):void`

Runtime Versions: | AIR 1.0

Writes a 32-bit unsigned integer.

Parameters

| `value:uint` — A byte value as an unsigned integer.

Events

| `ioError:`IOErrorEvent`` — You cannot write to the file (for example, because the file is missing). This event is dispatched only for files that have been opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `IOError` — The file has not been opened; the file has been opened, but it was not opened with write capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be written (for example, because the file is missing).

### writeUTF

()
method

`public function writeUTF(value:String):void`

Runtime Versions: | AIR 1.0

Writes a UTF-8 string to the file stream, byte stream, or byte array. The length of the UTF-8 string in bytes is written first, as a 16-bit integer, followed by the bytes representing the characters of the string.

Parameters

| `value:String` — The string value to be written.

Events

| `ioError:`IOErrorEvent`` — You cannot write to the file (for example, because the file is missing). This event is dispatched only for files that have been opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `RangeError` — If the length of the string is larger than 65535.
| `IOError` — The file has not been opened; the file has been opened, but it was not opened with write capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be written (for example, because the file is missing).

### writeUTFBytes

()
method

`public function writeUTFBytes(value:String):void`

Runtime Versions: | AIR 1.0

Writes a UTF-8 string. Similar to `writeUTF()`, but does not prefix the string with a 16-bit length word.

Parameters

| `value:String` — The string value to be written.

Events

| `ioError:`IOErrorEvent`` — You cannot write to the file (for example, because the file is missing). This event is dispatched only for files that have been opened for asynchronous operations (by using the `openAsync()` method).

Throws

| `IOError` — The file has not been opened; the file has been opened, but it was not opened with write capabilities; or for a file that has been opened for synchronous operations (by using the `open()` method), the file cannot be written (for example, because the file is missing).

Event Detail

### close

Event

Event Object Type: `flash.events.Event`
property Event.type = `flash.events.Event.CLOSE`

Runtime Versions: | AIR 1.0

Indicates that the stream has been closed by an explicit call to the `close()` method.

The `Event.CLOSE` constant defines the value of the `type` property of a `close` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The object whose connection has been closed.

Related API Elements

close()

### complete

Event

Event Object Type: `flash.events.Event`
property Event.type = `flash.events.Event.COMPLETE`

Runtime Versions: | AIR 1.0

Signals that the end of the stream has been reached.

The `Event.COMPLETE` constant defines the value of the `type` property of a `complete` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The network object that has completed loading.

Related API Elements

position

### ioError

Event

Event Object Type: `flash.events.IOErrorEvent`
property IOErrorEvent.type = `flash.events.IOErrorEvent.IO_ERROR`

Runtime Versions: | AIR 1.0

Indicates that an error occurred during an asynchronous file I/O operation.

Defines the value of the `type` property of an `ioError` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`errorID` | A reference number associated with the specific error (AIR only).
`target` | The network object experiencing the input/output error.
`text` | Text to be displayed as an error message.

### outputProgress

Event

Event Object Type: `flash.events.OutputProgressEvent`
property OutputProgressEvent.type = `flash.events.OutputProgressEvent.OUTPUT_PROGRESS`

Runtime Versions: | AIR 1.0

Signals that buffered data has been written to the file.

Defines the value of the `type` property of an `outputProgress` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`bytesPending` | The number of bytes remaining to be written at the time the listener processes the event.
`bytesTotal` | The total number of bytes that ultimately will be written if the write process succeeds.
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The FileStream object reporting progress.

### progress

Event

Event Object Type: `flash.events.ProgressEvent`
property ProgressEvent.type = `flash.events.ProgressEvent.PROGRESS`

Runtime Versions: | AIR 1.0

Signals the availability of new data on the stream.

Defines the value of the `type` property of a `progress` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`bytesLoaded` | The number of items or bytes loaded at the time the listener processes the event.
`bytesTotal` | The total number of items or bytes that ultimately will be loaded if the loading process succeeds.
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The object reporting progress.

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00