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 filter is passed, the watcher will only return
  // If time is passed, the watcher will immediately call callback on each request which occurred since the given time.
  // The time is measured in milliseconds since Midnight GMT (00:00), January 1st, 1970.
  // returns a DOMRequest whose .result is a PRUint32 specifying a unique ID for the added watcher.
  DOMRequest addFileWatcher(Function callback, optional DOMString filter, optional PRInt64 time);

  // returns true if there was a watcher with this id, and false otherwise.
  boolean removeFileWatcher(PRUint32 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();
};