Accessing Files

File and Stream Guide: [ nsIScriptableIO | Accessing Files | Getting File Information | Reading from Files | Writing to Files | Moving, Copying and Deleting Files | Uploading and Downloading Files | Working With Directories ]

Other documentation on files and I/O not using the unavailable nsIScriptableIO APIs: Code snippets: File I/O, Open and Save Dialogs, Reading textual data, Writing textual data, List of file-related error codes.

Accessing Files

This section describes how to create a file reference.

Retrieving 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 nsIScriptableIO.getFile(). 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 nsIScriptableIO object is a global object always available within an application or extension which provides a number of useful functions for dealing with files. One such method it provides is nsIScriptableIO.getFile() which returns a new nsIFile object.

The first argument to nsIScriptableIO.getFile() 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 nsIScriptableIO.getFile() 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, nsIScriptableIO.getFile() 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 nsIFile.exists().

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 nsIFile.create() method which may be used to create an empty file, or you can open a writing stream and write to the file.

nsIScriptableIO.getFile() 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 nsIScriptableIO.getFile() 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.

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 nsIScriptableIO.getFile(), listed in the following table.

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.