WebAPI/FileHandleAPI: Difference between revisions
< WebAPI
Jump to navigation
Jump to search
(→API) |
|||
Line 47: | Line 47: | ||
FileRequest readAsArrayBuffer(unsigned long long size); | FileRequest readAsArrayBuffer(unsigned long long size); | ||
FileRequest readAsText(unsigned long long size); | FileRequest readAsText(unsigned long long size, optional DOMString encoding); | ||
FileRequest write(DOMString or ArrayBuffer or Blob value); | FileRequest write(DOMString or ArrayBuffer or Blob value); |
Revision as of 05:10, 16 June 2012
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
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, 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. }
Writing 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(value.toUpperCase()); }
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