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.

nsIScriptableIO provides a convenient API for creating files and streams, as well as for reading and writing data to them. For your convenience, this API is published through a global IO object.

For more details about how to use this object, see the File and Stream Guide.

Inherits from: nsISupports

A scriptable IO object can be used in an extension or chrome code by referring to the global IO object. For example:

IO.getFile("Profile", "cookies.txt");

From an XPCOM component, however, you will need to get a reference as with other components:

var scriptableIO = Components.classes["@mozilla.org/io/scriptable-io;1"]
                             .getService();
scriptableIO.getFile("Profile", "cookies.txt");

Method overview

Methods

getFile()

Retrieves a reference to a file or directory on disk. The file does not have to exist already; this method simply creates the file reference which may then be passed to the newInputStream() or newOutputStream() method to open the file for reading or writing.

Files are located by starting at a known directory, specified using a location key string. For example, if the location key is specified as "Desk" and the file name is specified as "Foo.txt", the file reference generated will refer to a file named "Foo.txt" on the user's desktop.

You may specify an empty filename string if you wish to get a reference to the directory itself.

 nsIFile getFile(
   in AString aLocation,
   in AString aFileName
 );

Parameters

aLocation

A location key identifying a known standard directory. The aFileName parameter is treated as being local to this directory.

aFileName

The relative path of the file to generate a reference for.

Return value

Returns an nsIFile object referencing the specified file location.

Exceptions thrown

NS_ERROR_INVALID_ARG

aLocation was null.

getFileWithPath()

Returns a file reference using an absolute file path to locate the file.

 nsIFile getFileWithPath(
   in AString aFilePath
 );

Parameters

aFilePath

The absolute pathname of the file to reference, or the value of a file's persistentDescriptor.

Return value

Returns an nsIFile object referencing the specified file location.

Exceptions thrown

NS_ERROR_INVALID_ARG

aFilePath was null.

newURI()

Creates a URI object that implements the nsIURI interface.

 nsIURI newURI(
   in nsIVariant aUri
 );

Parameters

aUri

The file for which to create a new nsIURI object. This parameter may be specified either as a URL string or as an nsIFile object.

Return value

Returns an nsIURI object corresponding to the specified string or file.

Exceptions thrown

NS_ERROR_INVALID_ARG

aUri was null.

newInputStream()

Retrieves a stream from which data can be read.

 nsISupports newInputStream(
   in nsIVariant aBase,
   in AString aMode,
   [optional] in AString aCharSet,
   [optional] in AString aReplaceChar,
   [optional] in unsigned long aBufferSize
 );

Parameters

aBase

The base object from which to read. This should be one of the following types:

• nsIFile: An object returned by getFile() or getFileWithPath(), or any object implementing the nsIFile interface.
• nsITransport: A transport object such as a socket.
• nsIInputStream: A stream returned by a previous call to this method, or any other object that implements nsIInputStream.
• string: A string from which to read data.

aMode

A space-delineated string of mode terms controlling the manner in which the stream is accessed. If none of these modes are desired, specify an empty string.

• text: Read Unicode-converted text. The default character set is UTF-8; to read text in another character set, set the aCharSet argument to the desired character set.
• buffered: A stream that uses a buffer to hold a block of the next piece of the data to be read. This mode is generally used as a wrapper for other streams. By default, the buffer size is 1024 bytes; however, the size may be changed by specifying the aBufferSize parameter. If the text mode is specified, a buffer is always used, regardless of whether or not it is specifically requested.
• block: When this mode is specified, reading from a transport such as a socket when no data is available will block until data is available before returning. If this mode isn't specified, an exception is thrown if no data is available.
• deleteonclose: The file is automatically deleted when the stream is closed. This can be useful for temporary files.
• closeoneof: The file is automatically closed when the end of the file is reached.
• reopenonrewind: Used in conjunction with the seek mode, the file will be reopened when a seek to the beginning of the file is done.
• multi: The resulting stream is one which is used to concatenate the input from multiple streams as if they were one long, continuous stream. The returned stream implements the nsIMultiplexInputStream interface. This mode may not be used in conjunction with the text or buffered modes.

aCharSet

The character set to use for interpreting the text data being read. Used only in conjunction with the text input mode. By default, streams are interpreted in UTF-8.

aReplaceChar

The character used to replace unknown characters in the input stream.

aBufferSize

The size of the buffer to use. By default, the buffer is 1024 bytes long.

Return value

Returns an nsIInputStream object to use for reading the stream. If the multi mode was specified, this object also implements the nsIMultiplexInputStream interface.

Exceptions thrown

NS_ERROR_INVALID_ARG

aBase was null.

newOutputStream()

Retrieves a stream to which data can be written.

 nsISupports newOutputStream(
   in nsIVariant aBase,
   in AString aMode,
   [optional] in AString aCharSet,
   [optional] in AString aReplaceChar,
   [optional] in unsigned long aBufferSize,
   [optional] in unsigned long aPermissions
 );

Parameters

aBase

The base object to which to write. This should be one of the following types:

• nsIFile: An object returned by getFile() or getFileWithPath(), or any object implementing the nsIFile interface.
• nsITransport: A transport object such as a socket.
• nsIOutputStream: A stream returned by a previous call to this method, or any other object that implements nsIOutputStream.

aMode

A space-delineated string of mode terms controlling the manner in which the stream is accessed. If none of these modes are desired, specify an empty string.

• text: Write Unicode-converted text. The default character set is UTF-8; to write text in another character set, set the aCharSet argument to the desired character set.
• buffered: A stream that buffers the data being written. This mode is generally used as a wrapper for other streams. By default, the buffer size is 1024 bytes; however, the size may be changed by specifying the aBufferSize parameter. If the text mode is specified, a buffer is always used, regardless of whether or not it is specifically requested.
• append: When writing to files, indicates to append to the file rather than overwrite the existing file. The write position will be set to the end of the file before each write. If used in conjuction with the create mode, an existing file may be opened for appending, or a new file created.
• block: When this mode is specified, writing to a transport such as a socket doesn't return until all data has been written. This may cause a delay if the socket's underlying buffer is full. If you don't specify this mode, an exception is thrown if the buffer is full.
• nocreate: If the file doesn't already exist, don't create a new file.
• notruncate: If the file already exists, overwrite the existing content instead of resetting the file size to 0 bytes.
• syncsave: Writing methods do not return until the data is properly saved.

aCharSet

The character set to use for interpreting the text data being written. Used only in conjunction with the text input mode. By default, streams are interpreted in UTF-8.

aReplaceChar

The character used to replace unknown characters in the output stream.

aBufferSize

The size of the buffer to use. By default, the buffer is 1024 bytes long.

aPermissions

The permissions to use on a newly created file, if applicable. Typically you will use an actual octal permissions value for this parameter. By default, the value 0664 is used.

Return value

Returns an nsIOutputStream object to use for writing the stream.

Exceptions thrown

NS_ERROR_INVALID_ARG

aBase was null.

Example: Writing to a file

var json = "{ name: 'bob', age: 37}";
var file = IO.getFile("Profile", null);
file.append("myobject.json");
if (!file.exists())
  file.create(Ci.nsIFile.NORMAL_FILE_TYPE, 0600);
var stream = IO.newOutputStream(file, "text write create truncate");
stream.writeString(json);
stream.close();

Example: Reading from a file

var file = IO.getFile("Profile", null);
file.append("localstore.json");
if (file.exists()) {
  var stream = IO.newInputStream(file, "text");
  var json = stream.readLine();
  stream.close();
}

See also

nsIFile, nsIInputStream, nsIOutputStream