WebAPI/ProposedDeviceStorageAPIWithNotifications: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
(Created page with "This page contains a draft of the proposed modification to the DeviceStorage API to include onchanged notifications. == API == partial interface Navigator { /** * type ...")
 
No edit summary
Line 34: Line 34:
   // Deletes a file
   // Deletes a file
   DOMRequest delete(DOMString name);
   DOMRequest delete(DOMString name);
 
   // Watches a file for updates: type is intended to be a list (probably a bitfield) of creation, deletion, and modification.
   // Watches a file for updates: type is intended to be a list (probably a bitfield) of creation, deletion, and modification.
   // handler takes the file's name and an event type.
   // handler takes the file's name and an event type.
Line 41: Line 41:
   DOMRequest watchFileChange(DOMString name, Function handler, Function onError, UpdateType type);
   DOMRequest watchFileChange(DOMString name, Function handler, Function onError, UpdateType type);
   
   
   // Watches all files for updates: type is intended to be a list (probably a bitfield) of creation, deletion, and modification.
   // Watches all files for updates: type is intended to be a list (probably a bitfield) of creation, deletion, and modification.
   // handler takes the changed file's name and and an event type
   // handler takes the changed file's name and and an event type
Line 47: Line 46:
   // returns, in the DOMRequest's result field, an id that can be used to refer to this listener in other functions.
   // returns, in the DOMRequest's result field, an id that can be used to refer to this listener in other functions.
   DOMRequest watchChanges(Function handler, Function onError, UpdateType type);
   DOMRequest watchChanges(Function handler, Function onError, UpdateType type);
 
   // Watches for a file being renamed.
   // Watches for a file being renamed.
   // handler takes the file's old name, and the file's new name
   // handler takes the file's old name, and the file's new name
Line 54: Line 53:
   DOMRequest watchFileRename(DOMString name, Function handler, Function onError, UpdateType type);
   DOMRequest watchFileRename(DOMString name, Function handler, Function onError, UpdateType type);
   
   
   // Watches for any files being renamed
   // Watches for any files being renamed
   // handler takes the file's old name, and the file's new name
   // handler takes the file's old name, and the file's new name
Line 60: Line 58:
   // returns, in the DOMRequest's result field, an id that can be used to refer to this listener in other functions.
   // returns, in the DOMRequest's result field, an id that can be used to refer to this listener in other functions.
   DOMRequest watchRenames(Function handler, Function onError, UpdateType type);
   DOMRequest watchRenames(Function handler, Function onError, UpdateType type);
 
   // Removes a watcher with the given id.
   // Removes a watcher with the given id.
   boolean removeWatch(PRInt32 id);
   boolean removeWatch(PRInt32 id);
 
   // See interface below for how to use this
   // See interface below for how to use this
   DeviceStorageCursor enumerate(optional DOMString directory)
   DeviceStorageCursor enumerate(optional DOMString directory)
Line 71: Line 69:
  interface DeviceStorageCursor : DOMRequest {
  interface DeviceStorageCursor : DOMRequest {
   // .result is either a File or a FileHandle
   // .result is either a File or a FileHandle
   void continue();
   void continue();
  };
  };

Revision as of 18:14, 22 May 2012

This page contains a draft of the proposed modification to the DeviceStorage API to include onchanged notifications.

API

partial interface Navigator {
  /**
   * type is an arbitrary string. On OSs with predefined directories (pictures,
   * music, etc) we can match certain type names to certain folders.
   * To be figured out.
   *
   * Note that each value for the type represents a different directory.
   * I.e. passing "pictures" as type will yield a completely different set
   * of files from passing "movies" as the type.
   *
   * In other words, the type argument is not some sort of filter, but rather
   * simply a destination directory.
   */
  DeviceStorage getDeviceStorage(DOMString type);
};

interface DeviceStorage {
  // Name will be generated by the implementation and returned as result of request
  DOMRequest add(Blob blob);

  // Fails if a file with the given name already exists.
  DOMRequest addNamed(Blob blob, DOMString name);

  // Returns the result as a File object
  DOMRequest get(DOMString name);

  // Returns the result as a FileHandle object which enables writing
  DOMRequest getEditable(DOMString name);

  // Deletes a file
  DOMRequest delete(DOMString name);

  // Watches a file for updates: type is intended to be a list (probably a bitfield) of creation, deletion, and modification.
  // handler takes the file's name and an event type.
  // onError is an optional argument which is called if the process throws an error.
  // returns, in the DOMRequest's result field, an id that can be used to refer to this listener in other functions.
  DOMRequest watchFileChange(DOMString name, Function handler, Function onError, UpdateType type);

  // Watches all files for updates: type is intended to be a list (probably a bitfield) of creation, deletion, and modification.
  // handler takes the changed file's name and and an event type
  // onError is an optional argument which is called if the process throws an error.
  // returns, in the DOMRequest's result field, an id that can be used to refer to this listener in other functions.
  DOMRequest watchChanges(Function handler, Function onError, UpdateType type);

  // Watches for a file being renamed.
  // handler takes the file's old name, and the file's new name
  // onError is an optional argument which is called if the process throws an error.
  // returns, in the DOMRequest's result field, an id that can be used to refer to this listener in other functions.
  DOMRequest watchFileRename(DOMString name, Function handler, Function onError, UpdateType type);

  // Watches for any files being renamed
  // handler takes the file's old name, and the file's new name
  // onError is an optional argument which is called if the process throws an error.
  // returns, in the DOMRequest's result field, an id that can be used to refer to this listener in other functions.
  DOMRequest watchRenames(Function handler, Function onError, UpdateType type);

  // Removes a watcher with the given id.
  boolean removeWatch(PRInt32 id);

  // See interface below for how to use this
  DeviceStorageCursor enumerate(optional DOMString directory)
  DeviceStorageCursor enumerateEditable(optional DOMString directory)
};

interface DeviceStorageCursor : DOMRequest {
  // .result is either a File or a FileHandle
  void continue();
};

The cursor API is somewhat different from the IndexedDB cursor in that it's a bit simpler. We might want to align more with IndexedDB just for the sake of consistency.

Questions

  • Q: Why not use the W3C File System API? This API seems somewhat redundant with that part of the web platform.

Security/Privacy considerations

There are basically three different capabilities here:

  • Ability to add new files. This can't cause any harm in and of itself apart from using system resources.
  • Ability to read existing files. This isn't a security problem, but is a privacy problem.
  • Ability to modify/delete existing files. This can destroy user data.

Ability to add new files isn't terribly sensitive, simply asking the user might be sufficient here.

Ability to read existing files is more sensitive. Note that we should integrate device storage with <input type=file> such that the user is able to select a file from device storage on all platforms. That should significantly reduce the need for pages to use this API.

We could possibly further reduce the need by granting pages/apps the right to read files that they have added. I.e. only when wanting to read other files would we need to apply security restrictions. Implementing this on desktop will be hard though since we would have to keep additional meta-data on files that are stored in the user's "pictures", etc folders. I'm inclined to defer this aspect for now.

Ability to modify/delete existing files is extremely sensitive. We likely wouldn't want a scenario where the user simply answers yes to a "Do you want to let this website modify your pictures folder" and then have all of their vacation photos from the past 10 years destroyed.