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
+// Describes the type of a change made to a document.
+[Extensible]
+enum ChangeType {
+  // Indicates that the child document list of the watched directory was
+  // changed. Note that a watcher can be installed only on directory for now.
+  CHANGED = 0,
+
+  // Indicates that the watched document itself was deleted.
+  // When OnDocumentChanged() is called with this change type, the corresponding
+  // watcher has been already uninstalled and the host should not call
+  // RemoveWatcher().
+  DELETED = 1,
+};
+
+
+// Next method ID: 1
+interface FileSystemHost {
+  // Called when a watched document was changed.
+  // |type| describes the type of change made to the document. If |type| is
+  // DELETED, the watcher has been already removed and the host should not call
+  // RemoveWatcher().
+  [MinVersion=3] OnDocumentChanged@0(int64 watcher_id, ChangeType type);
+};
+
+// 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.
+  //
+  // Note: Currently, watchers can be installed only on directories, and only
+  // directory content changes are notified.
+  //
+  // On success, a positive unique integer is returned as a watcher ID.
+  // FileSystemHost.OnDocumentChanged() will be called with the watcher ID
+  // on directory content changes.
+  // On failure, -1 is returned.
+  //
+  // It is allowed to install multiple watchers to the same directory. 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);

[dcheng, 2017/02/23 19:07:07]

Btw, I know this is the pattern in ARC++, but for other code like this, we've
been moving towards a factory model where we ensure a 1:1 binding by using a
factory interface, e.g.

interface ArcInterfaceFactory {
  CreateFileSystemInstance(FileSystemHost&) => (FileSystemInstance);
}

Which guarantees:
- 1:1 binding
- that Init() won't be called multiple times
- easier to understand (probably)

Is that something we could investigate for ARC++?

+
   // 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.
+  //
+  // It fails if the specified watcher does not exist. Note that a watcher
+  // can be automatically uninstalled when a watched document is deleted
+  // (notified by OnDocumentChanged() with |type| = DELETED).
+  [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);
 };