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 ]
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.
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.
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.
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 annsIFile
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 bygetFile()
orgetFileWithPath()
, or any object implementing thensIFile
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 implementsnsIInputStream
.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 theaCharSet
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 theaBufferSize
parameter. If thetext
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 thensIMultiplexInputStream
interface. This mode may not be used in conjunction with thetext
orbuffered
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 bygetFile()
orgetFileWithPath()
, or any object implementing thensIFile
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 implementsnsIOutputStream
.
-
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 theaCharSet
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 theaBufferSize
parameter. If thetext
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(); }