mozilla

Revision 104067 of File I/O

  • Revision slug: File_I//O
  • Revision title: File I/O
  • Revision id: 104067
  • Created:
  • Creator: Oeekker
  • Is current revision? No
  • Comment page created, 558 words added

Revision Content

This article describes local file input/output in chrome JavaScript.

You access the file system using Mozilla XPCOM components. A list of resources and interfaces for local I/O is available for both Files and Streams at XUL Planet.

Available libraries

There are a few JavaScript wrappers for I/O XPCOM components. See JSLib and io.js (original by MonkeeSage). The io.js module is much smaller and very easy to use (simple examples are included in the module).

Creating a file object ("opening" files)

var file = Components.classes["@mozilla.org/file/local;1"]
                     .createInstance(Components.interfaces.nsILocalFile);
file.initWithPath("/home");

NOTE: the path passed to initWithPath() should be in "native" form (e.g. "C:\\Windows"). If you need to use file:// URIs as initializers, see discussion of nsIIOService below.

NOTE: initWithPath() / initWithFile() functions don't throw an exception if the specified file does not exist. An exception is thrown when methods that require the file existence are called, e.g. isDirectory(), moveTo(), etc.

Getting special files

// get profile directory
var file = Components.classes["@mozilla.org/file/directory_service;1"]
                     .getService(Components.interfaces.nsIProperties)
                     .get("ProfD", Components.interfaces.nsIFile);

// NOTE: "file" is an object that implements nsIFile. If you want the
// file system path, use file.path

