WebAPI/FileHandleAPI

Goals

Provide the ability to write to a file, as well the locking mechanisms needed to allow writing safely.

Status

Basic functionality and support in IndexedDB is done, support in DeviceStorage remaining.

For details about the development, refer to

• bug 726593.

API

partial interface IDBDatabase
{
  IDBRequest mozCreateFileHandle(DOMString name, optional DOMString type);
};

interface IDBFileHandle
{
  readonly attribute IDBDatabase database;
};

interface FileHandle
{
  LockedFile open(optional /* "readonly" */ DOMString mode);

  FileRequest getFile();

  [TreatNonCallableAsNull] attribute Function? onabort;

  [TreatNonCallableAsNull] attribute Function? onerror;
};

interface LockedFile
{
  readonly attribute FileHandle fileHandle;

  readonly attribute DOMString mode;

  readonly attribute boolean active;

  attribute unsigned long long location;

  FileRequest getMetadata(optional FileMetadataParameters parameters);

  FileRequest readAsArrayBuffer(unsigned long long size);

  FileRequest readAsText(unsigned long long size);

  FileRequest write(DOMString or ArrayBuffer or Blob value);

  FileRequest append(DOMString or ArrayBuffer or Blob value);

  FileRequest truncate(optional unsigned long long size);

  FileRequest flush();

  void abort();

  [TreatNonCallableAsNull] attribute Function? oncomplete;

  [TreatNonCallableAsNull] attribute Function? onabort;

  [TreatNonCallableAsNull] attribute Function? onerror;
};

interface FileRequest : DOMRequest
{
  readonly attribute LockedFile lockedFile;

  [TreatNonCallableAsNull] attribute Function? onprogress;
};

dictionary FileMetadataParameters {
  boolean size = true;

  boolean lastModified = true;
};

Example

Here are few examples about how to use FileHandle API.

Create a file

var request = myDatabase.mozCreateFileHandle("test.bin", "binary");
request.onsuccess = function(event) {
  var myFile = event.target.result;
}

// The file is now only referenced from JS, so it will be automatically deleted if we don't store it in an objectore (useful for creating temporary files).

Links

• Source code: http://mxr.mozilla.org/mozilla-central/source/dom/file/
• Original proposal: http://lists.w3.org/Archives/Public/public-webapps/2012JanMar/0886.html