WebAPI/FileHandleAPI
From MozillaWiki
< WebAPI
Contents
- 1 Goals
- 2 Status
- 3 API
- 3.1 Example
- 3.1.1 Create a file
- 3.1.2 Store the file in an objectstore
- 3.1.3 A simple write operation
- 3.1.4 A simple read operation
- 3.1.5 Write a 32 bit unsigned integer
- 3.1.6 Atomic increment of a counter somewhere in the file
- 3.1.7 Update the progress bar during a read or write
- 3.1.8 Store a snapshot of the file
- 3.1 Example
- 4 ToDo
- 5 Articles
- 6 Links
Goals
Provide the ability to write to a file, as well the locking mechanisms needed to allow writing safely. FileHandle is also known as low-level file-CRUD support.
Status
Basic functionality and support in IndexedDB is done, support in DeviceStorage remaining.
For details about the development, refer to
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); DOMRequest getFile(); [TreatNonCallableAsNull] attribute Function? onabort; [TreatNonCallableAsNull] attribute Function? onerror; };
interface LockedFile { readonly attribute FileHandle fileHandle; readonly attribute DOMString mode; readonly attribute boolean active; attribute any? location; FileRequest getMetadata(optional FileMetadataParameters parameters); FileRequest readAsArrayBuffer(unsigned long long size); FileRequest readAsText(unsigned long long size, optional DOMString encoding); 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, it will be automatically deleted after a // GC, if we don't store it in an objectstore (useful for creating temporary files).
Store the file in an objectstore
var transaction = myDatabase.transaction(["test"], "readwrite"); var objectStore = transaction.objectStore("test"); var request = objectStore.add(myFile, myKey); request.onsuccess = function(event) { // The file is now referenced from database too. } // If we store the same file using a different key or even in a different objectstore, // it won't be stored as a separate file, the operation will only add another database // reference.
A simple write operation
var lockedFile = myFile.open("readwrite"); var request = lockedFile.write("foo"); request.onsuccess = function(event) { // The string "foo" has been written. }
A simple read operation
var lockedFile = myFile.open(); var request = lockedFile.readAsText(3); request.onsuccess = function(event) { var text = event.target.result; // 3 characters have been read. }
Write a 32 bit unsigned integer
var buffer = new ArrayBuffer(4); var view = new Uint32Array(buffer); view[0] = 1; var lockedFile = myFile.open("readwrite"); var request = lockedFile.write(buffer); request.onsuccess = function(event) { // The integer has been written. }
Atomic increment of a counter somewhere in the file
var lockedFile = myFile.open("readwrite"); lockedFile.location = 123; lockedFile.readAsArrayBuffer(4).onsuccess = function(event) { var buffer = event.target.result; var view = new Uint32Array(buffer); view[0] = view[0] + 1; lockedFile.location = 123; lockedFile.write(buffer); }
Update the progress bar during a read or write
request.onprogress = function(event) { var progress = document.getElementById("progress"); progress.value = event.loaded; progress.max = event.total; }
Store a snapshot of the file
myFile.getFile().onsuccess = function(event) { var file = event.target.result; var transcation = myDatabase.transaction(["snapshots"], "readwrite"); var objectStore = transaction.objectStore("snapshots"); objectStore.add(file, snapshotKey).onsuccess = function(event) { // A new readonly copy of the file has been created. } } // myFile.getFile() can be also used to pass file objects to a FileReader, XHR, etc.
ToDo
- Multi-process support in IndexedDB (a requirement for use in B2G)
- Synchronous API (for use in workers)
- Fast methods or explicit close() method to avoid multiple round-trips to the main thread (to improve performance of multiple small reads/writes requested in a row)
Articles
Articles mentioning / discussing the FileHandle API:
- public-webapps: Colliding FileWriters
- Velocity 2012: Antisocial APIs
- Mozilla Hacks: Why no FileSystem API in Firefox?