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

  // Watches a file, or all files for updates
  // If name is specified, watches a file with that name
  // returns the DeviceStorageWatch for this request, through which future requests will be processed
  DeviceStorageWatch watchChanges(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();
};

interface DeviceStorageWatch{
  // This enum represents the kinds of operations that an application can watch for
  enum UpdateType { DSWCreated, DSWModified, DSWDeleted };

  // this function is called whenever the file(s) addressed by the request are created, modified, or deleted
  // takes the file's name and type as its two arguments
  void (*onChange)(DOMString, UpdateType);
  // this function stops the watcher permanently
  void cancel();
}