Working with File objects



A File object is a pointer to a file or directory in the file system.

The File class extends the FileReference class. The FileReference class, which is available in Adobe® Flash® Player as well as AIR, represents a pointer to a file, but the File class adds properties and methods that are not exposed in Flash Player (in a SWF file running in a browser), due to security considerations.

About the File class

You can use the File class for the following:

  • Getting the path to special directories, including the user directory, the user's documents directory, the directory from which the application was launched, and the application directory

  • Coping files and directories

  • Moving files and directories

  • Deleting files and directories (or moving them to the trash)

  • Listing files and directories contained in a directory

  • Creating temporary files and folders

Once a File object points to a file path, you can use it to read and write file data, using the FileStream class.

A File object can point to the path of a file or directory that does not yet exist. You can use such a File object in creating a file or directory.

Paths of File objects

Each File object has two properties that each define its path:

Property

Description

nativePath

Specifies the platform-specific path to a file. For example, on Windows a path might be "c:\Sample directory\test.txt" whereas on Mac OS it could be "/Sample directory/test.txt". A nativePath property uses the backslash (\) character as the directory separator character on Windows, and it uses the forward slash (/) character on Mac OS and Linux.

url

This may use the file URL scheme to point to a file. For example, on Windows a path might be "file:///c:/Sample%20directory/test.txt" whereas on Mac OS it could be "file:///Sample%20directory/test.txt". The runtime includes other special URL schemes besides file and are described in Supported URL schemes

The File class includes static properties for pointing to standard directories on Mac OS, Windows, and Linux. These properties include:

  • File.applicationStorageDirectory—a storage directory unique to each installed AIR application

  • File.applicationDirectory—the directory where the application is installed (along with any installed assets)

  • File.desktopDirectory—the user’s desktop directory

  • File.documentsDirectory—the user’s documents directory

  • File.userDirectory—the user directory

These properties have meaningful values on different operating systems. For example, Mac OS, Linux, and Windows each have different native paths to the user’s desktop directory. However, the File.desktopDirectory property points to the correct desktop directory path on each of these platforms. To write applications that work well across platforms, use these properties as the basis for referencing other directories and files used by the application. Then use the resolvePath() method to refine the path. For example, this code points to the preferences.xml file in the application storage directory:

var prefsFile:File = air.File.applicationStorageDirectory; 
prefsFile = prefsFile.resolvePath("preferences.xml");

Although the File class lets you point to a specific file path, doing so can lead to applications that will not work across platforms. For example, the path C:\Documents and Settings\joe\ only works on Windows. For these reasons, it is best to use the static properties of the File class, such as File.documentsDirectory.

More information on these File properties is provided in the next section.

Pointing a File object to a directory

There are different ways to set a File object to point to a directory.

Pointing to the user’s home directory

You can point a File object to the user’s home directory. The path varies by operating system. On Windows XP, for example, the home directory is the parent of the "My Documents" directory (for example, "C:\Documents and Settings\userName\My Documents"). On Mac OS, it is the Users/userName directory. On Linux, it is the /home/userName directory. The following code sets a File object to point to an AIR Test subdirectory of the home directory:

var file = air.File.userDirectory.resolvePath("AIR Test");

Pointing to the user’s documents directory

You can point a File object to the user's documents directory. On Windows, the default location is the "My Documents" directory (for example, "C:\Documents and Settings\userName\My Documents"). On Mac OS, the default location is the Users/userName/Documents directory. On Linux, the default location is the /home/userName/Documents directory. The following code sets a File object to point to an AIR Test subdirectory of the documents directory:

var file = air.File.documentsDirectory.resolvePath("AIR Test");

Pointing to the desktop directory

You can point a File object to the desktop. The following code sets a File object to point to an AIR Test subdirectory of the desktop:

var file = air.File.desktopDirectory.resolvePath("AIR Test");

Pointing to the application storage directory

You can point a File object to the application storage directory. For every AIR application, there is a unique associated path that defines the application storage directory. This directory is unique to each application and user. You may want to use this directory to store user-specific, application-specific data (such as user data or preferences files). For example, the following code points a File object to a preferences file, prefs.xml, contained in the application storage directory:

var file = air.File.applicationStorageDirectory; 
file = file.resolvePath("prefs.xml");

