Revision 1121301 of FileSystemDirectoryEntry

<p>{{APIRef("File System API")}}{{Non-standard_header}}</p>

<p>The <strong><code>FileSystemDirectoryEntry</code></strong> interface of the <a href="/en-US/docs/Web/API/File_and_Directory_Entries_API">File and Directory Entries API</a> represents a directory in a file system. It provides methods which make it possible to access and manipulate the files in a directory, as well as to access the entries within the directory.</p>

<div class="note">
<p>Because this is a non-standard API, whose specification is not currently on a standards track, it's important to keep in mind that not all browsers implement it, and those that do may implement only small portions of it. Check the {{anch("Browser compatibility")}} section for details.</p>
</div>

<h2 id="basic_concepts" name="basic_concepts">Basic concepts</h2>

<p>You can create a new directory by calling {{domxref("FileSystemDirectoryEntry.getDirectory", "getDirectory()")}}. If you want to create subdirectories, create each child directory in sequence. If you try creating a directory using a full path that includes parent directories that do not exist yet, an error is returned. So create the hierarchy by recursively adding a new path after creating the parent directory.</p>

<h3 id="example" name="example">Example</h3>

<p>In the following code snippet, we create a directory called "Documents."</p>

<pre class="brush: js">
// Taking care of the browser-specific prefixes.
window.requestFileSystem&nbsp;&nbsp;=&nbsp;window.requestFileSystem&nbsp;||&nbsp;window.webkitRequestFileSystem;&nbsp;
window.directoryEntry = window.directoryEntry || window.webkitDirectoryEntry;

...

function onFs(fs){
  fs.root.getDirectory('Documents', {create:true}, function(directoryEntry){
    //directoryEntry.isFile === false
    //directoryEntry.isDirectory === true
    //directoryEntry.name === 'Documents'
    //directoryEntry.fullPath === '/Documents'
    
    }, onError);

  }

// Opening a file system with temporary storage
window.requestFileSystem(TEMPORARY, 1024*1024 /*1MB*/, onFS, onError);</pre>

<h2 id="Method_overview">Methods</h2>

