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    * Passes the input event to the browser, which sends it back to the
97    * plugin. The plugin should implement PPP_InputEvent and register for
98    * the input event type.
99    *
100    * This method sends an input event through the browser just as if it had
101    * come from the user. If the browser determines that it is an event for the
102    * plugin, it will be sent to be handled by the plugin's PPP_InputEvent
103    * interface. When generating mouse events, make sure the position is within
104    * the plugin's area on the page. When generating a keyboard event, make sure
105    * the plugin is focused.
106    *
107    * Note that the browser may generate extra input events in order to
108    * maintain certain invariants, such as always having a "mouse enter" event
109    * before any other mouse event. Furthermore, the event the plugin receives
110    * after sending a simulated event will be slightly different from the
111    * original event. The browser may change the timestamp, add modifiers, and
112    * slightly alter the mouse position, due to coordinate transforms it
113    * performs.
114    */
115   void (*SimulateInputEvent)(PP_Instance instance, PP_Resource input_event);
116   /**
117    * Returns the URL for the document. This is a safe way to retrieve
118    * window.location.href.
119    * If the canonicalized URL is valid, the method will parse the URL
120    * and fill in the components structure. This pointer may be NULL
121    * to specify that no component information is necessary.
122    */
123   struct PP_Var (*GetDocumentURL)(PP_Instance instance,
124                                   struct PP_URLComponents_Dev* components);
125   /**
126    * Fetches up to |array_size| active PP_Vars in the tracker. Returns the
127    * number of vars in the tracker. The active vars are written to |live_vars|
128    * contiguously starting at index 0. The vars are not in any particular order.
129    * If the number of live vars is greater than |array_size|, then an arbitrary
130    * subset of |array_size| vars is written to |live_vars|. The reference count
131    * of the returned PP_Vars will *not* be affected by this call.
132    */
133   uint32_t (*GetLiveVars)(struct PP_Var live_vars[], uint32_t array_size);
134   /**
135    * Sets the threshold size at which point we switch from transmitting
136    * array buffers in IPC messages to using shared memory. This is only used
137    * for testing purposes where we need to transmit small buffers using shmem
138    * (in order to have fast tests). Passing a value of 0 resets the threshold
139    * to its default. The threshold is in bytes.
140    */
141   void (*SetMinimumArrayBufferSizeForShmem)(PP_Instance instance,
142                                             uint32_t threshold);
143   /**
144    * Run the V8 garbage collector for tests.
145    */
146   void (*RunV8GC)(PP_Instance instance);
147 };
148 
149 typedef struct PPB_Testing_Private_1_0 PPB_Testing_Private;
150 /**
151  * @}
152  */
153 
154 #endif  /* PPAPI_C_PRIVATE_PPB_TESTING_PRIVATE_H_ */
155 
156