1// Copyright 2019 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
5module blink.mojom;
6
7import "third_party/blink/public/mojom/file_system_access/native_file_system_file_handle.mojom";
8import "third_party/blink/public/mojom/file_system_access/native_file_system_error.mojom";
9import "third_party/blink/public/mojom/file_system_access/native_file_system_transfer_token.mojom";
10import "third_party/blink/public/mojom/permissions/permission_status.mojom";
11
12// Union representing either a file or a directory handle. Used in APIs that
13// can return arbitrary handles.
14union NativeFileSystemHandle {
15  pending_remote<NativeFileSystemFileHandle> file;
16  pending_remote<NativeFileSystemDirectoryHandle> directory;
17};
18
19struct NativeFileSystemEntry {
20  NativeFileSystemHandle entry_handle;
21  string name;
22};
23
24interface NativeFileSystemDirectoryEntriesListener {
25  // Called by NativeFileSystemDirectoryHandle.GetEntries when some entries
26  // have been obtained. |has_more_entries| is false when all the entries have
27  // been obtained, and  indicates that the callback will not be called again.
28  DidReadDirectory(NativeFileSystemError result,
29                   array<NativeFileSystemEntry> entries,
30                   bool has_more_entries);
31};
32
33// This interface represents a handle to a directory in the Native File System
34// API.
35//
36// TODO(mek): Using something similar to (but probably not the same as)
37// mojo_base.mojom.Basename (https://crbug.com/779196) to represent names of
38// children could help us defend against directory traversal bugs at the IPC
39// layer (not the same type though because of https://crbug.com/956231 and the
40// fact that our paths really aren't base::FilePath, but instead are virtual
41// paths).
42interface NativeFileSystemDirectoryHandle {
43  // Queries the current permission status for this handle.
44  GetPermissionStatus(bool writable) => (PermissionStatus status);
45
46  // Requests read and/or write permission for this handle. Returns the new
47  // permission status for this handle.
48  RequestPermission(bool writable) => (NativeFileSystemError result, PermissionStatus status);
49
50  // Returns a file with the given |basename| that is a child of this
51  // directory. If no such file exists, and |create| is true, the file is first
52  // created. Returns an error if the operation fails, or a handle to the newly
53  // created file if the operation succeeds.
54  GetFile(string basename, bool create) =>
55      (NativeFileSystemError result, pending_remote<NativeFileSystemFileHandle>? file);
56
57  // Returns a directory with the given |basename| that is a child of this
58  // directory. If no such directory exists, and |create| is true, the directory
59  // is first created.
60  // Returns an error if the operation fails, or a handle to the newly created
61  // directory if the operation succeeds.
62  GetDirectory(string basename, bool create) =>
63      (NativeFileSystemError result,
64       pending_remote<NativeFileSystemDirectoryHandle>? directory);
65
66  // Returns all the direct children of this directory.
67  GetEntries(pending_remote<NativeFileSystemDirectoryEntriesListener> listener);
68
69  // Deletes an entry which is a child of this directory.
70  // To delete recursively, set |recurse| to true.
71  RemoveEntry(string basename, bool recurse) => (NativeFileSystemError result);
72
73  // If |possible_child| is not a descendant of this directory, |path| will be
74  // null. If |possible_child| is equal to this directory, |path| will be an
75  // empty array. And if |possible_child| is a descendant of this directory,
76  // |path| will contain the path components making up the path of
77  // |possible_child| relative to this directory.
78  Resolve(pending_remote<NativeFileSystemTransferToken> possible_child) =>
79      (NativeFileSystemError result, array<string>? path);
80
81  // Create a TransferToken for this directory. This token can be used to pass
82  // a reference to this directory to other methods, for example to copy or move
83  // the directory, or when transferring the handle over postMessage.
84  Transfer(pending_receiver<NativeFileSystemTransferToken> token);
85};
86