<dl>
 <dt>{{domxref("FileSystemDirectoryEntry.createReader", "createReader()")}}</dt>
 <dd>Creates a {{domxref("FileSystemDirectoryReader")}} object which can be used to read the entries in this directory.</dd>
 <dt>{{domxref("FileSystemDirectoryEntry.getDirectory", "getDirectory()")}}</dt>
 <dd>Returns a {{domxref("FileSystemDirectoryEntry")}} object representing a directory located at a given path, relative to the directory on which the method is called.</dd>
 <dt>{{domxref("FileSystemDirectoryEntry.getFile", "getFile()")}}</dt>
 <dd>Returns a {{domxref("FileSystemFileEntry")}} object representing a file located within the directory's hierarchy, given a path relative to the directory on which the method is called.</dd>
 <dt>{{domxref("FileSystemDirectoryEntry.removeRecursively", "removeRecursively()")}</dt>
 <dd>Deletes a directory and all of its contents, including the contents of subdirectories.</dd>
</dl>

<table class="standard-table">
 <tbody>
  <tr>
   <td><code>FileSystemDirectoryReader <a href="#createReader" title="#createReader">createReader</a> ();</code></td>
  </tr>
  <tr>
   <td><code>void <a href="#getFile" title="#getFile">getFile</a> (in DOMString <em>path</em>, in optional Flags <em>options</em>, in optional <a class="external" href="https://www.w3.org/TR/file-system-api/#idl-def-EntryCallback">EntryCallback</a> <em>successCallback</em>, in optional <a class="external" href="https://www.w3.org/TR/file-system-api/#idl-def-ErrorCallback">ErrorCallback</a> <em>errorCallback</em>);</code></td>
  </tr>
  <tr>
   <td><code>void <a href="#getDirectory" title="#getDirectory">getDirectory</a> (in DOMString path, in optional Flags <em>options</em>, in optional EntryCallback <em>successCallback</em>, in optional ErrorCallback <em>errorCallback</em>);</code></td>
  </tr>
  <tr>
   <td><code>void <a href="#removeRecursively" title="#removeRecursively">removeRecursively</a> (in Void Callback <em>successCallback</em>, in optional ErrorCallback <em>errorCallback</em>); </code></td>
  </tr>
 </tbody>
</table>

<h3 id="createReader" name="createReader">createReader()</h3>

<p>Creates a new {{domxref("FileSystemDirectoryReader")}} to read entries from this directory.&nbsp;</p>

<pre>
FileSystemDirectoryReader createReader ();</pre>

<h5 id="Returns">Returns</h5>

<dl>
 <dt><code>FileSystemDirectoryReader</code></dt>
</dl>

<h3 id="getFile" name="getFile">getFile()</h3>

<p>Depending on how you've set the <code>options</code> parameter, this method either creates a file or looks up an existing file.</p>

<pre>
void getFile (
  in DOMString <em>path</em>, in optional Flags <em>options</em>, in optional EntryCallback <em>successCallback</em>, in optional ErrorCallback <em>errorCallback</em>
);</pre>

<h5 id="Parameter">Parameter</h5>

<dl>
 <dt>path</dt>
 <dd>Either an absolute path or a relative path from the directory to the file to be looked up or created. You cannot create a file whose immediate parent does not exist. Create the parent directory first.</dd>
 <dt>options</dt>
 <dd>An object literal describing the behavior of the method. If the file does not exist, it is created.</dd>
</dl>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col" width="249">Object literal</th>
   <th scope="col" width="354">Condition</th>
   <th scope="col" width="872">Result</th>
  </tr>
  <tr>
   <td><code>create: true</code><br />
    <code>exclusive: true</code></td>
   <td>Path already exists</td>
   <td>An error is thrown.</td>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td><code>create: true</code><br />
    <code>exclusive: false</code></td>
   <td>Path doesn't exist, and no other error occurs</td>
   <td>A file is created. If a file already exists, no error is thrown.</td>
  </tr>
  <tr>
   <td><code>create: false</code><br />
    (<code>exclusive</code> is ignored)</td>
   <td>Path exists</td>
   <td>The file is returned.</td>
  </tr>
  <tr>
   <td><code>create: false</code><br />
    (<code>exclusive</code> is ignored)</td>
   <td>Path doesn't exist</td>
   <td>An error is thrown.</td>
  </tr>
  <tr>
   <td><code>create: false</code><br />
    (<code>exclusive</code> is ignored)</td>
   <td>Path exists, but is a directory</td>
   <td>An error is thrown.</td>
  </tr>
 </tbody>
</table>

<dl>
 <dt>successCallback</dt>
 <dd>A callback that is called to return the file selected or created.</dd>
 <dt>errorCallback</dt>
 <dd>A callback that is called when errors occur.</dd>
</dl>

<h5 id="Returns_2">Returns</h5>

<dl>
 <dt><code>void</code></dt>
</dl>

<h3 id="getDirectory" name="getDirectory">getDirectory()</h3>

<p>Creates or looks up a directory. The methods are similar to <code>getFile()</code> with FileSystemDirectoryEntry being passed in the success callback.</p>

<pre>
void getDirectory (
  in DOMString <em>path</em>, in optional Flags <em>options</em>, in optional EntryCallback <em>successCallback</em>, in optional ErrorCallback <em>errorCallback</em>
);</pre>

<h5 id="Parameter_2">Parameter</h5>

<dl>
 <dt>path</dt>
 <dd>Either an absolute path or a relative path from the <code>FileSystemDirectoryEntry</code> to the directory to be looked up or created. It is an error to attempt to create a file whose immediate parent does not yet exist.</dd>
 <dt>options</dt>
 <dd>An object literal describing the behavior of the method if the directory does not exist.</dd>
</dl>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col" width="249">Object literal</th>
   <th scope="col" width="354">Condition</th>
   <th scope="col" width="872">Result</th>
  </tr>
  <tr>
   <td><code>create: true</code><br />
    <code>exclusive: true</code></td>
   <td>Path already exists</td>
   <td>An error is thrown.</td>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td><code>create: true</code><br />
    <code>exclusive: false</code></td>
   <td>Path doesn't exist, and no other error occurs</td>
   <td>A directory is created and return a corresponding <code>FileSystemDirectoryEntry</code>. If a directory already exists, no error is thrown.</td>
  </tr>
  <tr>
   <td><code>create: false</code><br />
    (<code>exclusive</code> is ignored)</td>
   <td>Path exists</td>
   <td>The directory corresponding to the path is returned.</td>
  </tr>
  <tr>
   <td><code>create: false</code><br />
    (<code>exclusive</code> is ignored)</td>
   <td>Path doesn't exist</td>
   <td>An error is thrown.</td>
  </tr>
  <tr>
   <td><code>create: false</code><br />
    (<code>exclusive</code> is ignored)</td>
   <td>Path exists, but is a file</td>
   <td>An error is thrown.</td>
  </tr>
 </tbody>
</table>

<dl>
 <dt>successCallback</dt>
 <dd>A callback that is called to return the directory selected or created.</dd>
 <dt>errorCallback</dt>
 <dd>A callback that is called when errors happen.</dd>
</dl>

<h5 id="Returns_3">Returns</h5>

<p><code>void</code></p>

<h3 id="removeRecursively" name="removeRecursively">removeRecursively()</h3>

<p>Deletes a directory and all of its contents. You cannot delete the root directory of a file system.</p>

<p>If you delete a directory containing a file that cannot be removed or if an error occurs while the deletion is in progress, some of the contents might not be deleted. Catch these cases with error callbacks and retry the deletion.</p>

<pre>
DOMString removeRecursively (
  <em>in </em>VoidCallback successCallback, optional ErrorCallback errorCallback
);</pre>

<h5 id="Parameter_3">Parameter</h5>

<dl>
 <dt>successCallback</dt>
 <dd>A callback that is called when the deletion succeeds.</dd>
 <dt>errorCallback</dt>
 <dd>A callback that is called when errors happen.</dd>
</dl>

<h5 id="Returns_4">Returns</h5>

<dl>
 <dt><code>void</code></dt>
</dl>

<h2 id="Specifications">Specifications</h2>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>{{SpecName('File System API')}}</td>
   <td>{{Spec2('File System API')}}</td>
   <td>Draft of proposed API</td>
  </tr>
 </tbody>
</table>

<p>This API has no official W3C or WHATWG specification.</p>

<h2 id="Browser_compatibility" name="Browser_compatibility">Browser compatibility</h2>

<p>{{ CompatibilityTable }}</p>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari (WebKit)</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>13 {{ property_prefix("webkit") }}</td>
   <td>{{ CompatGeckoDesktop(50) }}<sup>[2]</sup></td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatNo }}</td>
  </tr>
  <tr>
   <td><code>removeRecursively()</code></td>
   <td>13 {{ property_prefix("webkit") }}</td>
   <td>{{ CompatNo }}<sup>[1]</sup></td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatNo }}</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Android</th>
   <th>Chrome for Android</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>IE&nbsp;Phone</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{ CompatNo }}</td>
   <td>0.16 {{ property_prefix("webkit") }}</td>
   <td>{{ CompatGeckoDesktop(50) }}<sup>[2]</sup></td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatNo }}</td>
  </tr>
  <tr>
   <td><code>removeRecursively()</code></td>
   <td>{{ CompatNo }}</td>
   <td>0.16 {{ property_prefix("webkit") }}</td>
   <td>{{ CompatNo }}<sup>[1]</sup></td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatNo }}</td>
  </tr>
 </tbody>
</table>
</div>

<p>[1] While the {{domxref("FileSystemDirectoryEntry.removeRecursively", "removeRecursively()")}} method exists in Firefox 50, all it does is immediately call the error callback with <code>NS_ERROR_DOM_SECURITY_ERR</code>.</p>

<p>[2] In Firefox, the error callback's parameter is a {{domxref("DOMError")}} rather than a {{domxref("FileError")}} object.</p>

<h2 id="See_also">See also</h2>

<ul>
 <li><a href="/en-US/docs/Web/API/File_and_Directory_Entries_API">File and Directory Entries API</a></li>
 <li><a href="/en-US/docs/Web/API/File_and_Directory_Entries_API/Introduction">Introduction to the File System API</a></li>
 <li>{{domxref("FileSystemDirectoryReader")}}</li>
 <li>{{domxref("FileSystemEntry")}}</li>
 <li>{{domxref("FileSystemFileEntry")}}</li>
</ul>