OLD | NEW |
1 /* Copyright (c) 2011 The Chromium Authors. All rights reserved. | 1 /* Copyright (c) 2011 The Chromium Authors. All rights reserved. |
2 * Use of this source code is governed by a BSD-style license that can be | 2 * Use of this source code is governed by a BSD-style license that can be |
3 * found in the LICENSE file. | 3 * found in the LICENSE file. |
4 */ | 4 */ |
5 | 5 |
6 /** | 6 /** |
7 * This file defines the <code>PPP_Instance</code> structure - a series of | 7 * This file defines the <code>PPP_Instance</code> structure - a series of |
8 * pointers to methods that you must implement in your module. | 8 * pointers to methods that you must implement in your module. |
9 */ | 9 */ |
10 | 10 |
(...skipping 21 matching lines...) Expand all Loading... |
32 * identify which instance the call pertains to. | 32 * identify which instance the call pertains to. |
33 * | 33 * |
34 * It's possible for more than one instance to be created in a single module. | 34 * It's possible for more than one instance to be created in a single module. |
35 * This means that you may get more than one <code>OnCreate</code> without an | 35 * This means that you may get more than one <code>OnCreate</code> without an |
36 * <code>OnDestroy</code> in between, and should be prepared to maintain | 36 * <code>OnDestroy</code> in between, and should be prepared to maintain |
37 * multiple states associated with each instance. | 37 * multiple states associated with each instance. |
38 * | 38 * |
39 * If this function reports a failure (by returning <code>PP_FALSE</code>), | 39 * If this function reports a failure (by returning <code>PP_FALSE</code>), |
40 * the instance will be deleted. | 40 * the instance will be deleted. |
41 * | 41 * |
42 * @param[in] instance A new <code>PP_Instance</code> indentifying one | 42 * @param[in] instance A new <code>PP_Instance</code> identifying one |
43 * instance of a module. This is an opaque handle. | 43 * instance of a module. This is an opaque handle. |
44 * | 44 * |
45 * @param[in] argc The number of arguments contained in <code>argn</code> | 45 * @param[in] argc The number of arguments contained in <code>argn</code> |
46 * and <code>argv</code>. | 46 * and <code>argv</code>. |
47 * | 47 * |
48 * @param[in] argn An array of argument names. These argument names are | 48 * @param[in] argn An array of argument names. These argument names are |
49 * supplied in the \<embed\> tag, for example: | 49 * supplied in the \<embed\> tag, for example: |
50 * <code>\<embed id="nacl_module" dimensions="2"\></code> will produce two | 50 * <code>\<embed id="nacl_module" dimensions="2"\></code> will produce two |
51 * argument names: "id" and "dimensions." | 51 * argument names: "id" and "dimensions." |
52 * | 52 * |
53 * @param[in] argv An array of argument values. These are the values of the | 53 * @param[in] argv An array of argument values. These are the values of the |
54 * arguments listed in the \<embed\> tag, for example | 54 * arguments listed in the \<embed\> tag, for example |
55 * <code>\<embed id="nacl_module" dimensions="2"\></code> will produce two | 55 * <code>\<embed id="nacl_module" dimensions="2"\></code> will produce two |
56 * argument values: "nacl_module" and "2". The indices of these values match | 56 * argument values: "nacl_module" and "2". The indices of these values match |
57 * the indices of the corresponding names in <code>argn</code>. | 57 * the indices of the corresponding names in <code>argn</code>. |
58 * | 58 * |
59 * @return <code>PP_TRUE</code> on success or <code>PP_FALSE</code> on | 59 * @return <code>PP_TRUE</code> on success or <code>PP_FALSE</code> on |
60 * failure. | 60 * failure. |
61 */ | 61 */ |
62 PP_Bool DidCreate( | 62 PP_Bool DidCreate( |
63 /* A PP_Instance indentifying one instance of a module. */ | 63 /* A PP_Instance identifying one instance of a module. */ |
64 [in] PP_Instance instance, | 64 [in] PP_Instance instance, |
65 /* The number of arguments contained in argn and argv. */ | 65 /* The number of arguments contained in argn and argv. */ |
66 [in] uint32_t argc, | 66 [in] uint32_t argc, |
67 /* An array of argument names. These argument names are | 67 /* An array of argument names. These argument names are |
68 * supplied in the <embed> tag, for example: | 68 * supplied in the <embed> tag, for example: |
69 * <embed id="nacl_module" dimensions="2"> will produce two argument | 69 * <embed id="nacl_module" dimensions="2"> will produce two argument |
70 * names: "id" and "dimensions." | 70 * names: "id" and "dimensions." |
71 */ | 71 */ |
72 [in, size_as=argc] str_t[] argn, | 72 [in, size_as=argc] str_t[] argn, |
73 /* An array of argument values. These are the values of the | 73 /* An array of argument values. These are the values of the |
(...skipping 21 matching lines...) Expand all Loading... |
95 * do any asynchronous operations like network requests, file writes or | 95 * do any asynchronous operations like network requests, file writes or |
96 * messaging from this function since they will be immediately canceled. | 96 * messaging from this function since they will be immediately canceled. |
97 * | 97 * |
98 * <strong>Note:</strong> This function will always be skipped on untrusted | 98 * <strong>Note:</strong> This function will always be skipped on untrusted |
99 * (Native Client) implementations. This function may be skipped on trusted | 99 * (Native Client) implementations. This function may be skipped on trusted |
100 * implementations in certain circumstances when Chrome does "fast shutdown" | 100 * implementations in certain circumstances when Chrome does "fast shutdown" |
101 * of a web page. Fast shutdown will happen in some cases when all module | 101 * of a web page. Fast shutdown will happen in some cases when all module |
102 * instances are being deleted, and no cleanup functions will be called. | 102 * instances are being deleted, and no cleanup functions will be called. |
103 * The module will just be unloaded and the process terminated. | 103 * The module will just be unloaded and the process terminated. |
104 * | 104 * |
105 * @param[in] instance A <code>PP_Instance</code> indentifying one instance | 105 * @param[in] instance A <code>PP_Instance</code> identifying one instance |
106 * of a module. | 106 * of a module. |
107 */ | 107 */ |
108 void DidDestroy( | 108 void DidDestroy( |
109 /* A PP_Instance indentifying one instance of a module. */ | 109 /* A PP_Instance identifying one instance of a module. */ |
110 [in] PP_Instance instance); | 110 [in] PP_Instance instance); |
111 | 111 |
112 /** | 112 /** |
113 * DidChangeView() is called when the position, the size, of the clip | 113 * DidChangeView() is called when the position, the size, of the clip |
114 * rectangle of the element in the browser that corresponds to this | 114 * rectangle of the element in the browser that corresponds to this |
115 * instance has changed. | 115 * instance has changed. |
116 * | 116 * |
117 * A typical implementation will check the size of the <code>position</code> | 117 * A typical implementation will check the size of the <code>position</code> |
118 * argument and reallocate the graphics context when a different size is | 118 * argument and reallocate the graphics context when a different size is |
119 * received. Note that this function will be called for scroll events where | 119 * received. Note that this function will be called for scroll events where |
120 * the size doesn't change, so you should always check that the size is | 120 * the size doesn't change, so you should always check that the size is |
121 * actually different before doing any reallocations. | 121 * actually different before doing any reallocations. |
122 * | 122 * |
123 * @param[in] instance A <code>PP_Instance</code> indentifying the instance | 123 * @param[in] instance A <code>PP_Instance</code> identifying the instance |
124 * that has changed. | 124 * that has changed. |
125 * | 125 * |
126 * @param[in] position The location on the page of the instance. This is | 126 * @param[in] position The location on the page of the instance. This is |
127 * relative to the top left corner of the viewport, which changes as the | 127 * relative to the top left corner of the viewport, which changes as the |
128 * page is scrolled. Generally the size of this value will be used to create | 128 * page is scrolled. Generally the size of this value will be used to create |
129 * a graphics device, and the position is ignored (most things are relative | 129 * a graphics device, and the position is ignored (most things are relative |
130 * to the instance so the absolute position isn't useful in most cases). | 130 * to the instance so the absolute position isn't useful in most cases). |
131 * | 131 * |
132 * @param[in] clip The visible region of the instance. This is relative to | 132 * @param[in] clip The visible region of the instance. This is relative to |
133 * the top left of the module's coordinate system (not the page). If the | 133 * the top left of the module's coordinate system (not the page). If the |
134 * module is invisible, <code>clip</code> will be (0, 0, 0, 0). | 134 * module is invisible, <code>clip</code> will be (0, 0, 0, 0). |
135 * | 135 * |
136 * It's recommended to check for invisible instances and to stop | 136 * It's recommended to check for invisible instances and to stop |
137 * generating graphics updates in this case to save system resources. It's | 137 * generating graphics updates in this case to save system resources. It's |
138 * not usually worthwhile, however, to generate partial updates according to | 138 * not usually worthwhile, however, to generate partial updates according to |
139 * the clip when the instance is partially visible. Instead, update the entire | 139 * the clip when the instance is partially visible. Instead, update the entire |
140 * region. The time saved doing partial paints is usually not significant and | 140 * region. The time saved doing partial paints is usually not significant and |
141 * it can create artifacts when scrolling (this notification is sent | 141 * it can create artifacts when scrolling (this notification is sent |
142 * asynchronously from scolling so there can be flashes of old content in the | 142 * asynchronously from scrolling so there can be flashes of old content in the |
143 * exposed regions). | 143 * exposed regions). |
144 */ | 144 */ |
145 void DidChangeView( | 145 void DidChangeView( |
146 /* A PP_Instance indentifying the instance whose view changed. */ | 146 /* A PP_Instance identifying the instance whose view changed. */ |
147 [in] PP_Instance instance, | 147 [in] PP_Instance instance, |
148 /* The new location on the page of this instance. This is relative to | 148 /* The new location on the page of this instance. This is relative to |
149 * the top left corner of the viewport, which changes as the | 149 * the top left corner of the viewport, which changes as the |
150 * page is scrolled. | 150 * page is scrolled. |
151 */ | 151 */ |
152 [in] PP_Rect position, | 152 [in] PP_Rect position, |
153 /* The visible region of the NaCl module. This is relative to the top | 153 /* The visible region of the NaCl module. This is relative to the top |
154 * left of the plugin's coordinate system (not the page) If the plugin | 154 * left of the plugin's coordinate system (not the page) If the plugin |
155 * is invisible, clip will be (0, 0, 0, 0). | 155 * is invisible, clip will be (0, 0, 0, 0). |
156 */ | 156 */ |
157 [in] PP_Rect clip); | 157 [in] PP_Rect clip); |
158 | 158 |
159 /** | 159 /** |
160 * DidChangeFocus() is called when an instance has gained or lost focus. | 160 * DidChangeFocus() is called when an instance has gained or lost focus. |
161 * Having focus means that keyboard events will be sent to the instance. | 161 * Having focus means that keyboard events will be sent to the instance. |
162 * An instance's default condition is that it will not have focus. | 162 * An instance's default condition is that it will not have focus. |
163 * | 163 * |
164 * <strong>Note:</strong>Clicks on instances will give focus only if you | 164 * <strong>Note:</strong>Clicks on instances will give focus only if you |
165 * handle the click event. Return <code>true</code> from | 165 * handle the click event. Return <code>true</code> from |
166 * <code>HandleInputEvent</code> in <code>PPP_InputEvent</code> (or use | 166 * <code>HandleInputEvent</code> in <code>PPP_InputEvent</code> (or use |
167 * unfiltered events) to signal that the click event was handled. Otherwise, | 167 * unfiltered events) to signal that the click event was handled. Otherwise, |
168 * the browser will bubble the event and give focus to the element on the page | 168 * the browser will bubble the event and give focus to the element on the page |
169 * that actually did end up consuming it. If you're not getting focus, check | 169 * that actually did end up consuming it. If you're not getting focus, check |
170 * to make sure you're returning true from the mouse click in | 170 * to make sure you're returning true from the mouse click in |
171 * <code>HandleInputEvent</code>. | 171 * <code>HandleInputEvent</code>. |
172 * | 172 * |
173 * @param[in] instance A <code>PP_Instance</code> indentifying the instance | 173 * @param[in] instance A <code>PP_Instance</code> identifying the instance |
174 * receiving the input event. | 174 * receiving the input event. |
175 * | 175 * |
176 * @param[in] has_focus Indicates the new focused state of the instance. | 176 * @param[in] has_focus Indicates the new focused state of the instance. |
177 */ | 177 */ |
178 void DidChangeFocus( | 178 void DidChangeFocus( |
179 /* A PP_Instance indentifying one instance of a module. */ | 179 /* A PP_Instance identifying one instance of a module. */ |
180 [in] PP_Instance instance, | 180 [in] PP_Instance instance, |
181 /* Indicates whether this NaCl module gained or lost event focus. */ | 181 /* Indicates whether this NaCl module gained or lost event focus. */ |
182 [in] PP_Bool has_focus); | 182 [in] PP_Bool has_focus); |
183 | 183 |
184 /** | 184 /** |
185 * HandleDocumentLoad() is called after initialize for a full-frame | 185 * HandleDocumentLoad() is called after initialize for a full-frame |
186 * module that was instantiated based on the MIME type of a DOMWindow | 186 * module that was instantiated based on the MIME type of a DOMWindow |
187 * navigation. This situation only applies to modules that are pre-registered | 187 * navigation. This situation only applies to modules that are pre-registered |
188 * to handle certain MIME types. If you haven't specifically registered to | 188 * to handle certain MIME types. If you haven't specifically registered to |
189 * handle a MIME type or aren't positive this applies to you, your | 189 * handle a MIME type or aren't positive this applies to you, your |
190 * implementation of this function can just return <code>PP_FALSE</code>. | 190 * implementation of this function can just return <code>PP_FALSE</code>. |
191 * | 191 * |
192 * The given <code>url_loader</code> corresponds to a | 192 * The given <code>url_loader</code> corresponds to a |
193 * <code>PPB_URLLoader</code> instance that is already opened. Its response | 193 * <code>PPB_URLLoader</code> instance that is already opened. Its response |
194 * headers may be queried using <code>PPB_URLLoader::GetResponseInfo</code>. | 194 * headers may be queried using <code>PPB_URLLoader::GetResponseInfo</code>. |
195 * The reference count for the URL loader is not incremented automatically on | 195 * The reference count for the URL loader is not incremented automatically on |
196 * behalf of the module. You need to increment the reference count yourself | 196 * behalf of the module. You need to increment the reference count yourself |
197 * if you are going to keep a reference to it. | 197 * if you are going to keep a reference to it. |
198 * | 198 * |
199 * This method returns <code>PP_FALSE</code> if the module cannot handle the | 199 * This method returns <code>PP_FALSE</code> if the module cannot handle the |
200 * data. In response to this method, the module should call | 200 * data. In response to this method, the module should call |
201 * ReadResponseBody() to read the incoming data. | 201 * ReadResponseBody() to read the incoming data. |
202 * | 202 * |
203 * @param[in] instance A <code>PP_Instance</code> indentifying the instance | 203 * @param[in] instance A <code>PP_Instance</code> identifying the instance |
204 * that should do the load. | 204 * that should do the load. |
205 * | 205 * |
206 * @param[in] url_loader An open <code>PPB_URLLoader</code> instance. | 206 * @param[in] url_loader An open <code>PPB_URLLoader</code> instance. |
207 * | 207 * |
208 * @return <code>PP_TRUE</code> if the data was handled, | 208 * @return <code>PP_TRUE</code> if the data was handled, |
209 * <code>PP_FALSE</code> otherwise. | 209 * <code>PP_FALSE</code> otherwise. |
210 */ | 210 */ |
211 PP_Bool HandleDocumentLoad( | 211 PP_Bool HandleDocumentLoad( |
212 /* A PP_Instance indentifying one instance of a module. */ | 212 /* A PP_Instance identifying one instance of a module. */ |
213 [in] PP_Instance instance, | 213 [in] PP_Instance instance, |
214 /* A PP_Resource an open PPB_URLLoader instance. */ | 214 /* A PP_Resource an open PPB_URLLoader instance. */ |
215 [in] PP_Resource url_loader); | 215 [in] PP_Resource url_loader); |
216 | 216 |
217 }; | 217 }; |
218 | 218 |
219 #inline c | 219 #inline c |
220 | 220 |
221 typedef struct PPP_Instance PPP_Instance_1_0; | 221 typedef struct PPP_Instance PPP_Instance_1_0; |
222 | 222 |
223 #endinl | 223 #endinl |
224 | 224 |
OLD | NEW |