ppapi/c/dev/ppb_testing_dev.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 dev/ppb_testing_dev.idl modified Thu Apr 18 13:22:09 2013. */
   7
   8 #ifndef PPAPI_C_DEV_PPB_TESTING_DEV_H_
   9 #define PPAPI_C_DEV_PPB_TESTING_DEV_H_
  10
  11 #include "ppapi/c/dev/ppb_url_util_dev.h"
  12 #include "ppapi/c/pp_bool.h"
  13 #include "ppapi/c/pp_instance.h"
  14 #include "ppapi/c/pp_macros.h"
  15 #include "ppapi/c/pp_point.h"
  16 #include "ppapi/c/pp_resource.h"
  17 #include "ppapi/c/pp_stdint.h"
  18 #include "ppapi/c/pp_var.h"
  19
  20 #define PPB_TESTING_DEV_INTERFACE_0_7 "PPB_Testing(Dev);0.7"
  21 #define PPB_TESTING_DEV_INTERFACE_0_8 "PPB_Testing(Dev);0.8"
  22 #define PPB_TESTING_DEV_INTERFACE_0_9 "PPB_Testing(Dev);0.9"
  23 #define PPB_TESTING_DEV_INTERFACE_0_91 "PPB_Testing(Dev);0.91"
  24 #define PPB_TESTING_DEV_INTERFACE_0_92 "PPB_Testing(Dev);0.92"
  25 #define PPB_TESTING_DEV_INTERFACE PPB_TESTING_DEV_INTERFACE_0_92
  26
  27 /**
  28  * @file
  29  * This file contains interface functions used for unit testing. Do not use in
  30  * production code. They are not guaranteed to be available in normal plugin
  31  * environments so you should not depend on them.
  32  */
  33
  34
  35 /**
  36  * @addtogroup Interfaces
  37  * @{
  38  */
  39 struct PPB_Testing_Dev_0_92 {
  40   /**
  41    * Reads the bitmap data out of the backing store for the given
  42    * DeviceContext2D and into the given image. If the data was successfully
  43    * read, it will return PP_TRUE.
  44    *
  45    * This function should not generally be necessary for normal plugin
  46    * operation. If you want to update portions of a device, the expectation is
  47    * that you will either regenerate the data, or maintain a backing store
  48    * pushing updates to the device from your backing store via PaintImageData.
  49    * Using this function will introduce an extra copy which will make your
  50    * plugin slower. In some cases, this may be a very expensive operation (it
  51    * may require slow cross-process transitions or graphics card readbacks).
  52    *
  53    * Data will be read into the image starting at |top_left| in the device
  54    * context, and proceeding down and to the right for as many pixels as the
  55    * image is large. If any part of the image bound would fall outside of the
  56    * backing store of the device if positioned at |top_left|, this function
  57    * will fail and return PP_FALSE.
  58    *
  59    * The image format must be of the format
  60    * PPB_ImageData.GetNativeImageDataFormat() or this function will fail and
  61    * return PP_FALSE.
  62    *
  63    * The returned image data will represent the current status of the backing
  64    * store. This will not include any paint, scroll, or replace operations
  65    * that have not yet been flushed; these operations are only reflected in
  66    * the backing store (and hence ReadImageData) until after a Flush()
  67    * operation has completed.
  68    */
  69   PP_Bool (*ReadImageData)(PP_Resource device_context_2d,
  70                            PP_Resource image,
  71                            const struct PP_Point* top_left);
  72   /**
  73    * Runs a nested message loop. The plugin will be reentered from this call.
  74    * This function is used for unit testing the API. The normal pattern is to
  75    * issue some asynchronous call that has a callback. Then you call
  76    * RunMessageLoop which will suspend the plugin and go back to processing
  77    * messages, giving the asynchronous operation time to complete. In your
  78    * callback, you save the data and call QuitMessageLoop, which will then
  79    * pop back up and continue with the test. This avoids having to write a
  80    * complicated state machine for simple tests for asynchronous APIs.
  81    */
  82   void (*RunMessageLoop)(PP_Instance instance);
  83   /**
  84    * Posts a quit message for the outermost nested message loop. Use this to
  85    * exit and return back to the caller after you call RunMessageLoop.
  86    */
  87   void (*QuitMessageLoop)(PP_Instance instance);
  88   /**
  89    * Returns the number of live objects (resources + strings + objects)
  90    * associated with this plugin instance. Used for detecting leaks. Returns
  91    * (uint32_t)-1 on failure.
  92    */
  93   uint32_t (*GetLiveObjectsForInstance)(PP_Instance instance);
  94   /**
  95    * Returns PP_TRUE if the plugin is running out-of-process, PP_FALSE
  96    * otherwise.
  97    */
  98   PP_Bool (*IsOutOfProcess)(void);
  99   /**
 100    * Passes the input event to the browser, which sends it back to the
 101    * plugin. The plugin should implement PPP_InputEvent and register for
 102    * the input event type.
 103    *
 104    * This method sends an input event through the browser just as if it had
 105    * come from the user. If the browser determines that it is an event for the
 106    * plugin, it will be sent to be handled by the plugin's PPP_InputEvent
 107    * interface. When generating mouse events, make sure the position is within
 108    * the plugin's area on the page. When generating a keyboard event, make sure
 109    * the plugin is focused.
 110    *
 111    * Note that the browser may generate extra input events in order to
 112    * maintain certain invariants, such as always having a "mouse enter" event
 113    * before any other mouse event. Furthermore, the event the plugin receives
 114    * after sending a simulated event will be slightly different from the
 115    * original event. The browser may change the timestamp, add modifiers, and
 116    * slightly alter the mouse position, due to coordinate transforms it
 117    * performs.
 118    */
 119   void (*SimulateInputEvent)(PP_Instance instance, PP_Resource input_event);
 120   /**
 121    * Returns the URL for the document. This is a safe way to retrieve
 122    * window.location.href.
 123    * If the canonicalized URL is valid, the method will parse the URL
 124    * and fill in the components structure. This pointer may be NULL
 125    * to specify that no component information is necessary.
 126    */
 127   struct PP_Var (*GetDocumentURL)(PP_Instance instance,
 128                                   struct PP_URLComponents_Dev* components);
 129   /**
 130    * Fetches up to |array_size| active PP_Vars in the tracker. Returns the
 131    * number of vars in the tracker. The active vars are written to |live_vars|
 132    * contiguously starting at index 0. The vars are not in any particular order.
 133    * If the number of live vars is greater than |array_size|, then an arbitrary
 134    * subset of |array_size| vars is written to |live_vars|. The reference count
 135    * of the returned PP_Vars will *not* be affected by this call.
 136    */
 137   uint32_t (*GetLiveVars)(struct PP_Var live_vars[], uint32_t array_size);
 138   /**
 139    * Sets the threshold size at which point we switch from transmitting
 140    * array buffers in IPC messages to using shared memory. This is only used
 141    * for testing purposes where we need to transmit small buffers using shmem
 142    * (in order to have fast tests). Passing a value of 0 resets the threshold
 143    * to its default. The threshold is in bytes.
 144    */
 145   void (*SetMinimumArrayBufferSizeForShmem)(PP_Instance instance,
 146                                             uint32_t threshold);
 147 };
 148
 149 typedef struct PPB_Testing_Dev_0_92 PPB_Testing_Dev;
 150
 151 struct PPB_Testing_Dev_0_7 {
 152   PP_Bool (*ReadImageData)(PP_Resource device_context_2d,
 153                            PP_Resource image,
 154                            const struct PP_Point* top_left);
 155   void (*RunMessageLoop)(PP_Instance instance);
 156   void (*QuitMessageLoop)(PP_Instance instance);
 157   uint32_t (*GetLiveObjectsForInstance)(PP_Instance instance);
 158   PP_Bool (*IsOutOfProcess)(void);
 159 };
 160
 161 struct PPB_Testing_Dev_0_8 {
 162   PP_Bool (*ReadImageData)(PP_Resource device_context_2d,
 163                            PP_Resource image,
 164                            const struct PP_Point* top_left);
 165   void (*RunMessageLoop)(PP_Instance instance);
 166   void (*QuitMessageLoop)(PP_Instance instance);
 167   uint32_t (*GetLiveObjectsForInstance)(PP_Instance instance);
 168   PP_Bool (*IsOutOfProcess)(void);
 169   void (*SimulateInputEvent)(PP_Instance instance, PP_Resource input_event);
 170 };
 171
 172 struct PPB_Testing_Dev_0_9 {
 173   PP_Bool (*ReadImageData)(PP_Resource device_context_2d,
 174                            PP_Resource image,
 175                            const struct PP_Point* top_left);
 176   void (*RunMessageLoop)(PP_Instance instance);
 177   void (*QuitMessageLoop)(PP_Instance instance);
 178   uint32_t (*GetLiveObjectsForInstance)(PP_Instance instance);
 179   PP_Bool (*IsOutOfProcess)(void);
 180   void (*SimulateInputEvent)(PP_Instance instance, PP_Resource input_event);
 181   struct PP_Var (*GetDocumentURL)(PP_Instance instance,
 182                                   struct PP_URLComponents_Dev* components);
 183 };
 184
 185 struct PPB_Testing_Dev_0_91 {
 186   PP_Bool (*ReadImageData)(PP_Resource device_context_2d,
 187                            PP_Resource image,
 188                            const struct PP_Point* top_left);
 189   void (*RunMessageLoop)(PP_Instance instance);
 190   void (*QuitMessageLoop)(PP_Instance instance);
 191   uint32_t (*GetLiveObjectsForInstance)(PP_Instance instance);
 192   PP_Bool (*IsOutOfProcess)(void);
 193   void (*SimulateInputEvent)(PP_Instance instance, PP_Resource input_event);
 194   struct PP_Var (*GetDocumentURL)(PP_Instance instance,
 195                                   struct PP_URLComponents_Dev* components);
 196   uint32_t (*GetLiveVars)(struct PP_Var live_vars[], uint32_t array_size);
 197 };
 198 /**
 199  * @}
 200  */
 201
 202 #endif  /* PPAPI_C_DEV_PPB_TESTING_DEV_H_ */
 203