// 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: 7

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;

  // Path to a real file on the Android VFS corresponding to this document,
  // e.g. "/storage/emulated/0/DCIM/kitten.jpg".
  // This value is available in limited DocumentsProviders only. If the
  // provider does not expose real VFS paths, this field is always set to null.
  [MinVersion=5] string? android_file_system_path;
};

// 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.
  // Even if OnDocumentChanged() is called with this change type, the
  // corresponding watcher is not uninstalled automatically. The host must
  // call RemoveWatcher() to clean up an orphaned watcher.
  DELETED = 1,
};


// Next method ID: 5
interface FileSystemHost {
  // Returns the name of the file specified by the URL.
  // When an error occurs, returns null value.
  [MinVersion=6] GetFileName@1(string url) => (string? name);

  // Returns 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=6] GetFileSize@2(string url) => (int64 size);

  // Returns the MIME type of the file specified by the URL.
  // When an error occurs, returns null value.
  [MinVersion=6] GetFileType@3(string url) => (string? mime_type);

  // Called when a watched document was changed.
  // |type| describes the type of change made to the document.
  [MinVersion=3] OnDocumentChanged@0(int64 watcher_id, ChangeType type);

  // Returns an FD for reading the file specified by the URL.
  [MinVersion=6] OpenFileToRead@4(string url) => (handle? fd);
};

// Next method ID: 10
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 documents provider may provide one or more roots. Each root is identified
  //   by a root ID.
  // - A document ID is an opaque string that specifies a particular document
  //   in a documents provider. Its format varies by providers. Roots also have
  //   associated document IDs.
  //
  // 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.
  //
  // 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.
  //
  // Watchers are not persistent. When the Mojo connection is lost, all
  // watchers are cleared. Also, after reconnecting, watcher IDs can be reused.
  [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);

  // Asks the ContentResolver to get the MIME type of the file specified by the
  // URL. When an error occurs, returns null value.
  [MinVersion=4] GetMimeType@8(string url) => (string? mime_type);

  // Queries recent documents of a root specified by |authority| and |root_id|.
  // If the root exists and it supports recent document queries, a (possibly
  // empty) list of documents is returned. Otherwise, null is returned.
  [MinVersion=5] GetRecentDocuments@9(string authority, string root_id) =>
      (array<Document>? documents);

  // 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.
  //
  // After this method call returns, OnDocumentChanged() will never be called
  // with the watcher ID. Whether OnDocumentChanged() is called or not after
  // this method is called and before this method returns is undefined.
  //
  // It fails if the specified watcher does not exist.
  [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);
};