mediaview: IPC definitions to watch for document changes.

components/arc/common/file_system.mojom

 // Copyright 2016 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.
 //
-// Next MinVersion: 3
+// Next MinVersion: 4
 
 module arc.mojom;
 
 // Represents a document in Android DocumentsProvider.
 // See Android docs of DocumentsContract.Document for details.
 struct Document {
   // Opaque ID of the document.
   string document_id;
 
   // Display name of the document.
   string display_name;
 
   // MIME type of the document.
   // A directory is represented by a document having MIME_TYPE_DIR MIME type.
   string mime_type;
 
   // Size of the document in bytes. If the size is unknown, -1 is set.
   int64 size;
 
   // Timestamp when the document was modified last time, in milliseconds
   // since UNIX epoch.
   // TODO(crbug.com/672737): Use mojo.common.mojom.Time once the type is
   // converted to a non-native type so that it can be used from Java.
   uint64 last_modified;
 };
 
-// Next method ID: 5
+// Next method ID: 1
+interface FileSystemHost {
+  // Called when a watched document was changed or deleted.
+  // If |deleted| is true, the watcher has been already removed and the host
+  // does not need to explicitly call RemoveWatcher().
+  [MinVersion=3] OnDocumentChanged@0(int64 watcher_id, bool deleted);

[Luis Héctor Chávez, 2017/02/22 17:29:31]

I'd prefer to replace |bool deleted| with an enum indicating the nature of the
change. Or a struct with even more information, but that depends on whether the
implementation will eagerly refresh metadata (struct would be preferred) or do
it lazily thus coalescing multiple changed notifications (enum is sufficient).

[Shuhei Takahashi, 2017/02/23 03:37:22]

Sure, let's use enum instead.

We are not going to do eager refreshing because the expected caller
(storage::WatcherManager) does not support such protocol.

+};
+
+// Next method ID: 8
 interface FileSystemInstance {
   // Notes about Android Documents Provider:
   //
   // In Android Storage Access Framework, a document is uniquely identified by
   // a pair of "authority" and "document ID".
   //
   // - An authority specifies a Documents Provider that serves a document.
   //   It is the origin part of a content:// URI used to access the Documents
   //   Provider via Content Resolver protocol.
   //   Example: "com.android.providers.media.documents"
   // - A document ID is an opaque string that specifies a particular document
   //   in a documents provider. Its format varies by providers.
   //
   // See the following documents for details about Documents Provider:
   // https://developer.android.com/guide/topics/providers/document-provider.html
   // https://developer.android.com/reference/android/provider/DocumentsContract.html
 
+  // Installs a document watcher to watch updates of a document.
+  //
+  // On success, a positive unique integer is returned as a watcher ID and
+  // FileSystemHost.OnDocumentChanged() will be called with the watcher ID
+  // on document changes until the watcher is removed by RemoveWatcher().
+  // On failure, -1 is returned.
+  //
+  // It is allowed to install multiple watchers to the same document. In that
+  // case, different watcher IDs are returned.
+  [MinVersion=3] AddWatcher@6(string authority, string document_id) =>
+      (int64 watcher_id);
+
   // Queries child documents of the directory specified by |authority| and
   // |parent_document_id| in Documents Provider.
   // If such a directory does not exist, null is returned.
   [MinVersion=2] GetChildDocuments@4(string authority,
                                      string parent_document_id) =>
       (array<Document>? documents);
 
   // Queries the document specified by |authority| and |document_id| in
   // Documents Provider.
   // If such a document does not exist, null is returned.
   [MinVersion=2] GetDocument@3(string authority, string document_id) =>
       (Document? document);
 
   // Asks the ContentResolver for the size of the file specified by the URL.
   // If the file does not exist or the size is unknown (e.g. directories and
   // streams), -1 is returned.
   [MinVersion=1] GetFileSize@1(string url) => (int64 size);
 
+  // Establishes full-duplex communication with the host.
+  [MinVersion=3] Init@5(FileSystemHost host_ptr);
+
   // Asks the ContentResolver to get a FD to read the file specified by the
   // URL.
   [MinVersion=1] OpenFileToRead@2(string url) => (handle? fd);
 
+  // Uninstalls a document watcher.

[Luis Héctor Chávez, 2017/02/22 17:29:31]

Please document the semantics of uninstalling a document watcher that has been
deleted, given the wording of the comment above OnDocumentChanged() ("does not
need to explicitly call").

[Shuhei Takahashi, 2017/02/23 03:37:22]

I changed the comment of OnDocumentChanged():

  Before: the host does not need to explicitly call RemoveWatcher()
  After: the host should not call RemoveWatcher()

And updated the comments around here to be more explicit about semantics.

+  [MinVersion=3] RemoveWatcher@7(int64 watcher_id) => (bool success);
+
   // Requests MediaProvider to scan specified files.
   // When the specified file does not exist, the corresponding entry in
   // MediaProvider is removed.
   RequestMediaScan@0(array<string> paths);
 };