nsIScriptableIO

by 4 contributors:

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 ]

Important note: The pages from the File and Stream Guide use the IO object (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.

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.


Please add a summary to this article.
  Last changed in Gecko 1.9 (Firefox 3)

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

nsIFile getFile(in AString aLocation, in AString aFileName);
nsIFile getFileWithPath(in AString aFilePath);
nsISupports newInputStream(in nsIVariant aBase, in AString aMode, [optional] in AString aCharSet, [optional] in AString aReplaceChar, [optional] in unsigned long aBufferSize);
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);
nsIURI newURI(in nsIVariant aUri);

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.

Note: The filename may only be the name of a file. If you need to select a file in a subdirectory, you should get a reference to the directory, then use the file's append() method to navigate through the directory hierarchy to the file you really want. This properly allows platform-independent path construction.

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.

Note: You should avoid using this method, since file paths are platform-dependent and non-portable. Instead, you should use getFile() and construct the path from the base location manually.

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

Document Tags and Contributors

Contributors to this page: Sheppy, zalun, Nickolay, Enn
Last updated by: Sheppy,