third_party/blink/public/mojom/filesystem/file_system.mojom

// Copyright 2018 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module blink.mojom;

import "components/services/filesystem/public/mojom/types.mojom";
import "url/mojom/origin.mojom";
import "url/mojom/url.mojom";
import "mojo/public/mojom/base/file_error.mojom";
import "mojo/public/mojom/base/file_path.mojom";
import "mojo/public/mojom/base/file_info.mojom";
import "mojo/public/mojom/base/time.mojom";
import "third_party/blink/public/mojom/blob/serialized_blob.mojom";
import "third_party/blink/public/mojom/blob/blob.mojom";

enum FileSystemType {
  kTemporary,
  kPersistent,
  kIsolated,
  kExternal
};

struct FileSystemInfo {
  string name;
  url.mojom.Url root_url;
  FileSystemType mount_type = kTemporary;
};

// Interface for renderers to cancel running file system operations. A
// pending_receiver<FileSystemCancellableOperation> is passed as a parameter for
// any operation that can be cancelled.
interface FileSystemCancellableOperation {
  // Cancels the associated operation. It may not always be possible to cancel
  // an operation, and partial writes are possible. |error_code| indicates if
  // the operation was successfully canceled.
  Cancel() => (mojo_base.mojom.FileError error_code);
};

// Operations that need to repeatedly call a particular callback use this
// interface. For example, the Write operation needs to call DidWrite
// repeatedly, and uses a pending_remote<FileSystemOperationListener> passed
// from the renderer to call it.
// Note: For operations that only need a callback called once, we can directly
// use mojo return value callbacks.
interface FileSystemOperationListener {
  // Called by ReadDirectory when entries have been obtained. |has_more| is
  // false when all the entries are obtained, and indicates that the callback
  // will not be called again.
  ResultsRetrieved(array<filesystem.mojom.DirectoryEntry> entries,
                   bool has_more);

  // Called repeatedly by Write to indicate progress. If |complete| is true,
  // the operation is complete and the callback will not be called again.
  DidWrite(int64 byte_count, bool complete);

  // Called by all operations that use a listener to indicate an error. No
  // other listener callbacks will be called after this.
  ErrorOccurred(mojo_base.mojom.FileError error_code);
};

// Used by the renderer to notify the browser that it has received a snapshot
// after calling CreateSnapshotFile. The browser sends a pending remote along
// with the result of the CreateSnapshotFile call.
interface ReceivedSnapshotListener {
  DidReceiveSnapshotFile();
};

// Interface provided by the browser to the renderer to carry out filesystem
// operations. All [Sync] methods should only be called synchronously on worker
// threads (and asynchronously otherwise).
interface FileSystemManager {
  // Opens a new filesystem and returns a name and root path for the requested
  // filesystem and a success error code if the operation succeeds. If the
  // operation fails, |error_code| indicates the reason for failure.
  // TODO(https://crbug.com/873661): Make interface per frame/worker and remove
  // |origin|.
  [Sync]
  Open(url.mojom.Origin origin, blink.mojom.FileSystemType file_system_type) =>
      (string name,
       url.mojom.Url root_url,
       mojo_base.mojom.FileError error_code);

  // Resolves a filesystem URL and returns the filesystem information and
  // metadata (file path and type) if the operation is successful. |error_code|
  // indicates the reason for failure if the operation fails.
  [Sync]
  ResolveURL(url.mojom.Url filesystem_url) =>
      (FileSystemInfo info,
       mojo_base.mojom.FilePath file_path,
       bool is_directory,
       mojo_base.mojom.FileError error_code);

  // Moves a file or directory at |src_path| to |dest_path|. Returns
  // |error_code| after completion to indicate if the operation succeeded or
  // failed.
  [Sync]
  Move(url.mojom.Url src_path, url.mojom.Url dest_path) =>
      (mojo_base.mojom.FileError error_code);

  // Copies a file or directory at |src_path| to |dest_path|. Returns
  // |error_code| after completion to indicate if the operation succeeded or
  // failed.
  [Sync]
  Copy(url.mojom.Url src_path, url.mojom.Url dest_path) =>
      (mojo_base.mojom.FileError error_code);

  // Deletes a file or directory at the given |path|. To delete recursively, set
  // |recursive| to true. Returns |error_code| after completion to indicate if
  // the operation succeeded or failed.
  [Sync]
  Remove(url.mojom.Url path, bool recursive) =>
      (mojo_base.mojom.FileError error_code);

  // Retrieves the metadata information of the file or directory at the given
  // |path|. This may not always return the local platform path in remote
  // filesystem cases. Returns valid metadata if the retrieval is successful,
  // and uses |error_code| to indicate if the operation was successful.
  [Sync]
  ReadMetadata(url.mojom.Url path) =>
      (mojo_base.mojom.FileInfo file_info,
       mojo_base.mojom.FileError error_code);

