ppapi/api/private/ppb_flash_clipboard.idl

   1 /* Copyright (c) 2012 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  */
   5
   6 /**
   7  * This file defines the private <code>PPB_Flash_Clipboard</code> API used by
   8  * Pepper Flash for reading and writing to the clipboard.
   9  */
  10
  11 label Chrome {
  12   M19 = 4.0,
  13   M24 = 5.0,
  14   M34 = 5.1
  15 };
  16
  17 /**
  18  * This enumeration contains the types of clipboards that can be accessed.
  19  * These types correspond to clipboard types in WebKit.
  20  */
  21 [assert_size(4)]
  22 enum PP_Flash_Clipboard_Type {
  23   /** The standard clipboard. */
  24   PP_FLASH_CLIPBOARD_TYPE_STANDARD = 0,
  25   /** The selection clipboard (e.g., on Linux). */
  26   PP_FLASH_CLIPBOARD_TYPE_SELECTION = 1
  27 };
  28
  29 /**
  30  * This enumeration contains the predefined clipboard data formats.
  31  */
  32 [assert_size(4)]
  33 enum PP_Flash_Clipboard_Format {
  34   /** Indicates an invalid or unsupported clipboard data format. */
  35   PP_FLASH_CLIPBOARD_FORMAT_INVALID = 0,
  36   /**
  37    * Indicates plaintext clipboard data. The format expected/returned is a
  38    * <code>PP_VARTYPE_STRING</code>.
  39    */
  40   PP_FLASH_CLIPBOARD_FORMAT_PLAINTEXT = 1,
  41   /**
  42    * Indicates HTML clipboard data. The format expected/returned is a
  43    * <code>PP_VARTYPE_STRING</code>.
  44    */
  45   PP_FLASH_CLIPBOARD_FORMAT_HTML = 2,
  46   /**
  47    * Indicates RTF clipboard data. The format expected/returned is a
  48    * <code>PP_VARTYPE_ARRAY_BUFFER</code>.
  49    */
  50   PP_FLASH_CLIPBOARD_FORMAT_RTF = 3
  51 };
  52
  53 /**
  54  * The <code>PPB_Flash_Clipboard</code> interface contains pointers to functions
  55  * used by Pepper Flash to access the clipboard.
  56  *
  57  */
  58 interface PPB_Flash_Clipboard {
  59   /**
  60    * Deprecated in 5.0.
  61    */
  62   [version=4.0, deprecate=5.0]
  63   PP_Bool IsFormatAvailable(
  64       [in] PP_Instance instance_id,
  65       [in] PP_Flash_Clipboard_Type clipboard_type,
  66       [in] PP_Flash_Clipboard_Format format);
  67
  68   /**
  69    * Deprecated in 5.0.
  70    */
  71   [version=4.0, deprecate=5.0]
  72   PP_Var ReadData([in] PP_Instance instance_id,
  73       [in] PP_Flash_Clipboard_Type clipboard_type,
  74       [in] PP_Flash_Clipboard_Format format);
  75
  76   /**
  77    * Deprecated in 5.0.
  78    */
  79   [version=4.0, deprecate=5.0]
  80   int32_t WriteData([in] PP_Instance instance_id,
  81       [in] PP_Flash_Clipboard_Type clipboard_type,
  82       [in] uint32_t data_item_count,
  83       [in, size_is(data_item_count)] PP_Flash_Clipboard_Format[] formats,
  84       [in, size_is(data_item_count)] PP_Var[] data_items);
  85
  86   /**
  87    * Registers a custom clipboard format. The format is identified by a
  88    * string. An id identifying the format will be returned if the format is
  89    * successfully registered, which can be used to read/write data of that
  90    * format. If the format has already been registered, the id associated with
  91    * that format will be returned. If the format fails to be registered
  92    * <code>PP_FLASH_CLIPBOARD_FORMAT_INVALID</code> will be returned.
  93    *
  94    * All custom data should be read/written as <code>PP_Var</code> array
  95    * buffers. The clipboard format is pepper-specific meaning that although the
  96    * data will be stored on the system clipboard, it can only be accessed in a
  97    * sensible way by using the pepper API. Data stored in custom formats can
  98    * be safely shared between different applications that use pepper.
  99    */
 100   [version=5.0]
 101   uint32_t RegisterCustomFormat(
 102       [in] PP_Instance instance_id,
 103       [in] str_t format_name);
 104
 105   /**
 106    * Checks whether a given data format is available from the given clipboard.
 107    * Returns true if the given format is available from the given clipboard.
 108    */
 109   [version=5.0]
 110   PP_Bool IsFormatAvailable(
 111       [in] PP_Instance instance_id,
 112       [in] PP_Flash_Clipboard_Type clipboard_type,
 113       [in] uint32_t format);
 114
 115   /**
 116    * Reads data in the given <code>format</code> from the clipboard. An
 117    * undefined <code>PP_Var</code> is returned if there is an error in reading
 118    * the clipboard data and a null <code>PP_Var</code> is returned if there is
 119    * no data of the specified <code>format</code> to read.
 120    */
 121   [version=5.0]
 122   PP_Var ReadData([in] PP_Instance instance_id,
 123       [in] PP_Flash_Clipboard_Type clipboard_type,
 124       [in] uint32_t format);
 125
 126   /**
 127    * Writes the given array of data items to the clipboard. All existing
 128    * clipboard data in any format is erased before writing this data. Thus,
 129    * passing an array of size 0 has the effect of clearing the clipboard without
 130    * writing any data. Each data item in the array should have a different
 131    * <code>PP_Flash_Clipboard_Format</code>. If multiple data items have the
 132    * same format, only the last item with that format will be written.
 133    * If there is an error writing any of the items in the array to the
 134    * clipboard, none will be written and an error code is returned.
 135    * The error code will be <code>PP_ERROR_NOSPACE</code> if the value is
 136    * too large to be written, <code>PP_ERROR_BADARGUMENT</code> if a PP_Var
 137    * cannot be converted into the format supplied or <code>PP_FAILED</code>
 138    * if the format is not supported.
 139    */
 140   [version=5.0]
 141   int32_t WriteData([in] PP_Instance instance_id,
 142       [in] PP_Flash_Clipboard_Type clipboard_type,
 143       [in] uint32_t data_item_count,
 144       [in, size_is(data_item_count)] uint32_t[] formats,
 145       [in, size_is(data_item_count)] PP_Var[] data_items);
 146
 147   /**
 148    * Gets a sequence number which uniquely identifies clipboard state. This can
 149    * be used to version the data on the clipboard and determine whether it has
 150    * changed. The sequence number will be placed in |sequence_number| and
 151    * PP_TRUE returned if the sequence number was retrieved successfully.
 152    */
 153   [version=5.1]
 154   PP_Bool GetSequenceNumber([in] PP_Instance instance_id,
 155                             [in] PP_Flash_Clipboard_Type clipboard_type,
 156                             [out] uint64_t sequence_number);
 157 };