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