// Copyright 2022 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
module crosapi.mojom;
import "mojo/public/mojom/base/file_path.mojom";
import "mojo/public/mojom/base/values.mojom";
import "ui/gfx/image/mojom/image.mojom";
// A file system is uniquely identified by an opaque string (consisting of at
// least the extension id + profile unique identifier) and a file_system_id.
[Stable]
struct FileSystemId {
// At a minimum, identifies the extension. May also need to identify profiles
// in the future.
string provider@0;
// A unique id (for a particular |provider|) provided by the extension.
string id@1;
};
// The primary data source for the file system.
[Stable, Extensible]
enum FileSystemSource {
[Default] kFile,
kNetwork,
kDevice
};
// Provides immutable metadata about a file system.
[Stable]
struct FileSystemMetadata {
// The identifier of the file system.
FileSystemId file_system_id@0;
// A human-readable name for the file system.
string display_name@1;
// Whether the file system supports operations which may change contents of
// the file system (such as creating, deleting or writing to files).
bool writable@2;
// The maximum number of files that can be opened at once. If 0, then not
// limited.
uint32 opened_files_limit@3;
// Whether the file system supports the tag field for observing directories.
bool supports_notify@4;
};
// Files can be opened either for reading or writing.
[Stable, Extensible]
enum OpenFileMode {
[Default] kRead,
kWrite,
};
[Stable]
struct OpenedFile {
// A request ID to be be used by consecutive read/write and close requests.
int64 open_request_id@0;
// The path of the opened file. While it seems like it would make sense to use
// a base::Path, both the extension API and the ash FileSystemProvider API
// pass strings.
string file_path@1;
// Whether the file was opened for reading or writing.
OpenFileMode mode@2;
};
// Represents a watcher.
[Stable]
struct FSPWatcher {
// The path of the entry being observed.
mojo_base.mojom.FilePath entry_path@0;
// Whether watching should include all child entries recursively. It can be
// true for directories only.
bool recursive@1;
// Tag used by the last notification for the watcher.
string last_tag@2;
};
[Stable]
struct FileSystemInfo {
// Fixed metadata about the file system.
FileSystemMetadata metadata@0;
// List of currently opened files.
array<OpenedFile> opened_files@1;
// List of watchers.
array<FSPWatcher> watchers@2;
};
[Stable, Extensible]
enum FSPChangeType {
[Default] kChanged,
kDeleted
};
[Stable]
struct CloudFileInfo {
string? version_tag@0;
};
[Stable]
struct FSPChange {
// Next MinVersion: 2
FSPChangeType type@0;
mojo_base.mojom.FilePath path@1;
[MinVersion=1] CloudFileInfo? cloud_file_info@2;
};
[Stable, Extensible]
enum FSPOperationResponse {
// Next MinVersion: 2
[Default] kUnknown,
kUnmountSuccess,
kGetEntryMetadataSuccess,
kGetActionsSuccess,
kReadDirectorySuccess,
kReadFileSuccess,
kGenericSuccess,
kGenericFailure,
[MinVersion=1] kOpenFileSuccess,
};
[Stable, Extensible]
enum FSPForwardResult {
[Default] kUnknown,
kSuccess,
kInternalError,
kNoListener,
};
// Implemented by Lacros.
[Stable, Uuid="8cbcf151-c189-4fe9-90ff-892c7f5637a9"]
interface FileSystemProvider {
// Allows Ash to forward requests to Lacros extension providers.
// We use mojo_base.mojom.Value as the type because:
// * The extension API is stable.
// * Both the supplier and consumer of this information uses a type
// interchangeable with mojo_base.mojom.Value. While we could add a
// translation layer to a strongly typed mojom struct, this adds a
// overhead and the potential for errors with no benefit.
// Similarly, histogram_value is an int32 instead of the native enum
// HistogramValue because the enum is stable, has hundreds of entries, and
// cannot be type-mapped due to build-time dependency inversions.
// Provider will typically be an extension_id but is intentionally left
// abstract to support multi-profile in the future.
// |delivery_failure| is set to true if the operation could not be forwarded
// to the extension for any reason.
[MinVersion=1]
DeprecatedDeprecatedForwardOperation@0(
string provider, int32 histogram_value, string event_name,
array<mojo_base.mojom.Value> args);
[MinVersion=2]
DeprecatedForwardOperation@1(
string provider, int32 histogram_value, string event_name,
array<mojo_base.mojom.Value> args) => (bool delivery_failure);
[MinVersion=3]
ForwardOperation@2(
string provider, int32 histogram_value, string event_name,
mojo_base.mojom.ListValue args) => (bool delivery_failure);
// Same as ForwardOperation, but exposes request metadata uniquely identifying
// a request. A request is uniquely identified by a tuple of:
// - |provider|, |file_system_id|, |request_id|: for requests addressed to a
// specific file system instance.
// - |provider|, |request_id|: for requests addressed to a provider in general
// (e.g. a request to mount a new filesystem). In this case,
// |file_system_id| will be null.
[MinVersion=4]
ForwardRequest@3(
string provider, string? file_system_id, int64 request_id,
int32 histogram_value, string event_name,
mojo_base.mojom.ListValue args) => (FSPForwardResult result);
// Signal to Lacros that Ash cancelled a request uniquely identified by
// given parameters.
[MinVersion=4]
CancelRequest@4(
string provider, string? file_system_id, int64 request_id);
};
// Implemented by Ash. Extensions in Lacros can register themselves as file
// system providers. As the underlying system in Ash already supports
// multiplexing, we refrain from introducing a second layer of multiplexing at
// the crosapi layer. Lacros registers itself as a FileSystemProvider at
// startup. Extensions will call the "mount" method to make themselves known to
// Ash. At that point, Ash will send operations via FileSystemProvider, which
// Lacros will fulfill by calling methods in FileSystemProviderService. This
// creates a state machine with state spread between Ash and Lacros. This is
// dispreferred but unfortunately impossible to avoid given the design of the
// fileSystemProvider extension API.
[Stable, Uuid="82db93f7-e0a5-4a9c-a09f-db92f9e45348"]
interface FileSystemProviderService {
// File system providers use this interface to receive operation requests.
RegisterFileSystemProvider@0(pending_remote<FileSystemProvider> provider);
// Makes a filesystem provided by an extension visible to the operating system
// and other consumers.
Mount@1(FileSystemMetadata metadata, bool persistent) => (string error);
// Makes a filesystem provided by an extension unavailable.
Unmount@2(FileSystemId file_system_id) => (string error);
// Returns all file systems mounted by the extension.
GetAll@3(string provider) => (array<FileSystemInfo> infos);
// Returns information about a file system with the passed file_system_id.
Get@4(FileSystemId file_system_id) => (FileSystemInfo? info);
// Called by the extension to notify watchers of changes.
// |file_system_id| is the identifier of the file system related to this
// change.
// |watcher| gives information about the path being observed, including the
// tag.
// |type| provides information about the observed entry.
// |changes| provides information about the observed directory.
// Note: for backwards compatibility with the existing extension API, both
// |type| and |changes| are necessary even though they appear mutually
// exclusive.
Notify@5(FileSystemId file_system_id, FSPWatcher watcher,
FSPChangeType type, array<FSPChange> changes) => (string error);
// The following function represents responses from the Extension after
// handling an operation. We use mojo_base.mojom.Value as the type because:
// * The extension API is stable.
// * Both the supplier and consumer of this information uses a type
// interchangeable with mojo_base.mojom.Value. While we could add a
// translation layer to a strongly typed mojom struct, this adds a
// overhead and the potential for errors with no benefit.
// |request_id| corresponds to ids passed in via methods on interface
// FileSystemProvider.
[MinVersion=1]
DeprecatedOperationFinished@6(FSPOperationResponse response,
FileSystemId file_system_id, int64 request_id,
array<mojo_base.mojom.Value> args) => (string error);
[MinVersion=3]
OperationFinished@9(FSPOperationResponse response,
FileSystemId file_system_id, int64 request_id,
mojo_base.mojom.ListValue args) => (string error);
// Handles return the success callback from the `OpenFile` method after the
// optional metadata dictionary support was added.
// The underlying functionality behaves similarly to the `OperationFinished`
// method above, however, having it as an interface method enables validating
// whether the remote version supports the callback or not.
[MinVersion=6]
OpenFileFinishedSuccessfully@12(FileSystemId file_system_id,
int64 request_id,
mojo_base.mojom.ListValue args) => (string error);
// The following function represents responses from the Extension after
// handling a mount request. As opposed to `OperationFinished`, these
// requests are handled per-provider instead of per provided file system
// (no `FileSystemId).
// |request_id| corresponds to ids passed in via methods on interface
// FileSystemProvider.
[MinVersion=4]
MountFinished@10(string extension_id, int64 request_id,
mojo_base.mojom.ListValue args) => (string error);
// Called by Lacros when a filesystem providing extension is loaded.
[MinVersion=2]
ExtensionLoadedDeprecated@7(
bool configurable, bool watchable, bool multiple_mounts,
FileSystemSource source, string extension_name, string extension_id);
// Called by Lacros when a filesystem providing extension is loaded. This
// version passes the extension's icons to use in the file browser.
[MinVersion=5]
ExtensionLoaded@11(
bool configurable, bool watchable, bool multiple_mounts,
FileSystemSource source, string extension_name, string extension_id,
gfx.mojom.ImageSkia? icon16x16, gfx.mojom.ImageSkia? icon32x32);
// Called by Lacros when a filesystem providing extension is unloaded.
[MinVersion=2]
ExtensionUnloaded@8(string id, bool due_to_shutdown);
};
Codebase Browser
chromium