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 ]
nsIScriptableIO), which was not available in any released version of the platform (pending some fixes). There are alternative XPCOM APIs you can use, your help in updating this pages to use the supported API is very much welcome!
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.
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");
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
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
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.
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.
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.
|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.