FileSystemDirectoryReader.readEntries()

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

This API has no official W3C or WHATWG specification.

Browser compatibility

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

See also

• File and Directory Entries API
• Introduction to the File System API
• FileSystemDirectoryEntry
• FileSystem