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 }; 143