  // Creates a file or directory at the given |path| (based on |is_directory|).
  // If |exclusive| is true, the operation fails if the |path| already exists.
  // Returns |error_code| after completion to indicate if the operation
  // succeeded or failed.
  [Sync]
  Create(url.mojom.Url path,
         bool exclusive,
         bool is_directory,
         bool recursive) =>
      (mojo_base.mojom.FileError error_code);

  // Checks if a file exists at the given |path| if |is_directory| is false or
  // checks if a directory exists at the given |path| otherwise. Returns
  // |error_code| to indicate if the file was successfully found or if an error
  // occurred.
  [Sync]
  Exists(url.mojom.Url path, bool is_directory) =>
      (mojo_base.mojom.FileError error_code);

  // Reads directory entries of a given directory at |path|. Calls
  // ResultsRetrieved on |listener| when results are ready, or ErrorOccurred
  // if the operation fails.
  ReadDirectory(url.mojom.Url path,
                pending_remote<FileSystemOperationListener> listener);
  [Sync]
  ReadDirectorySync(url.mojom.Url path) =>
    (array<filesystem.mojom.DirectoryEntry> entries,
     mojo_base.mojom.FileError error_code);

  // Write data (indicated by |blob|) to the given file at |file_path|,
  // at |position|. Calls DidWrite on |listener| to provide progress updates on
  // the write, and |ErrorOccurred| if the operation fails. The operation can
  // also be cancelled using the remote associated with |op_receiver|.
  Write(url.mojom.Url file_path,
        pending_remote<blink.mojom.Blob> blob,
        int64 position,
        pending_receiver<FileSystemCancellableOperation> op_receiver,
        pending_remote<FileSystemOperationListener> listener);
  [Sync]
  WriteSync(url.mojom.Url file_path, pending_remote<blink.mojom.Blob> blob, int64 position) =>
      (int64 byte_count, mojo_base.mojom.FileError error_code);

  // Changes the file length of the file at |file_path| to the |length|
  // indicated. Returns |error_code| after completion to indicate if the
  // operation succeeded or failed. The operation can also be cancelled using
  // the remote associated with |op_receiver|.
  Truncate(url.mojom.Url file_path,
           int64 length,
           pending_receiver<FileSystemCancellableOperation> op_receiver) =>
      (mojo_base.mojom.FileError error_code);
  [Sync]
  TruncateSync(url.mojom.Url file_path, int64 length) =>
      (mojo_base.mojom.FileError error_code);

  // Creates a snapshot file for a given file specified by |file_path|. Returns
  // the metadata of the created snapshot file, which also includes a local
  // platform path to the snapshot image (|platform_path|).
  //
  // In local filesystem cases the backend may simply return the metadata of the
  // file itself (exactly like ReadMetadata would), while in remote filesystem
  // cases, the backend may download the file into a temporary snapshot file and
  // return the metadata of the temporary file.
  //
  // If |snapshot_listener| is provided, the renderer is expected to call
  // DidReceiveSnapshotFile on the listener (which allows the backend to drop
  // a ref to the temporary snapshot file).
  [Sync]
  CreateSnapshotFile(url.mojom.Url file_path) =>
      (mojo_base.mojom.FileInfo file_info,
       mojo_base.mojom.FilePath platform_path,
       mojo_base.mojom.FileError error_code,
       pending_remote<ReceivedSnapshotListener>? snapshot_listener);

  // Synchronously gets the platform path for the given |file_path|.
  [Sync]
  GetPlatformPath(url.mojom.Url file_path) =>
      (mojo_base.mojom.FilePath platform_path);

  // Register a new blob and return the SerializedBlob (which is typemapped to
  // blink::BlobDataHandle). Since Blob construction is generally a synchronous
  // process even in window environments, this IPC is expected to be called
  // synchronously everywhere.
  // TODO(crbug.com/974616): Get rid of return/sync behavior after removing
  // UUIDs
  //
  // |content_type| is simply reflected back into the
  // SerializedBlob returned, and will be used in the "content-type" header if
  // the blob is fetched with a "blob:" url.
  // |url| should be a serialized "filesystem:" url that is readable by the
  // renderer. An invalid url will create a blob that will return an error any
  // time it is read from.
  // |expected_modification_time| is used to implement the snapshotting behavior
  // described in the Blob spec. If a time is provided the resulting Blob will
  // only be readable as long as the last modified timestamp of the underlying
  // file doesn't change.
  [Sync]
  RegisterBlob(string content_type,
               url.mojom.Url url,
               uint64 length,
               mojo_base.mojom.Time? expected_modification_time) =>
      (SerializedBlob blob);
};