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 204