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