WebAPI/ProposedDeviceStorageAPIWithNotifications

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);

  // Create a watcher which will call the callback function every time files are updated
  // callback will take the DeviceStorage, the file's name, and the update type, which will be one of "created", "deleted", or "modified"
  // If name is passed, the file watcher will only watch the file with the specified name.
  boolean addFileWatcher(Function callback, optional DOMstring name);

  // returns true if there was a watcher with this id, and false otherwise.
  boolean removeFileWatcher(Function callback, optional DOMstring name);

  // 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();
};

An example callback:

store.addFileWatcher(callback);
...
void callback (DeviceStorage store, DOMString name, DOMString type){
   //do stuff
};