chromium/src/third_party/blink/public/mojom/file_system_access/file_system_access_directory_handle.mojom

// Copyright 2019 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.

module blink.mojom;

import "third_party/blink/public/mojom/file_system_access/file_system_access_file_handle.mojom";
import "third_party/blink/public/mojom/file_system_access/file_system_access_error.mojom";
import "third_party/blink/public/mojom/file_system_access/file_system_access_transfer_token.mojom";
import "third_party/blink/public/mojom/permissions/permission_status.mojom";

// Union representing either a file or a directory handle. Used in APIs that
// can return arbitrary handles.
union FileSystemAccessHandle {
  pending_remote<FileSystemAccessFileHandle> file;
  pending_remote<FileSystemAccessDirectoryHandle> directory;
};

struct FileSystemAccessEntry {
  FileSystemAccessHandle entry_handle;
  string name;
};

interface FileSystemAccessDirectoryEntriesListener {
  // Called by FileSystemAccessDirectoryHandle.GetEntries when some entries
  // have been obtained. |has_more_entries| is false when all the entries have
  // been obtained, and  indicates that the callback will not be called again.
  DidReadDirectory(FileSystemAccessError result,
                   array<FileSystemAccessEntry> entries,
                   bool has_more_entries);
};

// This interface represents a handle to a directory in the File System Access
// API.
//
// TODO(mek): Using something similar to (but probably not the same as)
// mojo_base.mojom.Basename (https://crbug.com/779196) to represent names of
// children could help us defend against directory traversal bugs at the IPC
// layer (not the same type though because of https://crbug.com/956231 and the
// fact that our paths really aren't base::FilePath, but instead are virtual
// paths).
interface FileSystemAccessDirectoryHandle {
  // Queries the current permission status for this handle.
  GetPermissionStatus(bool writable) => (PermissionStatus status);

  // Requests read and/or write permission for this handle. Returns the new
  // permission status for this handle.
  RequestPermission(bool writable) => (FileSystemAccessError result, PermissionStatus status);

  // Returns a file with the given |basename| that is a child of this
  // directory. If no such file exists, and |create| is true, the file is first
  // created. Returns an error if the operation fails, or a handle to the newly
  // created file if the operation succeeds.
  GetFile(string basename, bool create) =>
      (FileSystemAccessError result, pending_remote<FileSystemAccessFileHandle>? file);

  // Returns a directory with the given |basename| that is a child of this
  // directory. If no such directory exists, and |create| is true, the directory
  // is first created.
  // Returns an error if the operation fails, or a handle to the newly created
  // directory if the operation succeeds.
  GetDirectory(string basename, bool create) =>
      (FileSystemAccessError result,
       pending_remote<FileSystemAccessDirectoryHandle>? directory);

  // Returns all the direct children of this directory.
  GetEntries(pending_remote<FileSystemAccessDirectoryEntriesListener> listener);

  // Deletes an entry which is a child of this directory.
  // To delete recursively, set |recurse| to true.
  RemoveEntry(string basename, bool recurse) => (FileSystemAccessError result);

  // If |possible_child| is not a descendant of this directory, |path| will be
  // null. If |possible_child| is equal to this directory, |path| will be an
  // empty array. And if |possible_child| is a descendant of this directory,
  // |path| will contain the path components making up the path of
  // |possible_child| relative to this directory.
  Resolve(pending_remote<FileSystemAccessTransferToken> possible_child) =>
      (FileSystemAccessError result, array<string>? path);

  // Create a TransferToken for this directory. This token can be used to pass
  // a reference to this directory to other methods, for example to copy or move
  // the directory, or when transferring the handle over postMessage.
  Transfer(pending_receiver<FileSystemAccessTransferToken> token);
};