ppapi/c/private/ppb_flash_clipboard.h

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