The File class lets applications write to the server’s file system. This is useful for storing information without using a database server, creating log files for debugging, and tracking usage. Also, a directory listing is useful for building a content list of streams or shared objects without using Flash Remoting.
By default, a script can access files and directories only within the application directory of the hosting application. A server administrator can grant access to additional directories by specifying virtual directory mappings for File object paths. This is done in the FileObject tag in the Application.xml file, as shown in the following example:
<FileObject> <VirtualDirectory>/videos;C:\myvideos</VirtualDirectory> <VirtualDirectory>/amsapps;C:\Program Files\ams\applications</VirtualDirectory> </FileObject>
This example specifies two additional directory mappings in addition to the default application directory. Any path that begins with /videos—for example, /videos/xyz/vacation.flv—maps to c:/myvideos/xyz/vaction.flv. Similarly, /amsapps/conference maps to c:/Program Files/ams/applications/conference. Any path that does not match a mapping resolves to the default application folder. For example, if c:/myapps/filetest is the application directory, then /streams/hello.flv maps to c:/myapps/filetest/streams/hello.flv.
You can use an Application.xml file at the virtual host level or at the application level.
In addition, the following rules are enforced by the server:
File objects cannot be created by using native file path specification.
File object paths must follow the URI convention:
A slash (/) must be used as the path separator. Access is denied if a path contains a backslash (\), or if a dot (.) or two dots (..) is the only string component found between path separators.
Root objects cannot be renamed or deleted.
For example, if a path using a slash (/) is used to create a File object, the application folder is mapped.
Availability
Flash Media Server 2
Property summary
Property |
Description |
|---|---|
Read-only; a boolean value indicating whether a file can be appended (true) or not (false). |
|
Read-only; A boolean value indicating whether a file can be read (true) or not (false). |
|
Read-only; A boolean value indicating whether a file was opened in "create" mode (true) or not (false). This property is undefined for closed files. |
|
Read-only; a boolean value indicating whether a file can be written to (true) or not (false). |
|
Read-only; a Date object containing the time the file was created. |
|
Read-only; a boolean value indicating whether the file or directory exists (true) or not (false). |
|
Read-only; a boolean value indicating whether the file is a directory (true) or not (false). |
|
Read-only; a boolean value indicating whether the file is a regular data file (true) or not (false). |
|
Read-only; a boolean value indicating whether the file has been successfully opened and is still open (true) or not (false). |
|
Read-only; a Date object containing the time the file was last modified. |
|
Read-only; for a directory, the number of files in the directory, not counting the current directory and parent directory entries; for a file, the number of bytes in the file. |
|
Read-only; the mode of an open file. |
|
Read-only; a string indicating the name of the file. |
|
The current offset in the file. |
|
Read-only; a string specifying the type of data or encoding used when a file is opened. |
Method summary
Method |
Description |
|---|---|
Closes the file. |
|
Copies a file to a different location or copies it to the same location with a different filename. |
|
Returns a boolean value indicating whether the file pointer is at the end of file (true) or not (false). |
|
Flushes the output buffers of a file. |
|
If the file is a directory, lists the files in the directory. |
|
Creates a directory. |
|
Opens a file so that you can read from it or write to it. |
|
Reads the specified number of characters from a file and returns a string. |
|
Reads the file after the location of the file pointer and returns an array with an element for each line of the file. |
|
Reads the next byte from the file and returns the numeric value of the next byte, or -1 if the operation fails. |
|
Reads a specified number of bytes from a file into a ByteArray. |
|
Reads the next line from the file and returns it as a string. |
|
Removes the file or directory pointed to by the File object. |
|
Moves or renames a file. |
|
Skips a specified number of bytes and returns the new file position. |
|
Returns the path to the File object. |
|
Writes data to a file. |
|
Takes an array as a parameter and calls the File.writeln() method on each element in the array. |
|
Writes a byte to a file. |
|
Writes a specified number of bytes to a file from a ByteArray. |
|
Writes data to a file and adds a platform-dependent end-of-line character after outputting the last parameter. |
File constructor
fileObject = new File(name)
Creates an instance of the File class.
Availability
Flash Media Server 2
Parameters
name
A string indicating the name of the file or directory. The name can contain only UTF-8 encoded characters; high byte values can be encoded by using the URI character-encoding scheme. The specified name is mapped to a system path by using the mappings specified in the FileObject section of the Application.xml file. If the path is invalid, the name property of the object is set to an empty string, and no file operation can be performed.
Returns
A File object if successful; otherwise, null.
Example
The following code creates an instance of the File class:
var errorLog = new File("/logs/error.txt");
Note that the physical file isn’t created on the hard disk until you call File.open().
File.canAppend
fileObject.canAppend
Read only; a boolean value indicating whether a file can be appended (true) or not (false). The property is undefined for closed files.
Availability
Flash Media Server 2.0
File.canRead
fileObject.canRead
Read-only; A boolean value indicating whether a file can be read (true) or not (false).
Availability
Flash Media Server 2
File.canReplace
fileObject.canReplace
Read-only; A boolean value indicating whether a file was opened in "create" mode (true) or not (false). This property is undefined for closed files.
Availability
Flash Media Server 2
File.canWrite
fileObject.canWrite
Read only; a boolean value indicating whether a file can be written to (true) or not (false).
If File.open() was called to open the file, the mode in which the file was opened is respected. For example, if the file was opened in read mode, you can read from the file, but you cannot write to the file.
Availability
Flash Media Server 2
File.close()
fileObject.close()
Closes the file. This method is called automatically on an open File object when the object is out of scope.
Availability
Flash Media Server 2
Returns
A boolean value indicating whether the file was closed successfully (true) or not (false). Returns false if the file is not open.
Example
The following code closes the /path/file.txt file:
if (x.open("/path/file.txt", "read") ){
// Do something here.
x.close();
}
File.copyTo()
fileObject.copyTo(name)
Copies a file to a different location or copies it to the same location with a different filename. This method returns false if the source file doesn't exist or if the source file is a directory. When this method fails, it invokes the application.onStatus() event handler to report errors.
The user or process owner that the server runs under in the operating system must have adequate write permissions or the call can fail.
Availability
Flash Media Server 2
Parameters
name
Specifies the name of the destination file. The name can contain only UTF-8 characters; high byte values can be encoded by using the URI character-encoding scheme. The name specified is mapped to a system path by using the mappings specified in the Application.xml file. If the path is invalid or if the destination file doesn’t exist, the operation fails, and the method returns false.
Returns
A boolean value indicating whether the file is copied successfully (true) or not (false).
Example
The following code copies the file set by the myFileObj File object to the location provided by the parameter:
if (myFileObj.copyTo( "/logs/backup/hello.log")){
// Do something here.
}
File.creationTime
fileObject.creationTime
Read-only; a Date object containing the time the file was created.
Availability
Flash Media Server 2
File.eof()
fileObject.eof()
Returns a boolean value indicating whether the file pointer is at the end of file (true) or not (false). If the file is closed, the method returns true.
Availability
Flash Media Server 2
Returns
A boolean value.
Example
The following while statement lets you insert code that is executed until the file pointer is at the end of a file:
while (!myFileObj.eof()){
// Do something here.
}
File.exists
fileObject.exists
Read-only; a boolean value indicating whether the file or directory exists (true) or not (false).
Availability
Flash Media Server 2
File.flush()
fileObject.flush()
Flushes the output buffers of a file. If the file is closed, the operation fails. When this method fails, it invokes the application.onStatus() event handler to report errors.
Availability
Flash Media Server 2
Returns
A boolean value indicating whether the flush operation was successful (true) or not (false).
File.isDirectory
fileObject.isDirectory
Read-only; a boolean value indicating whether the file is a directory (true) or not (false).
A File object that represents a directory has properties that represent the files contained in the directory. These properties have the same names as the files in the directory, as shown in the following example:
myDir = new File("/some/directory");
myFileInDir = myDir.fileName;
trace(myDir.isDirectory) // Outputs true.
The following example uses named property lookup to refer to files that do not have valid property names:
mySameFileInDir = myDir["fileName"]; myOtherFile = myDir["some long filename with spaces"];
Availability
Flash Media Server 2
File.isFile
fileObject.isFile
Read-only; a boolean value indicating whether a file is a regular data file (true) or not (false).
Availability
Flash Media Server 2
File.isOpen
fileObject.isOpen
Read-only; a boolean value indicating whether the file has been successfully opened and is still open (true) or not (false).
Directories do not need to be opened.
Availability
Flash Media Server 2
File.lastModified
fileObject.lastModified
Read-only; a Date object containing the time the file was last modified.
Availability
Flash Media Server 2
File.length
fileObject.length
Read-only; for a directory, the number of files in the directory, not counting the current directory and parent directory entries; for a file, the number of bytes in the file.
Availability
Flash Media Server 2
File.list()
fileObject.list(filter)
If the file is a directory, lists the files in the directory. Returns an array with an element for each file in the directory.
Availability
Flash Media Server 2
Parameters
filter
A Function object that determines the files in the returned array.
If the function returns true when a file’s name is passed to it as a parameter, the file is added to the array returned by File.list(). This parameter is optional and allows you to filter the results of the call.
Returns
An Array object.
Example
The following example returns files in the current directory that have 3-character names:
var a = x.currentDir.list(function(name){return name.length==3;});
File.mkdir()
fileObject.mkdir(newDir)
Creates a directory. The directory is created in the directory specified by fileObject. When this method fails, it invokes the application.onStatus() event handler to report errors.
The user or process owner that the server runs under in the operating system must have adequate write permissions or the call can fail.
You cannot call this method from a File object that is a file (where isFile is true). You must call this method from a File object that is a directory (where isDirectory is true).
Availability
Flash Media Server 2
Parameters
newDir
A string indicating the name of the new directory. This name is relative to the current File object instance.
Returns
A boolean value indicating success (true) or failure (false).
Example
The following example creates a logs directory in the myFileObject instance:
if (myFileObject.mkdir("logs")){
// Do something if a logs directory is created successfully.
}
File.mode
fileObject.mode
Read-only; the mode of an open file. It can be different from the mode parameter that was passed to the open() method for the file if you have repeating attributes (for example, "read, read") or if some attributes were ignored. If the file is closed, the property is undefined.
Availability
Flash Media Server 2
See also
File.name
fileObject.name
Read-only; a string indicating the name of the file. If the File object was created with an invalid path, the value is an empty string.
Availability
Flash Media Server 2
File.open()
fileObject.open(type, mode)
Opens a file so that you can read from it or write to it. First use the File constructor to create a File object and then call open() on that object. When the open() method fails, it invokes the application.onStatus() event handler to report errors.
Availability
Flash Media Server 2
Parameters
type
A string indicating the encoding type for the file. The following types are supported (there is no default value):
Value |
Description |
|---|---|
"text" |
Opens the file for text access by using the default file encoding. |
"binary" |
Opens the file for binary access. |
"utf8" |
Opens the file for UTF-8 access. |
mode
A string indicating the mode in which to open the file. The following modes are valid and can be combined (modes are case sensitive and multiple modes must be separated by commas—for example, "read,write"; there is no default value):
Value |
Description |
|---|---|
"read" |
Opens a file for reading. |
"write" |
Opens a file for writing. |
"readWrite" |
Opens a file for both reading and writing. |
"append" |
Opens a file for writing and positions the file pointer at the end of the file when you attempt to write to the file. |
"create" |
Creates a new file if the file is not present. If a file exists, its contents are destroyed and a new file is created. |
Note: If both "read" and "write" are set, "readWrite" is automatically set. The user or process owner that the server runs under in the operating system must have write permissions to use "create", "append", "readWrite", and "write" modes.
Returns
A boolean value indicating whether the file opened successfully (true) or not (false).
Example
The following client-side script creates a connection to an application called file:
var nc:NetConnection = new NetConnection();
function traceStatus(info) {
trace("Level: " + info.level + " Code: " + info.code);
}
nc.onStatus = traceStatus;
nc.connect("rtmp:/file");
The following server-side script creates a text file called log.txt and writes text to the file:
application.onConnect = function(client){
this.acceptConnection(client);
var logFile = new File("log.txt");
if(!logFile.exists){
logFile.open("text", "append");
logFile.write("something", "somethingElse")
}
};
File.position
fileObject.position
The current offset in the file. This is the only property of the File class that can be set. Setting this property performs a seek operation on the file. The property is undefined for closed files.
Availability
Flash Media Server 2
File.read()
fileObject.read(numChars)
Reads the specified number of characters from a file and returns a string. If the file is opened in binary mode, the operation fails. When this method fails, it invokes the application.onStatus() event handler to report errors.
Availability
Flash Media Server 2
Parameters
numChars
A number specifying the number of characters to read. If numChars specifies more bytes than are left in the file, the method reads to the end of the file.
Returns
A string.
Example
The following code opens a text file in read mode and sets variables for the first 100 characters, a line, and a byte:
if (myFileObject.open("text", "read")){
strVal = myFileObject.read(100);
strLine = myFileObject.readln();
strChar = myFileObject.readByte();
}
File.readAll()
fileObject.readAll()
Reads the file after the location of the file pointer and returns an Array object with an element for each line of the file. If the file opened in binary mode, the operation fails. When this method fails, it invokes the application.onStatus() event handler to report errors.
Availability
Flash Media Server 2
Returns
An Array object.
File.readByte()
fileObject.readByte()
Reads the next byte from the file and returns the numeric value of the next byte or -1if the operation fails. If the file is not opened in binary mode, the operation fails.
Availability
Flash Media Server 2
Returns
A number; either a positive integer or -1.
File.readBytes()
fileObject.readBytes(dest, offset, length)
Reads the number of bytes specified by the length parameter from the fileObject into the dest parameter starting at the offset within dest. This method throws an EOFError if length exceeds File.length - File.position.
Availability
Flash Media Server 4
Parameters
dest
A ByteArray into which bytes from the fileObject are read.
offset
An integer specifying an offset location within the ByteArray specified in the dest parameter. This parameter is optional. The default value is 0.
length
An integer specifying the number of bytes to read from the fileObject. This parameter is optional. The default value is File.length - File.position.
Returns
Nothing.
File.readln()
fileObject.readln()
Reads the next line from the file and returns it as a string. The line-separator characters (either \r\n on Windows or \n on Linux) are not included in the string. The character \r is skipped; \n determines the end of the line. If the file opened in binary mode, the operation fails.
The File.readln() method has a maximum character limit of around 4100 characters. To read more characters, call File.readAll().join('').
Availability
Flash Media Server 2
Returns
A string.
File.remove()
fileObject.remove(recursive)
Removes the file or directory pointed to by the File object. When this method fails, it invokes the application.onStatus() event handler to report errors.
Availability
Flash Media Server 2
Parameters
recursive
A boolean value specifying whether to do a recursive removal of the directory and all its contents (true), or a nonrecursive removal of the directory contents (false). If no value is specified, the default value is false. If fileObject is not a directory, any parameters passed to the remove() method are ignored.
Returns
A boolean value indicating whether the file or directory was removed successfully (true) or not (false). Returns false if the file is open, the path points to a root folder, or the directory is not empty.
Example
The following example shows the creation and removal of a file:
fileObject = new File("sharedobjects/_definst_/userIDs.fso");
fileObject.remove();
File.renameTo()
fileObject.renameTo(name)
Moves or renames a file. If the file is open or the directory points to the root directory, the operation fails. When this method fails, it invokes the application.onStatus() event handler to report errors.
Availability
Flash Media Server 2
Parameters
name
The new name for the file or directory. The name can contain only UTF-8-encoded characters; high byte values can be encoded by using the URI character-encoding scheme. The specified name is mapped to a system path by using the mappings specified in the Application.xml file. If the path is invalid or the destination file doesn’t exist, the operation fails.
Returns
A boolean value indicating whether the file was successfully renamed or moved (true) or not (false).
File.seek()
fileObject.seek(numBytes)
Skips a specified number of bytes and returns the new file position. This method can accept both positive and negative parameters.
Availability
Flash Media Server 2
Parameters
numBytes
A number indicating the number of bytes to move the file pointer from the current position.
Returns
If the operation is successful, returns the current position in the file; otherwise, returns -1. If the file is closed, the operation fails and calls application.onStatus() to report a warning. The operation returns -1 when called on a directory.
File.toString()
fileObject.toString()
Returns the path to the File object.
Availability
Flash Media Server 2
Returns
A string.
Example
The following example outputs the path of the File object myFileObject:
trace(myFileObject.toString());
File.type
fileObject.type
Read-only; a string specifying the type of data or encoding used when a file is opened. The following strings are supported: "text", "utf8", and "binary". This property is undefined for directories and closed files. If the file is opened in "text" mode and UTF-8 BOM (Byte Order Mark) is detected, the type property is set to "utf8".
Availability
Flash Media Server 2.0
See also
File.open()
File.write()
fileObject.write(param0, param1,...paramN)
Writes data to a file. The write() method converts each parameter to a string and then writes it to the file without separators. The file contents are buffered internally. The File.flush() method writes the buffer to the file on disk. When this method fails, it invokes the application.onStatus() event handler to report errors.
The user or process owner that the server runs under in the operating system must have write permissions or this call can fail.
Availability
Flash Media Server 2
Parameters
param0, param1,...paramN
Parameters to write to the file.
Returns
A boolean value indicating whether the write operation was successful (true) or not (false).
Example
The following example writes "Hello world" at the end of the myFileObject text file:
if (myFileObject.open( "text", "append") ) {
myFileObject.write("Hello world");
}
File.writeAll()
fileObject.writeAll(array)
Takes an Array object as a parameter and calls the File.writeln() method on each element in the array. The file contents are buffered internally. The File.flush() method writes the buffer to the file on disk.
The user or process owner that the server runs under in the operating system must have write permissions or this call can fail.
Availability
Flash Media Server 2
Parameters
array
An Array object containing all the elements to write to the file.
Returns
A boolean value indicating whether the write operation was successful (true) or not (false).
File.writeByte()
fileObject.writeByte(number)
Writes a byte to a file. The file contents are buffered internally. The File.flush() method writes the buffer to the file on disk.
The user or process owner that the server runs under in the operating system must have write permissions or this call can fail.
Availability
Flash Media Server 2
Parameters
number
A number to write.
Returns
A boolean value indicating whether the write operation was successful (true) or not (false).
Example
The following example writes byte 65 to the end of the myFileObject file:
if (myFileObject.open("text","append")) {
myFileObject.writeByte(65);
}
File.writeBytes()
fileObject.writeBytes(source, offset, length)
Writes length number of bytes to the fileObject from the source starting at the offset within source. This method throws an EOFError if length exceeds source.length - offset.
Availability
Flash Media Server 4
Parameters
source
A ByteArray from which bytes to the fileObject are written.
offset
An integer specifying an offset location within the ByteArray specifyed in the source parameter. This parameter is optional. The default value is 0.
length
An integer specifying the number of bytes to write to the fileObject. This parameter is optional. The default value is source.length - offset.
Returns
Nothing.
File.writeln()
fileObject.writeln(param0, param1,...paramN)
Writes data to a file and adds a platform-dependent end-of-line character after outputting the last parameter. The file contents are buffered internally. The File.flush() method writes the buffer to the file on disk.
The user or process owner that the server runs under in the operating system must have write permissions or this call can fail.
Availability
Flash Media Server 2
Parameters
param0, param1,...paramN
Strings to write to the file.
Returns
A boolean value indicating whether the write operation was successful (true) or not (false).
Example
The following example opens a text file for writing and writes a line:
if (fileObj.open( "text", "append") ) {
fileObj.writeln("This is a line!");
}