The application storage directory location is based on the user name, the application ID, and, if defined, the publisher ID:

  • On Mac OS—In:

    /Users/user name/Library/Preferences/applicationID.publisherID/Local Store/

    For example:

    /Users/babbage/Library/Preferences/com.example.TestApp.02D88EEED35F84C264A183921344EEA353A629FD.1/Local Store
  • On Windows—In the documents and Settings directory, in:

    user name/Application Data/applicationID.publisherID/Local Store/

    For example:

    C:\Documents and Settings\babbage\Application Data\com.example.TestApp.02D88EEED35F84C264A183921344EEA353A629FD.1\Local Store
  • On Linux—In:

    /home/user name/.appdata/applicationID.publisherID/Local Store/

    For example:

    /home/babbage/.appdata/com.example.TestApp.02D88EEED35F84C264A183921344EEA353A629FD.1/Local Store

The URL (and url property) for a File object created with File.applicationStorageDirectory uses the app-storage URL scheme (see Supported URL schemes), as in the following:

var dir = air.File.applicationStorageDirectory; 
dir = dir.resolvePath("prefs.xml"); 
air.trace(dir.url); // app-storage:/preferences
Note: If the publisher ID changes during an update signed with a migration signature, AIR creates a new application storage directory for the updated application. The files in the original directory are not removed, but the applicationStorageDirectory property and app-storage URL schemes resolve to the new directory instead of the old one. A publisher ID change can only occur with updates that specify AIR version 1.5.2, or earlier, in the application descriptor. After AIR 1.5.3, the publisher ID cannot change as a result of an update.

Pointing to the application directory

You can point a File object to the directory in which the application was installed, known as the application directory. You can reference this directory using the File.applicationDirectory property. You may use this directory to examine the application descriptor file or other resources installed with the application. For example, the following code points a File object to a directory named images in the application directory:

var dir = air.File.applicationDirectory; 
dir = dir.resolvePath("images");

The URL (and url property) for a File object created with File.applicationDirectory uses the app URL scheme (see Supported URL schemes), as in the following:

var dir = air.File.applicationDirectory; 
dir = dir.resolvePath("images"); 
air.trace(dir.url); // app:/images

Pointing to the filesystem root

The File.getRootDirectories() method lists all root volumes, such as C: and mounted volumes, on a Windows computer. On Mac OS and Linux, this method always returns the unique root directory for the machine (the "/" directory).

Pointing to an explicit directory

You can point the File object to an explicit directory by setting the nativePath property of the File object, as in the following example (on Windows):

var file = new air.File(); 
file.nativePath = "C:\\AIR Test\";

Important: Pointing to an explicit path this way can lead to code that does not work across platforms. For example, the previous example only works on Windows. You should use the static properties of the File object, such as File.applicationStorageDirectory, to locate a directory that works cross-platform. Then use the resolvePath() method (see the next section) to navigate to a relative path.

Navigating to relative paths

You can use the resolvePath() method to obtain a path relative to another given path. For example, the following code sets a File object to point to an "AIR Test" subdirectory of the user's home directory:

var file = air.File.userDirectory; 
file = file.resolvePath("AIR Test");

You can also use the url property of a File object to point it to a directory based on a URL string, as in the following:

var urlStr = "file:///C:/AIR Test/"; 
var file = new air.File() 
file.url = urlStr;

For more information, see Modifying File paths.

Letting the user browse to select a directory

The File class includes the browseForDirectory() method, which presents a system dialog box in which the user can select a directory to assign to the object. The browseForDirectory() method is asynchronous. It dispatches a select event if the user selects a directory and clicks the Open button, or it dispatches a cancel event if the user clicks the Cancel button.

For example, the following code lets the user select a directory and outputs the directory path upon selection:

var file = new air.File(); 
file.addEventListener(air.Event.SELECT, dirSelected); 
file.browseForDirectory("Select a directory"); 
function dirSelected(event) { 
    alert(file.nativePath); 
}

Pointing to the directory from which the application was invoked

You can get the directory location from which an application is invoked, by checking the currentDirectory property of the InvokeEvent object dispatched when the application is invoked. For details, see Capturing command line arguments.

Pointing a File object to a file

There are different ways to set the file to which a File object points.

Pointing to an explicit file path

Important: Pointing to an explicit path can lead to code that does not work across platforms. For example, the path C:/foo.txt only works on Windows. You should use the static properties of the File object, such as File.applicationStorageDirectory, to locate a directory that works cross-platform. Then use the resolvePath() method (see Modifying File paths) to navigate to a relative path.

You can use the url property of a File object to point it to a file or directory based on a URL string, as in the following:

var urlStr = "file:///C:/AIR Test/test.txt"; 
var file = new air.File() 
file.url = urlStr;

You can also pass the URL to the File() constructor function, as in the following:

var urlStr = "file:///C:/AIR Test/test.txt"; 
var file = new air.File(urlStr);

