Working with File objects in AIR

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.

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

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

These properties have different values on different operating systems. For example, Mac and Windows each have a different native path to the user’s desktop directory. However, the File.desktopDirectory property points to an appropriate directory path on every platform. 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 = 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 do 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 .

The actual native paths for these directories vary based on the operating system and computer configuration. The paths shown in this table are typical examples. You should always use the appropriate static File class properties to refer to these directories so that your application works correctly on any platform. In an actual AIR application, the values for applicationID and filename shown in the table are taken from the application descriptor. If you specify a publisher ID in the application descriptor, then the publisher ID is appended to the application ID in these paths. The value for userName is the account name of the installing user.

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

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

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

var file1:File = File.documentsDirectory; 
file1 = file1.resolvePath("AIR Test"); 
trace(file1.nativePath); // C:\Documents and Settings\userName\My Documents\AIR Test 
var file2:File = File.documentsDirectory; 
file2 = file2.resolvePath(".."); 
trace(file2.nativePath); // C:\Documents and Settings\userName 
var file3:File = File.documentsDirectory; 
file3.nativePath += "/subdirectory"; 
trace(file3.nativePath); // C:\Documents and Settings\userName\My Documents\subdirectory 
var file4:File = new File(); 
file4.url = "file:///c:/AIR Test/test.txt"; 
trace(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.

In AIR, you can use any of the following URL schemes in defining the url property of a File object:

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

app:/images

app-storage:/settings/prefs.xml

Certain operating systems, most notably iOS and Mac OS X, provide users the ability to automatically back up application files to a remote storage. In addition, on iOS there are restrictions on whether files can be backed up and also where files of different purposes can be stored.

The following summarize how to comply with Apple’s guidelines for file backup and storage. For further information see the next sections.

• To specify that a file does not need to be backed up and (iOS only) can be deleted by the operating system if device storage space runs low, save the file in the cache directory ( File.cacheDirectory ). This is the preferred storage location on iOS and should be used for most files that can be regenerated or re-downloaded.

• To specify that a file does not need to be backed up, but should not be deleted by the operating system, save the file in one of the application library directories such as the application storage directory ( File.applicationStorageDirectory ) or the documents directory ( File.documentsDirectory ). Set the File object’s preventBackup property to true . This is required by Apple for content that can be regenerated or downloaded again, but which is required for proper functioning of your application during offline use.

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

var file1:File = File.documentsDirectory.resolvePath("AIR Test"); 
var file2:File = File.documentsDirectory 
file2 = file2.resolvePath("AIR Test/bob/test.txt"); 
 
trace(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:File = File.documentsDirectory; 
file1 = file1.resolvePath("AIR Test"); 
var file2:File = File.documentsDirectory; 
file2 = file2.resolvePath("AIR Test/bob/test.txt"); 
var file3:File = File.documentsDirectory; 
file3 = file3.resolvePath("AIR Test/susan/test.txt"); 
 
trace(file2.getRelativePath(file1, true)); // ../.. 
trace(file3.getRelativePath(file2, true)); // ../../bob/test.txt 

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:File = File.documentsDirectory.resolvePath("AIR test"); 
trace(file.nativePath); // ... AIR test 
file.canonicalize(); 
trace(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:File = new File(); 
path.nativePath = "C:\\AIR~1"; 
path.canonicalize(); 
trace(path.nativePath); // C:\AIR Test

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:Array = File.desktopDirectory.getDirectoryListing(); 
for (var i:uint = 0; i < desktopNodes.length; i++)  
{ 
    if (desktopNodes[i].isDirectory && !desktopNodes[i].isPackage) 
    { 
        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:Array = File.desktopDirectory.getDirectoryListing(); 
for (var i:uint = 0; i < desktopNodes.length; i++)  
{ 
    if (!desktopNodes[i].isSymbolicLink) 
    { 
        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:Array = File.desktopDirectory.getDirectoryListing(); 
for (var i:uint = 0; i < desktopNodes.length; i++)  
{ 
    if (desktopNodes[i].isSymbolicLink) 
    { 
        var linkNode:File = desktopNodes[i] as File; 
        linkNode.canonicalize(); 
        trace(linkNode.nativePath); 
    } 
} 

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:

trace(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 .

The StorageVolumeInfo.getStorageVolumes() method provides more detailed information on mounted storage volumes (see Working with storage volumes ).

In AIR 2, you can open a file using the application registered by the operating system to open it. For example, an AIR application can open a DOC file with the application registered to open it. Use the openWithDefaultApplication() method of a File object to open the file. For example, the following code opens a file named test.doc on the user’s desktop and opens it with the default application for DOC files:

var file:File = File.deskopDirectory; 
file = file.resolvePath("test.doc"); 
file.openWithDefaultApplication();

The following code lets the user navigate to an mp3 file and open it in the default application for playing mp3 files:

var file:File = File.documentsDirectory; 
var mp3Filter:FileFilter = new FileFilter("MP3 Files", "*.mp3"); 
file.browseForOpen("Open", [mp3Filter]); 
file.addEventListener(Event.SELECT, fileSelected); 
 
function fileSelected(e:Event):void 
{ 
    file.openWithDefaultApplication(); 
}

You cannot use the openWithDefaultApplication() method with files located in the application directory.

AIR prevents you from using the openWithDefaultApplication() method to open certain files. On Windows, AIR prevents you from opening files that have certain filetypes, such as EXE or BAT. On Mac OS and Linux, AIR prevents you from opening files that will launch in certain application. (These include Terminal and AppletLauncher on Mac OS; and csh, bash, or ruby on Linux.) Attempting to open one of these files using the openWithDefaultApplication() method results in an exception. For a complete list of prevented filetypes, see the language reference entry for the File.openWithDefaultApplication() method.