FileSystemDirectoryReader.readEntries()

This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for usage in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the specification changes.

Non-standard
This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.

The FileSystemDirectoryReader interface's readEntries() method retrieves the directory entries within the directory being read. Each time the method is called, an array containing some number of the directory's entries is passed to the success callback. When the end of the directory is reached, the success callback receives an empty array.

The objects in the array are all based upon FileSystemEntry. Generally, they are either FileSystemFileEntry objects, which represent standard files, or FileSystemDirectoryEntry objects, which represent directories.

Syntax

readEntries(successCallback[, errorCallback]);

Parameters

successCallback
A function which is called with the next set of previously-unreported entries in the directory being read. The function receives a single input parameter: an array of file system entry objects, each based on FileSystemEntry. Generally, they are either FileSystemFileEntry objects, which represent standard files, or FileSystemDirectoryEntry objects, which represent directories.
errorCallback Optional
A callback function which is called if an error occurs while reading from the directory. It receives one input parameter: a FileError object describing the error which occurred.

Return value

undefined.

Example

In this example, we list all the entries in a directory into a web page. To list all the entries, you need to do the following:

  1. Call FileSystemDirectoryEntry.createReader() to create a new FileSystemDirectoryReader.
  2. Call readEntries().
  3. Continue calling readEntries() until an empty array is returned. You have to do this because the API might not return all entries in a single call.
// Taking care of the browser-specific prefixes.
window.requestFileSystem  = window.requestFileSystem || window.webkitRequestFileSystem; 
window.directoryEntry = window.directoryEntry || window.webkitDirectoryEntry;

...

function toArray(list) {
  return Array.prototype.slice.call(list || [], 0);
}

function listResults(entries) {
  // To improve performance, we create document fragments, 
  // which are appended to the DOM only once. 
  // So only one browser reflow occurs.
  var fragment = document.createDocumentFragment();

  entries.forEach(function(entry, i) {
    var img = entry.isDirectory ? 'img src=<"folder-icon.gif">' :
                                  'img src=<"file-icon.gif">';
                                  
                     
    var li = document.createElement('li');
    li.innerHTML = [img, '', entry.name, ''].join('');
    fragment.appendChild(li);
  });

  document.querySelector('#filelist').appendChild(fragment);
}

function onInitFs(fs) {

  var dirReader = fs.root.createReader();
  var entries = [];

  // Keep calling readEntries() until no more results are returned.
  var readEntries = function() {
     dirReader.readEntries (function(results) {
      if (!results.length) {
        listResults(entries.sort());
      } else {
        entries = entries.concat(toArray(results));
        readEntries();
      }
    }, errorHandler);
  };

// Start reading the directory.

  readEntries(); 

}

// Creating a filesystem
window.requestFileSystem(window.TEMPORARY, 1024*1024, onInitFs, errorHandler);

Specifications

Specification Status Comment
File and Directory Entries API Editor's Draft Draft of proposed API

This API has no official W3C or WHATWG specification.

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support 13 webkit 50 (50)[1] No support No support No support
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support No support (Yes) webkit 50.0 (50)[1] No support No support No support

[1] In Firefox, the error callback's parameter is a DOMError rather than a FileError object.

See also

License

© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-us/docs/web/api/filesystemdirectoryreader/readentries