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