third_party/blink/public/mojom/choosers/file_chooser.mojom

// Copyright 2018 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 "mojo/public/mojom/base/file_path.mojom";
import "mojo/public/mojom/base/string16.mojom";
import "mojo/public/mojom/base/time.mojom";
import "url/mojom/url.mojom";

// FileChooserParams stores arguments for an operation to open a file
// chooser dialog.
struct FileChooserParams {
  enum Mode {
    // Requires that the file exists before allowing the user to pick it.
    kOpen,

    // Like Open, but allows picking multiple files to open.
    kOpenMultiple,

    // Like Open, but selects a folder for upload.  This mode returns multiple
    // FileChooserFileInfo objects for descendant files, rather than a single
    // FileChooserFileInfo for the selected directory.
    kUploadFolder,

    // Allows picking a nonexistent file, and prompts to overwrite if the file
    // already exists. This is not for Blink but for PPAPI.
    kSave,
  };
  Mode mode = kOpen;

  // Title to be used for the dialog. This may be empty for the default title,
  // which will be either "Open" or "Save" depending on the mode.
  mojo_base.mojom.String16 title;

  // Default file name to select in the dialog with kSave mode.
  mojo_base.mojom.FilePath default_file_name;

  // |selected_files| has filenames which a file upload control already
  // selected. A FileChooser implementation may ask a user to select
  //  - removing a file from the selected files,
  //  - appending other files, or
  //  - replacing with other files
  // before opening a file chooser dialog.
  array<mojo_base.mojom.FilePath> selected_files;

  // A list of valid lower-cased MIME types or file extensions specified
  // in an |accept| attribute of an input element, such as "audio/*",
  // "text/plain", ".mp3" ".txt". It is used to restrict selectable
  // files to such types.
  array<mojo_base.mojom.String16> accept_types;

  // Whether the caller needs native file path or not.
  // This may be false if the callsite can handle |file_system_url| field of
  // resultant FileChooserFileInfo objects.
  bool need_local_path = true;

  // See http://www.w3.org/TR/html-media-capture for more information.
  // If true, the data should be obtained using the device's camera/mic/etc.
  bool use_media_capture = false;

  // If non-empty, represents the URL of the requestor if the request was
  // initiated by a document. Note that this value should be considered
  // untrustworthy since it is specified by the sandbox and not validated.
  url.mojom.Url requestor;
};

struct NativeFileInfo {
  mojo_base.mojom.FilePath file_path;

  // The display name of the file that is to be exposed as File.name in the
  // DOM layer.  If it is empty, the base part of the |file_path| is used.
  mojo_base.mojom.String16 display_name;
};

struct FileSystemFileInfo {
  url.mojom.Url url;
  mojo_base.mojom.Time modification_time;
  int64 length = 0;
};

// Represents a file selected by a user.
union FileChooserFileInfo {
  NativeFileInfo native_file;
  FileSystemFileInfo file_system;
};

// Represents the result of FileChooser::OpenFileChooser() or
// EnumerateChosenDirectory().
struct FileChooserResult {
  // Selected files.
  array<FileChooserFileInfo> files;

  // Requested base directory.
  // This is a user-chosen path in a case of OpenFileChooser() with
  // mode=kUploadFolder.
  // This is |directory_path| in a case of EnumerateChosenDirectory().
  // Otherwise, it's an empty FilePath.
  mojo_base.mojom.FilePath base_directory;
};

// An interface to receive file chooser requests.
interface FileChooser {
  // Ask a user to choose files interactively.  Null |result| is returned if the
  // user canceled a dialog, or the request is not accepted.
  OpenFileChooser(FileChooserParams params) => (FileChooserResult? result);

  // Ask to enumerate files which are descendants of the specified directory.
  // Null |result| is returned if the enumeration request is not accepted.
  EnumerateChosenDirectory(mojo_base.mojom.FilePath directory_path)
       => (FileChooserResult? result);
};