Here are some strings you can put in place of "ProfD" (stolen from MonkeeSage's I/O module comments):

String Meaning
ProfD profile directory
DefProfRt user (e.g., /root/.mozilla)
UChrm  %profile%/chrome
DefRt  %installation%/defaults
PrfDef  %installation%/defaults/pref
ProfDefNoLoc  %installation%/defaults/profile
APlugns  %installation%/plugins
AChrom  %installation%/chrome
ComsD  %installation%/components
CurProcD installation (usually)
Home OS root (e.g., /root)
TmpD OS tmp (e.g., /tmp)
ProfLD Local Settings on windows; where the network cache and fastload files are stored
resource:app application directory in a XULRunner app
Desk Desktop directory (e.g. ~/Desktop on Linux, C:\Documents and Settings\username\Desktop on Windows)
Progs User start menu programs directory (e.g., C:\Documents and Settings\username\Start Menu\Programs)

Look in the Source for other strings available: {{ Source("xpcom/io/nsAppDirectoryServiceDefs.h") }}, {{ Source("xpcom/io/nsDirectoryServiceDefs.h") }}.

Getting your extension's folder

NOTE: This will only work in Firefox/Thunderbird 1.5+, not 1.0.

Via nsIExtensionManager
// the extension's id from install.rdf
var MY_ID = "myextension@my.name";
var em = Components.classes["@mozilla.org/extensions/manager;1"].
         getService(Components.interfaces.nsIExtensionManager);
// the path may use forward slash ("/") as the delimiter
var file = em.getInstallLocation(MY_ID).getItemFile(MY_ID, "install.rdf");
// returns nsIFile for the extension's install.rdf
From an XPCOM component

To get the directory that an extension is installed in, use an XPCOM component written in JavaScript. The special __LOCATION__ builtin will return an nsIFile of the component file:

extensiondir/component/GetExtensionDirectory.js:

var componentFile = __LOCATION__;
var componentsDir = componentFile.parent;
var extensionDir = componentsDir.parent;

Creating Folders

To create a folder, use nsIFile.create():

var file = Components.classes["@mozilla.org/file/directory_service;1"]
                     .getService(Components.interfaces.nsIProperties)
                     .get("ProfD", Components.interfaces.nsIFile);
file.append("DIR");
if( !file.exists() || !file.isDirectory() ) {   // if it doesn't exist, create
   file.create(Components.interfaces.nsIFile.DIRECTORY_TYPE, 0777);
}

The above example creates a folder called "DIR" in the Profile folder. For more information, refer to the nsIFile.create reference.

Creating temporary files

To create a temporary file, use nsIFile.createUnique():

var file = Components.classes["@mozilla.org/file/directory_service;1"]
                     .getService(Components.interfaces.nsIProperties)

Revision Source

<p>This article describes local file input/output in chrome JavaScript.</p>
<p>You access the file system using Mozilla <a href="/en/XPCOM" title="en/XPCOM">XPCOM</a> components. A list of resources and interfaces for local I/O is available for both <a class="external" href="http://www.xulplanet.com/references/xpcomref/group_Files.html">Files</a> and <a class="external" href="http://www.xulplanet.com/references/xpcomref/group_Streams.html">Streams</a> at <a class="external" href="http://www.xulplanet.com/">XUL Planet</a>.</p>
<h3 name="Available_libraries">Available libraries</h3>
<p>There are a few JavaScript wrappers for I/O XPCOM components. See <a class="external" href="http://jslib.mozdev.org/">JSLib</a> and <a href="/en/io.js" title="en/io.js">io.js</a> (original by <a class="external" href="http://gratisdei.com/io.js">MonkeeSage</a>). The io.js module is much smaller and very easy to use (simple examples are included in the module).</p>
<h3 name="Creating_a_file_object_.28.22opening.22_files.29">Creating a file object ("opening" files)</h3>
<pre>var file = Components.classes["@mozilla.org/file/local;1"]
                     .createInstance(Components.interfaces.nsILocalFile);
file.initWithPath("/home");
</pre>
<div class="note">
<p><strong>NOTE</strong>: the path passed to <code>initWithPath()</code> should be in "native" form (e.g. <code>"C:\\Windows"</code>). If you need to use <a class=" external" href="file://" rel="freelink">file://</a> URIs as initializers, see discussion of <a href="/en/nsIIOService" title="en/nsIIOService">nsIIOService</a> below.</p>
</div>
<div class="note">
<p><strong>NOTE</strong>: <code>initWithPath()</code> / <code>initWithFile()</code> functions don't throw an exception if the specified file does not exist. An exception is thrown when methods that require the file existence are called, e.g. <code>isDirectory()</code>, <code>moveTo()</code>, etc.</p>
</div>
<h3 name="Getting_special_files">Getting special files</h3>
<pre>// get profile directory
var file = Components.classes["@mozilla.org/file/directory_service;1"]
                     .getService(Components.interfaces.nsIProperties)
                     .get("ProfD", Components.interfaces.nsIFile);

// NOTE: "file" is an object that implements nsIFile. If you want the
// file system path, use file.path
</pre>
<p>Here are some strings you can put in place of <code>"ProfD"</code> (stolen from MonkeeSage's I/O module comments):</p>
<table class="standard-table"> <tbody> <tr> <th>String</th> <th>Meaning</th> </tr> <tr> <td>ProfD</td> <td>profile directory</td> </tr> <tr> <td>DefProfRt</td> <td>user (e.g., /root/.mozilla)</td> </tr> <tr> <td>UChrm</td> <td> %profile%/chrome</td> </tr> <tr> <td>DefRt</td> <td> %installation%/defaults</td> </tr> <tr> <td>PrfDef</td> <td> %installation%/defaults/pref</td> </tr> <tr> <td>ProfDefNoLoc</td> <td> %installation%/defaults/profile</td> </tr> <tr> <td>APlugns</td> <td> %installation%/plugins</td> </tr> <tr> <td>AChrom</td> <td> %installation%/chrome</td> </tr> <tr> <td>ComsD</td> <td> %installation%/components</td> </tr> <tr> <td>CurProcD</td> <td>installation (usually)</td> </tr> <tr> <td>Home</td> <td>OS root (e.g., /root)</td> </tr> <tr> <td>TmpD</td> <td>OS tmp (e.g., /tmp)</td> </tr> <tr> <td>ProfLD</td> <td>Local Settings on windows; where the network cache and fastload files are stored</td> </tr> <tr> <td>resource:app</td> <td>application directory in a XULRunner app</td> </tr> <tr> <td>Desk</td> <td>Desktop directory (e.g. ~/Desktop on Linux, C:\Documents and Settings\username\Desktop on Windows)</td> </tr> <tr> <td>Progs</td> <td>User start menu programs directory (e.g., C:\Documents and Settings\username\Start Menu\Programs)</td> </tr> </tbody>
</table>
<p>Look in the Source for other strings available: {{ Source("xpcom/io/nsAppDirectoryServiceDefs.h") }}, {{ Source("xpcom/io/nsDirectoryServiceDefs.h") }}.</p>
<h4 name="Getting_your_extension.27s_folder">Getting your extension's folder</h4>
<div class="note">
<p><strong>NOTE</strong>: This will only work in Firefox/Thunderbird 1.5+, not 1.0.</p>
</div>
<h5 name="Via_nsIExtensionManager">Via <code>nsIExtensionManager</code></h5>
<pre class="eval">// the extension's id from <a href="/en/Install_Manifests" title="en/Install_Manifests">install.rdf</a>
var MY_ID = "<a class=" link-mailto" href="mailto:myextension@my.name" rel="freelink">myextension@my.name</a>";
var em = Components.classes["@mozilla.org/extensions/manager;1"].
         getService(Components.interfaces.nsIExtensionManager);
// the path may use forward slash ("/") as the delimiter
var file = em.getInstallLocation(MY_ID).getItemFile(MY_ID, "install.rdf");
// returns nsIFile for the extension's install.rdf
</pre>
<h5 name="From_an_XPCOM_component">From an XPCOM component</h5>
<p>To get the directory that an extension is installed in, use an XPCOM component written in JavaScript. The special <code>__LOCATION__</code> builtin will return an nsIFile of the component file:</p>
<p>extensiondir/component/GetExtensionDirectory.js:</p>
<pre class="eval">var componentFile = __LOCATION__;
var componentsDir = componentFile.parent;
var extensionDir = componentsDir.parent;
</pre>
<h3 name="Creating_Folders">Creating Folders</h3>
<p>To create a folder, use <code>nsIFile.create()</code>:</p>
<pre class="eval">var file = Components.classes["@mozilla.org/file/directory_service;1"]
                     .getService(Components.interfaces.nsIProperties)
                     .get("ProfD", Components.interfaces.nsIFile);
file.append(<em>"DIR"</em>);
if( !file.exists() || !file.isDirectory() ) {   // if it doesn't exist, create
   file.create(Components.interfaces.nsIFile.DIRECTORY_TYPE, 0777);
}
</pre>
<p>The above example creates a folder called <em>"DIR"</em> in the <a class="external" href="http://www.mozilla.org/support/firefox/profile">Profile folder</a>. For more information, refer to the <a href="/en/nsIFile/create" title="en/nsIFile/create"><code>nsIFile.create</code> reference</a>.</p>
<h3 name="Creating_temporary_files">Creating temporary files</h3>
<p>To create a temporary file, use <code>nsIFile.createUnique()</code>:</p>
<pre>var file = Components.classes["@mozilla.org/file/directory_service;1"]
                     .getService(Components.interfaces.nsIProperties)</pre>
Revert to this revision