file_system_provider.mojom 7.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222
  1. // Copyright 2022 The Chromium Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. module crosapi.mojom;
  5. import "mojo/public/mojom/base/big_buffer.mojom";
  6. import "mojo/public/mojom/base/file_path.mojom";
  7. import "mojo/public/mojom/base/values.mojom";
  8. // A file system is uniquely identified by an opaque string (consisting of at
  9. // least the extension id + profile unique identifier) and a file_system_id.
  10. [Stable]
  11. struct FileSystemId {
  12. // At a minimum, identifies the extension. May also need to identify profiles
  13. // in the future.
  14. string provider@0;
  15. // A unique id (for a particular |provider|) provided by the extension.
  16. string id@1;
  17. };
  18. // The primary data source for the file system.
  19. [Stable, Extensible]
  20. enum FileSystemSource {
  21. [Default] kFile,
  22. kNetwork,
  23. kDevice
  24. };
  25. // Provides immutable metadata about a file system.
  26. [Stable]
  27. struct FileSystemMetadata {
  28. // The identifier of the file system.
  29. FileSystemId file_system_id@0;
  30. // A human-readable name for the file system.
  31. string display_name@1;
  32. // Whether the file system supports operations which may change contents of
  33. // the file system (such as creating, deleting or writing to files).
  34. bool writable@2;
  35. // The maximum number of files that can be opened at once. If 0, then not
  36. // limited.
  37. uint32 opened_files_limit@3;
  38. // Whether the file system supports the tag field for observing directories.
  39. bool supports_notify@4;
  40. };
  41. // Files can be opened either for reading or writing.
  42. [Stable, Extensible]
  43. enum OpenFileMode {
  44. [Default] kRead,
  45. kWrite,
  46. };
  47. [Stable]
  48. struct OpenedFile {
  49. // A request ID to be be used by consecutive read/write and close requests.
  50. int64 open_request_id@0;
  51. // The path of the opened file. While it seems like it would make sense to use
  52. // a base::Path, both the extension API and the ash FileSystemProvider API
  53. // pass strings.
  54. string file_path@1;
  55. // Whether the file was opened for reading or writing.
  56. OpenFileMode mode@2;
  57. };
  58. // Represents a watcher.
  59. [Stable]
  60. struct FSPWatcher {
  61. // The path of the entry being observed.
  62. mojo_base.mojom.FilePath entry_path@0;
  63. // Whether watching should include all child entries recursively. It can be
  64. // true for directories only.
  65. bool recursive@1;
  66. // Tag used by the last notification for the watcher.
  67. string last_tag@2;
  68. };
  69. [Stable]
  70. struct FileSystemInfo {
  71. // Fixed metadata about the file system.
  72. FileSystemMetadata metadata@0;
  73. // List of currently opened files.
  74. array<OpenedFile> opened_files@1;
  75. // List of watchers.
  76. array<FSPWatcher> watchers@2;
  77. };
  78. [Stable, Extensible]
  79. enum FSPChangeType {
  80. [Default] kChanged,
  81. kDeleted
  82. };
  83. [Stable]
  84. struct FSPChange {
  85. FSPChangeType type@0;
  86. mojo_base.mojom.FilePath path@1;
  87. };
  88. [Stable, Extensible]
  89. enum FSPOperationResponse {
  90. [Default] kUnknown,
  91. kUnmountSuccess,
  92. kGetEntryMetadataSuccess,
  93. kGetActionsSuccess,
  94. kReadDirectorySuccess,
  95. kReadFileSuccess,
  96. kGenericSuccess,
  97. kGenericFailure,
  98. };
  99. // Implemented by Lacros.
  100. [Stable, Uuid="8cbcf151-c189-4fe9-90ff-892c7f5637a9"]
  101. interface FileSystemProvider {
  102. // Allows Ash file system to forward an operation to Lacros extension
  103. // providers.
  104. // We use mojo_base.mojom.Value as the type because:
  105. // * The extension API is stable.
  106. // * Both the supplier and consumer of this information uses a type
  107. // interchangeable with mojo_base.mojom.Value. While we could add a
  108. // translation layer to a strongly typed mojom struct, this adds a
  109. // overhead and the potential for errors with no benefit.
  110. // Similarly, histogram_value is an int32 instead of the native enum
  111. // HistogramValue because the enum is stable, has hundreds of entries, and
  112. // cannot be type-mapped due to build-time dependency inversions.
  113. // Provider will typically be an extension_id but is intentionally left
  114. // abstract to support multi-profile in the future.
  115. // |delivery_failure| is set to true if the operation could not be forwarded
  116. // to the extension for any reason.
  117. [MinVersion=1]
  118. DeprecatedDeprecatedForwardOperation@0(
  119. string provider, int32 histogram_value, string event_name,
  120. array<mojo_base.mojom.Value> args);
  121. [MinVersion=2]
  122. DeprecatedForwardOperation@1(
  123. string provider, int32 histogram_value, string event_name,
  124. array<mojo_base.mojom.Value> args) => (bool delivery_failure);
  125. [MinVersion=3]
  126. ForwardOperation@2(
  127. string provider, int32 histogram_value, string event_name,
  128. mojo_base.mojom.ListValue args) => (bool delivery_failure);
  129. };
  130. // Implemented by Ash. Extensions in Lacros can register themselves as file
  131. // system providers. As the underlying system in Ash already supports
  132. // multiplexing, we refrain from introducing a second layer of multiplexing at
  133. // the crosapi layer. Lacros registers itself as a FileSystemProvider at
  134. // startup. Extensions will call the "mount" method to make themselves known to
  135. // Ash. At that point, Ash will send operations via FileSystemProvider, which
  136. // Lacros will fulfill by calling methods in FileSystemProviderService. This
  137. // creates a state machine with state spread between Ash and Lacros. This is
  138. // dispreferred but unfortunately impossible to avoid given the design of the
  139. // fileSystemProvider extension API.
  140. [Stable, Uuid="82db93f7-e0a5-4a9c-a09f-db92f9e45348"]
  141. interface FileSystemProviderService {
  142. // File system providers use this interface to receive operation requests.
  143. RegisterFileSystemProvider@0(pending_remote<FileSystemProvider> provider);
  144. // Makes a filesystem provided by an extension visible to the operating system
  145. // and other consumers.
  146. Mount@1(FileSystemMetadata metadata, bool persistent) => (string error);
  147. // Makes a filesystem provided by an extension unavailable.
  148. Unmount@2(FileSystemId file_system_id) => (string error);
  149. // Returns all file systems mounted by the extension.
  150. GetAll@3(string provider) => (array<FileSystemInfo> infos);
  151. // Returns information about a file system with the passed file_system_id.
  152. Get@4(FileSystemId file_system_id) => (FileSystemInfo? info);
  153. // Called by the extension to notify watchers of changes.
  154. // |file_system_id| is the identifier of the file system related to this
  155. // change.
  156. // |watcher| gives information about the path being observed, including the
  157. // tag.
  158. // |type| provides information about the observed entry.
  159. // |changes| provides information about the observed directory.
  160. // Note: for backwards compatibility with the existing extension API, both
  161. // |type| and |changes| are necessary even though they appear mutually
  162. // exclusive.
  163. Notify@5(FileSystemId file_system_id, FSPWatcher watcher,
  164. FSPChangeType type, array<FSPChange> changes) => (string error);
  165. // The following function represents responses from the Extension after
  166. // handling an operation. We use mojo_base.mojom.Value as the type because:
  167. // * The extension API is stable.
  168. // * Both the supplier and consumer of this information uses a type
  169. // interchangeable with mojo_base.mojom.Value. While we could add a
  170. // translation layer to a strongly typed mojom struct, this adds a
  171. // overhead and the potential for errors with no benefit.
  172. // |request_id| corresponds to ids passed in via methods on interface
  173. // FileSystemProvider.
  174. [MinVersion=1]
  175. DeprecatedOperationFinished@6(FSPOperationResponse response,
  176. FileSystemId file_system_id, int64 request_id,
  177. array<mojo_base.mojom.Value> args) => (string error);
  178. [MinVersion=3]
  179. OperationFinished@9(FSPOperationResponse response,
  180. FileSystemId file_system_id, int64 request_id,
  181. mojo_base.mojom.ListValue args) => (string error);
  182. // Called by Lacros when a filesystem providing extension is loaded.
  183. [MinVersion=2]
  184. ExtensionLoaded@7(bool configurable, bool watchable, bool multiple_mounts,
  185. FileSystemSource source, string extension_name, string extension_id);
  186. // Called by Lacros when a filesystem providing extension is unloaded.
  187. [MinVersion=2]
  188. ExtensionUnloaded@8(string id, bool due_to_shutdown);
  189. };