Adobe® Flex® 4 Language Reference
Show Packages and Classes List |  Packages  |  Classes  |  Index  |  Appendixes
flash.filesystem 
FileStream 
Packageflash.filesystem
Classpublic class FileStream
InheritanceFileStream Inheritance EventDispatcher Inheritance 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.



Public Properties
 PropertyDefined By
  AIR-only bytesAvailable : uint
[read-only] Returns the number of bytes of data available for reading in the input buffer.
FileStream
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
  AIR-only endian : String
The byte order for the data, either the BIG_ENDIAN or LITTLE_ENDIAN constant from the Endian class.
FileStream
  AIR-only 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
  AIR-only position : Number
The current position in the file.
FileStream
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
  AIR-only readAhead : Number
When reading files asynchronously, the amount of data requested.
FileStream
Public Methods
 MethodDefined By
  
Creates a FileStream object.
FileStream
 Inherited
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
  
Closes the FileStream object.
FileStream
 Inherited
Dispatches an event into the event flow.
EventDispatcher
 Inherited
Checks whether the EventDispatcher object has any listeners registered for a specific type of event.
EventDispatcher
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
  
AIR-only open(file:File, fileMode:String):void
Opens the FileStream object synchronously, pointing to the file specified by the file parameter.
FileStream
  
AIR-only openAsync(file:File, fileMode:String):void
Opens the FileStream object asynchronously, pointing to the file specified by the file parameter.
FileStream
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
  
Reads a Boolean value from the file stream, byte stream, or byte array.
FileStream
  
Reads a signed byte from the file stream, byte stream, or byte array.
FileStream
  
AIR-only 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
  
Reads an IEEE 754 double-precision floating point number from the file stream, byte stream, or byte array.
FileStream
  
Reads an IEEE 754 single-precision floating point number from the file stream, byte stream, or byte array.
FileStream
  
Reads a signed 32-bit integer from the file stream, byte stream, or byte array.
FileStream
  
AIR-only 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
  
Reads an object from the file stream, byte stream, or byte array, encoded in AMF serialized format.
FileStream
  
Reads a signed 16-bit integer from the file stream, byte stream, or byte array.
FileStream
  
Reads an unsigned byte from the file stream, byte stream, or byte array.
FileStream
  
Reads an unsigned 32-bit integer from the file stream, byte stream, or byte array.
FileStream
  
Reads an unsigned 16-bit integer from the file stream, byte stream, or byte array.
FileStream
  
Reads a UTF-8 string from the file stream, byte stream, or byte array.
FileStream
  
Reads a sequence of UTF-8 bytes from the byte stream or byte array and returns a string.
FileStream
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Removes a listener from the EventDispatcher object.
EventDispatcher
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns the string representation of the specified object.
Object
  
Truncates the file at the position specified by the position property of the FileStream object.
FileStream
 Inherited
Returns the primitive value of the specified object.
Object
 Inherited
Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.
EventDispatcher
  
Writes a Boolean value.
FileStream
  
AIR-only writeByte(value:int):void
Writes a byte.
FileStream
  
AIR-only 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
  
Writes an IEEE 754 double-precision (64-bit) floating point number.
FileStream
  
Writes an IEEE 754 single-precision (32-bit) floating point number.
FileStream
  
AIR-only writeInt(value:int):void
Writes a 32-bit signed integer.
FileStream
  
AIR-only 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
  
AIR-only writeObject(object:*):void
Writes an object to the file stream, byte stream, or byte array, in AMF serialized format.
FileStream
  
Writes a 16-bit integer.
FileStream
  
Writes a 32-bit unsigned integer.
FileStream
  
Writes a UTF-8 string to the file stream, byte stream, or byte array.
FileStream
  
Writes a UTF-8 string.
FileStream
Events
 Event Summary Defined By
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.EventDispatcher
  Indicates that the stream has been closed by an explicit call to the close() method.FileStream
  Signals that the end of the stream has been reached.FileStream
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.EventDispatcher
  Indicates that an error occurred during an asynchronous file I/O operation.FileStream
  Signals that buffered data has been written to the file.FileStream
  Signals the availability of new data on the stream.FileStream
Property Detail
AIR-only 

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
AIR-only 

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
AIR-only 

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

See also

AIR-only 

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

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.
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();
}
AIR-only 

readAhead

property 
readAhead:Number

Runtime Versions: AIR 1.0

When reading files asynchronously, the amount of data requested.

This property specifies how much data an asynchronous stream attempts to read beyond the current position. 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:
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
AIR-only 

FileStream

()Constructor
public function FileStream()

Runtime Versions: AIR 1.0

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

See also

Method Detail

AIR-only 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.

See also


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.
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.
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();

AIR-only 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.

See also


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.
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();

AIR-only 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.

See also


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.
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();
}

AIR-only 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).

AIR-only 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).

AIR-only 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).

AIR-only 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).

AIR-only 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).

AIR-only 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).

AIR-only 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).

See also

AIR-only 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).

See also

AIR-only 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).

AIR-only 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).

AIR-only 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).

AIR-only 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).

AIR-only 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).

AIR-only 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).

AIR-only 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.

See also


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.
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.
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); 
}

AIR-only 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).

AIR-only 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).

AIR-only 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).

AIR-only 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).

AIR-only 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).

AIR-only 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).

AIR-only 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).

See also

AIR-only 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).

See also

AIR-only 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).

AIR-only 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).

AIR-only 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).

AIR-only 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
AIR-only 

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:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
targetThe object whose connection has been closed.

See also

AIR-only 

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:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
targetThe network object that has completed loading.

See also

AIR-only 

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:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
errorIDA reference number associated with the specific error (AIR only).
targetThe network object experiencing the input/output error.
textText to be displayed as an error message.
AIR-only 

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:

PropertyValue
bubblesfalse
bytesPendingThe number of bytes remaining to be written at the time the listener processes the event.
bytesTotalThe total number of bytes that ultimately will be written if the write process succeeds.
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
targetThe FileStream object reporting progress.
AIR-only 

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:

PropertyValue
bubblesfalse
bytesLoadedThe number of items or bytes loaded at the time the listener processes the event.
bytesTotalThe total number of items or bytes that ultimately will be loaded if the loading process succeeds.
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
targetThe object reporting progress.