[fsp] Add support for observing entries and notifying about changes.

chrome/common/extensions/api/file_system_provider.idl

 // Copyright 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // Use the <code>chrome.fileSystemProvider</code> API to create file systems,
 // that can be accessible from the file manager on Chrome OS.
 [platforms=("chromeos"),
  implemented_in="chrome/browser/chromeos/extensions/file_system_provider/file_system_provider_api.h"]
 namespace fileSystemProvider {
   // Error codes used by providing extensions in response to requests. For
@@ skipping 16 matching lines @@
     INVALID_URL,
     IO
   };
 
   // Mode of opening a file. Used by <code>onOpenFileRequested</code>.
   enum OpenFileMode {
     READ,
     WRITE
   };
 
+  // Type of a change detected on the observed directory.
+  enum ChangeType {
+    CHANGED,
+    DELETED
+  };
+
   // Represents metadata of a file or a directory.
   dictionary EntryMetadata {
     // True if it is a directory.
     boolean isDirectory;
 
     // Name of this entry (not full path name).
     DOMString name;
 
     // File size in bytes.
     double size;
 
     // The last modified time of this entry.
     [instanceOf=Date] object modificationTime;
 
     // Mime type for the entry.
     DOMString? mimeType;
 
     // Thumbnail image as a data URI in either PNG, JPEG or WEBP format, at most
     // 32 KB in size. Optional, but can be provided only when explicitly
     // requested by the <code>onGetMetadataRequested</code> event.
     DOMString? thumbnail;
   };
 
+  // Represents an observed entry.
+  dictionary ObservedEntry {
+    // The path of the entry being observed.
+    DOMString entryPath;
+
+    // Whether observing should include all child entries recursively.
+    boolean recursive;
+
+    // Tag used by the last notification for the observed path.
+    DOMString? lastTag;
+  };
+
   // Represents a mounted file system.
   dictionary FileSystemInfo {
     // The identifier of the file system.
     DOMString fileSystemId;
 
     // A human-readable name for the file system. 
     DOMString displayName;
 
     // Whether the file system supports operations which may change contents
     // of the file system (such as creating, deleting or writing to files).
     boolean writable;
+
+    // Whether the file system supports the <code>tag</code> field for observing
+    // directories.
+    [nodoc] boolean? supportsNotifyTag;
+
+    // List of observed entries.
+    [nodoc] ObservedEntry[] observedEntries;
   };
 
   // Options for the <code>mount()</code> method.
   dictionary MountOptions {
     // The string indentifier of the file system. Must be unique per each
     // extension.
     DOMString fileSystemId;
 
     // A human-readable name for the file system. 
     DOMString displayName;
 
     // Whether the file system supports operations which may change contents
     // of the file system (such as creating, deleting or writing to files).
     boolean? writable;
+
+    // Whether the file system supports the <code>tag</code> field for observed
+    // directories. Required in order to enable the internal cache.
+    [nodoc] boolean? supportsNotifyTag;
   };
 
   // Options for the <code>unmount()</code> method.
   dictionary UnmountOptions {
     // The identifier of the file system to be unmounted.
     DOMString fileSystemId;
   };
 
   // Options for the <code>onUnmountRequested()</code> event.
   dictionary UnmountRequestedOptions {
@@ skipping 181 matching lines @@
   };
 
   // Options for the <code>onAbortRequested()</code> event.
   dictionary AbortRequestedOptions {
     // The identifier of the file system related to this operation.
     DOMString fileSystemId;
 
     // The unique identifier of this request.
     long requestId;
 
-    // An ID of the request to be aborted.
+    // An ID of the request tothis change.

[benwells, 2014/10/09 04:36:44]

nit: "tothis". not sure if this change is intentional, it seemed to make sense
before.

[mtomasz, 2014/10/09 07:37:52]

Accidental change. Done.

     long operationRequestId;
   };
 
