FileGuide:Accessing Files

From MDC

[edit] Accessing Files

This section describes how to create a file reference.

[edit] Retreiving a File

When working with files, usage is always done via a File object and not via string paths. This allows files to used in a portable way.

Because string paths are not used, references to files in a File object are made relative to some starting directory. A number of starting directories may be used, for instance, the user's home directory, the desktop, the system's temporary folder, and so forth. Once one of these starting directories is determined, a file reference may be created relative to this. A common case is to write a file in the directory that holds the user's preferences. This is a convenient location where an extension might save a file it needs to use. This directory is referred to as the user's profile directory.

To get a reference to a File object use the getFile method of the top-level IO object. The following example will retrieve a reference to a file named sample.txt located in the profile directory.

var file = IO.getFile("Profile", "sample.txt");

The IO object is a global object always available within an application or extension which provides a number of useful functions for dealing with files. See the IO reference for details about this object. One such method it provides is the getFile method which returns a new File object.

The first argument to the getFile method is the starting directory from which to locate a file. In the example above the word 'Profile' is used, which means start from within the user's profile directory. The actual location of this directory will vary by user and system, so this is a convenient means to refer to a common directory without having to locate it yourself. For a full list of starting directories, see Starting Directories below.

The second argument to the getFile method is the filename to locate, which, here, is 'sample.txt'. The result is that a reference is made to the 'sample.txt' file. It is important to note that this file does not have to exist for a file reference to be valid. That is, the getFile method will still return a valid file reference even if the file 'sample.txt' does not yet exist. You can check if the file exists by using the file's exists method.

var file = IO.getFile("Profile", "sample.txt");
if (file.exists())
  alert("The file is there!");
else
  alert("File not found!");

Here, the same file is retrieved and a further check is performed to see whether the file is present or not. The exists method returns true if the file is present and false if it is not.

If the file does not exist, you may wish to create it. The File object has a create method which may be used to create an empty file, or you can open a writing stream and write to the file.

The getFile method may only be used to retrieve files that are directly within one of the starting directories. To retrieve other files, you will need to use the getFile method to access a directory and iterate through subdirectories until you come to the file that you want. For more information about this, see Working with Directories.

[edit] Starting Directories

The examples above use the profile directory 'Profile' as the starting directory for locating a file. There are several other values which may be used as the first argument to the getFile method, listed in the following table.

Application	The directory of the executing application. For Firefox, for instance, this will be the directory where Firefox is installed. For a XULRunner application, this will be the directory where the application is installed.
Working	The current working directory. If the application was launched from a command line, for instance, this will be the directory where the application was launched from, which may be different from the 'Application' value.
Profile	The profile directory where preferences are stored.
Desktop	The desktop directory. Usually, you would use this as the default directory for saving files.
Components	The components directory where XPCOM components are installed.
Temp	The temporary directory. You would store any temporary or cache files here.

There are a number of other values that may be used, most of which are platform specific. For instance, on Windows, the value 'Strt' returns the Start directory, where applications which run when the system starts up are placed. On other platforms, using this value will just result in an error.