Flash Media Server Resources

File class

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>/fmsapps;C:\Program Files\fms\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, /fmsapps/conference maps to c:/Program Files/fms/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.

Note: 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
`File.canAppend`	Read-only; a boolean value indicating whether a file can be appended (`true`) or not (`false`).
`File.canRead`	Read-only; A boolean value indicating whether a file can be read (`true`) or not (`false`).
`File.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.
`File.canWrite`	Read-only; a boolean value indicating whether a file can be written to (`true`) or not (`false`).
`File.creationTime`	Read-only; a Date object containing the time the file was created.
`File.exists`	Read-only; a boolean value indicating whether the file or directory exists (`true`) or not (`false`).
`File.isDirectory`	Read-only; a boolean value indicating whether the file is a directory (`true`) or not (`false`).
`File.isFile`	Read-only; a boolean value indicating whether the file is a regular data file (`true`) or not (`false`).
`File.isOpen`	Read-only; a boolean value indicating whether the file has been successfully opened and is still open (`true`) or not (`false`).
`File.lastModified`	Read-only; a Date object containing the time the file was last modified.
`File.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.
`File.mode`	Read-only; the mode of an open file.
`File.name`	Read-only; a string indicating the name of the file.
`File.position`	The current offset in the file.
`File.type`	Read-only; a string specifying the type of data or encoding used when a file is opened.

Method summary

Method	Description
`File.close()`	Closes the file.
`File.copyTo()`	Copies a file to a different location or copies it to the same location with a different filename.
`File.eof()`	Returns a boolean value indicating whether the file pointer is at the end of file (`true`) or not (`false`).
`File.flush()`	Flushes the output buffers of a file.
`File.list()`	If the file is a directory, lists the files in the directory.
`File.mkdir()`	Creates a directory.
`File.open()`	Opens a file so that you can read from it or write to it.
`File.read()`	Reads the specified number of characters from a file and returns a string.
`File.readAll()`	Reads the file after the location of the file pointer and returns an array with an element for each line of the file.
`File.readByte()`	Reads the next byte from the file and returns the numeric value of the next byte, or -1 if the operation fails.
`File.readln()`	Reads the next line from the file and returns it as a string.
`File.remove()`	Removes the file or directory pointed to by the File object.
`File.renameTo()`	Moves or renames a file.
`File.seek()`	Skips a specified number of bytes and returns the new file position.
`File.toString()`	Returns the path to the File object.
`File.write()`	Writes data to a file.
`File.writeAll()`	Takes an array as a parameter and calls the `File.writeln()` method on each element in the array.
`File.writeByte()`	Writes a byte to a file.
`File.writeln()`	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).

Note: 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.

Note: 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).

Note: 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.

Note: 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

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.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 actual end of the line. If the file opened in binary mode, the operation fails.

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

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.

Note: 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.

Note: 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.

Note: 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.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.

Note: 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!"); 
}

File class

Contents [Hide]

Availability

Property summary

Method summary

File constructor

Availability

Parameters

Returns

Example

File.canAppend

Availability

File.canRead

Availability

File.canReplace

Availability

File.canWrite

Availability

File.close()

Availability

Returns

Example

File.copyTo()

Availability

Parameters

Returns

Example

File.creationTime

Availability

File.eof()

Availability

Returns

Example

File.exists

Availability

File.flush()

Availability

Returns

File.isDirectory

Availability

File.isFile

Availability

File.isOpen

Availability

File.lastModified

Availability

File.length

Availability

File.list()

Availability

Parameters

Returns

Example

File.mkdir()

Availability

Parameters

Returns

Example

File.mode

Availability

See also

File.name

Availability

File.open()

Availability

Parameters

Returns

Example

File.position

Availability

File.read()

Availability

Parameters

Returns

Example

File.readAll()

Availability

Returns

File.readByte()

Availability