+  // Options for the <code>onObserveDirectoryRequested()</code> event.
+  dictionary ObserveDirectoryRequestedOptions {
+    // The identifier of the file system related to this operation.
+    DOMString fileSystemId;
+
+    // The unique identifier of this request.
+    long requestId;
+
+    // The path of the directory to be observed.
+    DOMString directoryPath;
+
+    // Whether observing should include all child entries recursively.
+    boolean recursive;
+  };
+
+  // Options for the <code>onUnobserveEntryRequested()</code> event.
+  dictionary UnobserveEntryRequestedOptions {
+    // The identifier of the file system related to this operation.
+    DOMString fileSystemId;
+
+    // The unique identifier of this request.
+    long requestId;
+
+    // The path of the entry to be not observed anymore.
+    DOMString entryPath;
+  };
+
+  // Information about a change happened to an entry within the observed
+  // directory.
+  dictionary ChildChange {
+    // The path of the changed entry.
+    DOMString entryPath;
+
+    // The type of the change which happened to the entry.
+    ChangeType changeType;
+  };
+
+  // Options for the <code>Notify()</code> method.
+  dictionary NotifyOptions {
+    // The identifier of the file system related to this change.
+    DOMString fileSystemId;
+
+    // The path of the observed entry.
+    DOMString observedPath;
+
+    // The type of the change which happened to the observed entry. If it is
+    // DELETED, then the observed entry will be automatically removed from the
+    // list of observed entries.
+    ChangeType changeType;
+
+    // List of changes to entries within the observed directory.
+    ChildChange[]? childChanges;
+
+    // Tag for the notification. Required if the file system was mounted with
+    // the <code>supportsNotifyTag</code> option. Note, that this flag is
+    // necessary to provide notifications about changes which changed even
+    // when the system was shutdown.
+    DOMString? tag;
+  };
+
   // Callback to receive the result of mount() function.
   callback MountCallback = void([nodoc, instanceOf=DOMError] object error);
 
   // Callback to receive the result of unmount() function.
   callback UnmountCallback = void([nodoc, instanceOf=DOMError] object error);
 
   // Callback to receive the result of getAll() function.
   callback GetAllCallback = void(FileSystemInfo[] fileSystems);
 
   // Callback to handle an error raised from the browser.
@@ skipping 44 matching lines @@
     // the providing extension can decide to perform unmounting if not requested
     // (eg. in case of lost connection, or a file error). If there is no file
     // system with the requested id, or unmounting fails, then the
     // <code>errorCallback</code> will be called.
     static void unmount(UnmountOptions options,
                         UnmountCallback successCallback,
                         [nocompile] ErrorCallback errorCallback);
 
     // Returns all file systems mounted by the extension.
     static void getAll(GetAllCallback callback);
+
+    // Notifies about changes in the observed directory at <code>
+    // observedPath</code>. If the file system is mounted with <code>
+    // supportsNofityTag</code>, then <code>tag</code> must be provided, and
+    // all changes since the last notification always reported, even if the
+    // system was shutdown. The last tag can be obtained with <code>
+    // getAll()</code>. Note, that tag is required in order to enable the
+    // internal cache.

[benwells, 2014/10/09 04:36:44]

This stuff about tagging isn't very obvious (i.e. it won't be obvious to someone
trying to use this documentation to make a file system provider).

I think you should explain more or add a TODO to explain it better.

[mtomasz, 2014/10/09 07:37:52]

Done.

+    [nodoc] static void notify(NotifyOptions options);
   };
 
   interface Events {
     // Raised when unmounting for the file system with the <code>fileSystemId
     // </code> identifier is requested. In the response, the <code>unmount
     // </code> API method must be called together with <code>successCallback
     // </code>. If unmounting is not possible (eg. due to a pending operation),
     // then <code>errorCallback</code> must be called.
     [maxListeners=1] static void onUnmountRequested(
         UnmountRequestedOptions options,
@@ skipping 98 matching lines @@
     // is requested. The operation executed with <code>operationRequestId</code>
     // must be immediately stopped and <code>successCallback</code> of this
     // abort request executed. If aborting fails, then <code>errorCallback
     // </code> must be called. Note, that callbacks of the aborted operation
     // must not be called, as they will be ignored. Despite calling <code>
     // errorCallback</code>, the request may be forcibly aborted. 
     [maxListeners=1] static void onAbortRequested(
         AbortRequestedOptions options,
         ProviderSuccessCallback successCallback,
         ProviderErrorCallback errorCallback);
+
+    // Raised when setting a new directory watcher is requested. If an error
+    // occurs, then <code>errorCallback</code> must be called.
+    [maxListeners=1, nodoc] static void onObserveDirectoryRequested(
+      ObserveDirectoryRequestedOptions options,
+      ProviderSuccessCallback successCallback,
+      ProviderErrorCallback errorCallback);
+
+    // Raised when the entry should no longer be observed. If an error occurs,
+    // then <code>errorCallback</code> must be called.
+    [maxListeners=1, nodoc] static void onUnobserveEntryRequested(
+      UnobserveEntryRequestedOptions options,
+      ProviderSuccessCallback successCallback,
+      ProviderErrorCallback errorCallback);
   };
 };