chromium/src/third_party/blink/public/mojom/clipboard/clipboard.mojom

// Copyright 2017 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/string16.mojom";
import "mojo/public/mojom/base/big_buffer.mojom";
import "mojo/public/mojom/base/big_string.mojom";
import "skia/public/mojom/bitmap.mojom";
import "third_party/blink/public/mojom/data_transfer/data_transfer.mojom";
import "url/mojom/url.mojom";

enum ClipboardFormat {
  kPlaintext,
  kHtml,
  kSmartPaste,
  kBookmark,
};

enum ClipboardBuffer {
  kStandard,
  // Used on platforms like the X Window System that treat selection
  // as a type of clipboard.
  // TODO(crbug.com/676224): When preprocessing of mojom is available only
  // define this value for USE_X11.
  kSelection,
};

struct ClipboardFiles {
  // Files on the system clipboard.
  array<DataTransferFile> files;
  // Isolated file system ID for the files.
  string? file_system_id;
};

// Allows communication with the system clipboard.
// Individual operations are atomic, but successive operations are not.
// Therefore, it's possible that one may see text available from
// ReadAvailableTypes(), but that a subsequent ReadText() may then fail.
interface ClipboardHost {
  [Sync]
  GetSequenceNumber(ClipboardBuffer buffer) => (uint64 result);

  [Sync]
  IsFormatAvailable(ClipboardFormat format,
                    ClipboardBuffer buffer) => (bool result);

  // Reads sanitized platform-neutral types.
  [Sync]
  ReadAvailableTypes(ClipboardBuffer buffer) =>
      (array<mojo_base.mojom.String16> types);

  [Sync]
  ReadText(ClipboardBuffer buffer) => (mojo_base.mojom.BigString16 result);

  [Sync]
  ReadHtml(ClipboardBuffer buffer) => (mojo_base.mojom.BigString16 markup,
                                      url.mojom.Url url,
                                      uint32 fragment_start,
                                      uint32 fragment_end);

  // Read SVG from the OS clipboard.
  ReadSvg(ClipboardBuffer buffer) => (mojo_base.mojom.BigString16 result);

  [Sync]
  ReadRtf(ClipboardBuffer buffer) => (mojo_base.mojom.BigString result);

  [Sync]
  ReadImage(ClipboardBuffer buffer) => (skia.mojom.BitmapN32? image);

  // Read Files from clipboard. Called on paste event to provide
  // clipboardData.files.
  // Security notes:
  // 1. This function must only be used with user activation, similar to drag
  //    and drop.
  // 2. We do not allow/implement WriteFiles(). Any such future function must
  //    ensure that renderers cannot place arbitrary paths on the clipboard,
  //    and then read them via ReadFiles().
  [Sync]
  ReadFiles(ClipboardBuffer buffer) => (ClipboardFiles result);

  [Sync]
  ReadCustomData(ClipboardBuffer buffer, mojo_base.mojom.String16 type) =>
      (mojo_base.mojom.BigString16 result);

  // Writing to the clipboard via mojo is a two-phase operation. First, the
  // sender sends the different types of data it'd like to write to the
  // receiver. Then, it sends a commit message to commit the data to the system
  // clipboard.
  WriteText(mojo_base.mojom.BigString16 text);

  WriteHtml(mojo_base.mojom.BigString16 markup, url.mojom.Url url);

  // Takes sanitized SVG in a UTF16 string format and writes it to the
  // OS clipboard.
  WriteSvg(mojo_base.mojom.BigString16 markup);

  WriteSmartPasteMarker();

  // Chrome-specific pickled data.
  WriteCustomData(map<mojo_base.mojom.String16, mojo_base.mojom.BigString16> data);

  // TODO(dcheng): The |url| parameter should really be a GURL, but <canvas>'s
  // copy as image tries to set very long data: URLs on the clipboard. Using
  // GURL causes the browser to kill the renderer for sending a bad IPC (GURLs
  // bigger than 2 megabytes are considered to be bad). https://crbug.com/459822
  WriteBookmark(string url,
                mojo_base.mojom.String16 title);

  WriteImage(skia.mojom.BitmapN32 image);

  CommitWrite();

  [EnableIf=is_mac]
  WriteStringToFindPboard(mojo_base.mojom.String16 text);
};