The url property always returns the URI-encoded version of the URL (for example, blank spaces are replaced with "%20):

file.url = "file:///c:/AIR Test"; 
alert(file.url); // file:///c:/AIR%20Test

You can also use the nativePath property of a File object to set an explicit path. For example, the following code, when run on a Windows computer, sets a File object to the test.txt file in the AIR Test subdirectory of the C: drive:

var file = new air.File(); 
file.nativePath = "C:/AIR Test/test.txt";

You can also pass this path to the File() constructor function, as in the following:

var file = new air.File("C:/AIR Test/test.txt");

Use the forward slash (/) character as the path delimiter for the nativePath property. On Windows, you can also use the backslash (\) character, but doing so leads to applications that do not work across platforms.

For more information, see Modifying File paths.

Enumerating files in a directory

You can use the getDirectoryListing() method of a File object to get an array of File objects pointing to files and subdirectories at the root level of a directory. For more information, see Enumerating directories.

Letting the user browse to select a file

The File class includes the following methods that present a system dialog box in which the user can select a file to assign to the object:

  • browseForOpen()

  • browseForSave()

  • browseForOpenMultiple()

These methods are each asynchronous. The browseForOpen() and browseForSave() methods dispatch the select event when the user selects a file (or a target path, in the case of browseForSave()). With the browseForOpen() and browseForSave() methods, upon selection the target File object points to the selected files. The browseForOpenMultiple() method dispatches a selectMultiple event when the user selects files. The selectMultiple event is of type FileListEvent, which has a files property that is an array of File objects (pointing to the selected files).

For example, the following code presents the user with an “Open” dialog box in which the user can select a file:

var fileToOpen = air.File.documentsDirectory; 
selectTextFile(fileToOpen); 
 
function selectTextFile(root) 
{ 
    var txtFilter = new air.FileFilter("Text", "*.as;*.css;*.html;*.txt;*.xml"); 
    root.browseForOpen("Open", new window.runtime.Array(txtFilter)); 
    root.addEventListener(air.Event.SELECT, fileSelected); 
} 
 
function fileSelected(event) 
{ 
    trace(fileToOpen.nativePath); 
}

If the application has another browser dialog box open when you call a browse method, the runtime throws an Error exception.

Modifying File paths

You can also modify the path of an existing File object by calling the resolvePath() method or by modifying the nativePath or url property of the object, as in the following examples (on Windows):

file1 = air.File.documentsDirectory; 
file1 = file1.resolvePath("AIR Test"); 
alert(file1.nativePath); // C:\Documents and Settings\userName\My Documents\AIR Test 
var file2 = air.File.documentsDirectory; 
file2 = file2.resolvePath(".."); 
alert(file2.nativePath); // C:\Documents and Settings\userName 
var file3 = air.File.documentsDirectory; 
file3.nativePath += "/subdirectory"; 
alert(file3.nativePath); // C:\Documents and Settings\userName\My Documents\subdirectory 
var file4 = new air.File(); 
file4.url = "file:///c:/AIR Test/test.txt"; 
alert(file4.nativePath); // C:\AIR Test\test.txt

When using the nativePath property, use the forward slash (/) character as the directory separator character. On Windows, you can use the backslash (\) character as well, but you should not do so, as it leads to code that does not work cross-platform.

Supported URL schemes

You can use any of the following URL schemes in defining the url property of a File object:

URL scheme

Description

file

Use to specify a path relative to the root of the file system. For example:

file:///c:/AIR Test/test.txt

The URL standard specifies that a file URL takes the form file://<host>/<path>. As a special case,<host> can be the empty string, which is interpreted as "the machine from which the URL is being interpreted." For this reason, file URLs often have three slashes (///).

app

Use to specify a path relative to the root directory of the installed application (the directory that contains the application.xml file for the installed application). For example, the following path points to an images subdirectory of the directory of the installed application:

app:/images

app-storage

Use to specify a path relative to the application store directory. For each installed application, AIR defines a unique application store directory, which is a useful place to store data specific to that application. For example, the following path points to a prefs.xml file in a settings subdirectory of the application store directory:

app-storage:/settings/prefs.xml

Finding the relative path between two files

You can use the getRelativePath() method to find the relative path between two files:

var file1 = air.File.documentsDirectory 
file1 = file1.resolvePath("AIR Test"); 
var file2 = air.File.documentsDirectory 
file2 = file2.resolvePath("AIR Test/bob/test.txt"); 
 
alert(file1.getRelativePath(file2)); // bob/test.txt

The second parameter of the getRelativePath() method, the useDotDot parameter, allows for .. syntax to be returned in results, to indicate parent directories:

var file1 = air.File.documentsDirectory; 
file1 = file1.resolvePath("AIR Test"); 
var file2 = air.File.documentsDirectory; 
file2 = file2.resolvePath("AIR Test/bob/test.txt"); 
var file3 = air.File.documentsDirectory; 
file3 = file3.resolvePath("AIR Test/susan/test.txt"); 
 
alert(file2.getRelativePath(file1, true)); // ../.. 
alert(file3.getRelativePath(file2, true)); // ../../bob/test.txt

Obtaining canonical versions of file names

File and path names are not case sensitive on Windows and Mac OS. In the following, two File objects point to the same file:

File.documentsDirectory.resolvePath("test.txt"); 
File.documentsDirectory.resolvePath("TeSt.TxT");

However, documents and directory names do include capitalization. For example, the following assumes that there is a folder named AIR Test in the documents directory, as in the following examples:

var file = air.File.documentsDirectory; 
file = file.resolvePath("AIR test"); 
trace(file.nativePath); // ... AIR test 
file.canonicalize(); 
alert(file.nativePath); // ... AIR Test

The canonicalize() method converts the nativePath object to use the correct capitalization for the file or directory name. On case sensitive file systems (such as Linux), when multiple files exists with names differing only in case, the canonicalize() method adjusts the path to match the first file found (in an order determined by the file system).

You can also use the canonicalize() method to convert short file names ("8.3" names) to long file names on Windows, as in the following examples:

var path = new air.File(); 
path.nativePath = "C:\\AIR~1"; 
path.canonicalize(); 
alert(path.nativePath); // C:\AIR Test

Working with packages and symbolic links

Various operating systems support package files and symbolic link files:

Packages—On Mac OS, directories can be designated as packages and show up in the Mac OS Finder as a single file rather than as a directory.

Symbolic links—Mac OS, Linux, and Windows Vista support symbolic links. Symbolic links allow a file to point to another file or directory on disk. Although similar, symbolic links are not the same as aliases. An alias is always reported as a file (rather than a directory), and reading or writing to an alias or shortcut never affects the original file or directory that it points to. On the other hand, a symbolic link behaves exactly like the file or directory it points to. It can be reported as a file or a directory, and reading or writing to a symbolic link affects the file or directory that it points to, not the symbolic link itself. Additionally, on Windows the isSymbolicLink property for a File object referencing a junction point (used in the NTFS file system) is set to true.

The File class includes the isPackage and isSymbolicLink properties for checking if a File object references a package or symbolic link.

The following code iterates through the user’s desktop directory, listing subdirectories that are not packages:

var desktopNodes = air.File.desktopDirectory.getDirectoryListing(); 
for (i = 0; i < desktopNodes.length; i++)  
{ 
    if (desktopNodes[i].isDirectory && !!desktopNodes[i].isPackage) 
    { 
        air.trace(desktopNodes[i].name); 
    } 
}

The following code iterates through the user’s desktop directory, listing files and directories that are not symbolic links:

var desktopNodes = air.File.desktopDirectory.getDirectoryListing(); 
for (i = 0; i < desktopNodes.length; i++)  
{ 
    if (!desktopNodes[i].isSymbolicLink) 
    { 
        air.trace(desktopNodes[i].name); 
    } 
}

The canonicalize() method changes the path of a symbolic link to point to the file or directory to which the link refers. The following code iterates through the user’s desktop directory, and reports the paths referenced by files that are symbolic links:

var desktopNodes = air.File.desktopDirectory.getDirectoryListing(); 
for (i = 0; i < desktopNodes.length; i++)  
{ 
    if (desktopNodes[i].isSymbolicLink) 
    { 
        var linkNode = desktopNodes[i]; 
        linkNode.canonicalize(); 
        air.trace(desktopNodes[i].name); 
    } 
}

Determining space available on a volume

The spaceAvailable property of a File object is the space available for use at the File location, in bytes. For example, the following code checks the space available in the application storage directory:

air.trace(air.File.applicationStorageDirectory.spaceAvailable); 

If the File object references a directory, the spaceAvailable property indicates the space in the directory that files can use. If the File object references a file, the spaceAvailable property indicates the space into which the file could grow. If the file location does not exist, the spaceAvailable property is set to 0. If the File object references a symbolic link, the spaceAvailable property is set to space available at the location the symbolic link points to.

Typically the space available for a directory or file is the same as the space available on the volume containing the directory or file. However, space available can take into account quotas and per-directory limits.

Adding a file or directory to a volume generally requires more space than the actual size of the file or the size of the contents of the directory. For example, the operating system may require more space to store index information. Or the disk sectors required may use additional space. Also, available space changes dynamically. So, you cannot expect to allocate all of the reported space for file storage. For information on writing to the file system, see Reading and writing files.