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 defines the <code>PPP_Instance</code> structure - a series of 8 * pointers to methods that you must implement in your module. 9 */ 10 11 label Chrome { 12 M14 = 1.0, 13 M17 = 1.1 14 }; 15 16 /** 17 * The <code>PPP_Instance</code> interface contains pointers to a series of 18 * functions that you must implement in your module. These functions can be 19 * trivial (simply return the default return value) unless you want your module 20 * to handle events such as change of focus or input events (keyboard/mouse) 21 * events. 22 */ 23 interface PPP_Instance { 24 /** 25 * DidCreate() is a creation handler that is called when a new instance is 26 * created. This function is called for each instantiation on the page, 27 * corresponding to one \<embed\> tag on the page. 28 * 29 * Generally you would handle this call by initializing the information 30 * your module associates with an instance and creating a mapping from the 31 * given <code>PP_Instance</code> handle to this data. The 32 * <code>PP_Instance</code> handle will be used in subsequent calls to 33 * identify which instance the call pertains to. 34 * 35 * It's possible for more than one instance to be created in a single module. 36 * This means that you may get more than one <code>OnCreate</code> without an 37 * <code>OnDestroy</code> in between, and should be prepared to maintain 38 * multiple states associated with each instance. 39 * 40 * If this function reports a failure (by returning <code>PP_FALSE</code>), 41 * the instance will be deleted. 42 * 43 * @param[in] instance A new <code>PP_Instance</code> identifying one 44 * instance of a module. This is an opaque handle. 45 * 46 * @param[in] argc The number of arguments contained in <code>argn</code> 47 * and <code>argv</code>. 48 * 49 * @param[in] argn An array of argument names. These argument names are 50 * supplied in the \<embed\> tag, for example: 51 * <code>\<embed id="nacl_module" dimensions="2"\></code> will produce two 52 * argument names: "id" and "dimensions." 53 * 54 * @param[in] argv An array of argument values. These are the values of the 55 * arguments listed in the \<embed\> tag, for example 56 * <code>\<embed id="nacl_module" dimensions="2"\></code> will produce two 57 * argument values: "nacl_module" and "2". The indices of these values match 58 * the indices of the corresponding names in <code>argn</code>. 59 * 60 * @return <code>PP_TRUE</code> on success or <code>PP_FALSE</code> on 61 * failure. 62 */ 63 PP_Bool DidCreate( 64 /* A PP_Instance identifying one instance of a module. */ 65 [in] PP_Instance instance, 66 /* The number of arguments contained in argn and argv. */ 67 [in] uint32_t argc, 68 /* An array of argument names. These argument names are 69 * supplied in the <embed> tag, for example: 70 * <embed id="nacl_module" dimensions="2"> will produce two argument 71 * names: "id" and "dimensions." 72 */ 73 [in, size_as=argc] str_t[] argn, 74 /* An array of argument values. These are the values of the 75 * arguments listed in the <embed> tag, for example 76 * <embed id="nacl_module" dimensions="2"> will produce two argument 77 * values: "nacl_module" and "2." The indices of these values match the 78 * indices of the corresponding names in argn. 79 */ 80 [in, size_as=argc] str_t[] argv); 81 82 /** 83 * DidDestroy() is an instance destruction handler. This function is called 84 * in many cases (see below) when a module instance is destroyed. It will be 85 * called even if DidCreate() returned failure. 86 * 87 * Generally you will handle this call by deallocating the tracking 88 * information and the <code>PP_Instance</code> mapping you created in the 89 * DidCreate() call. You can also free resources associated with this 90 * instance but this isn't required; all resources associated with the deleted 91 * instance will be automatically freed when this function returns. 92 * 93 * The instance identifier will still be valid during this call, so the module 94 * can perform cleanup-related tasks. Once this function returns, the 95 * <code>PP_Instance</code> handle will be invalid. This means that you can't 96 * do any asynchronous operations like network requests, file writes or 97 * messaging from this function since they will be immediately canceled. 98 * 99 * <strong>Note:</strong> This function will always be skipped on untrusted 100 * (Native Client) implementations. This function may be skipped on trusted 101 * implementations in certain circumstances when Chrome does "fast shutdown" 102 * of a web page. Fast shutdown will happen in some cases when all module 103 * instances are being deleted, and no cleanup functions will be called. 104 * The module will just be unloaded and the process terminated. 105 * 106 * @param[in] instance A <code>PP_Instance</code> identifying one instance 107 * of a module. 108 */ 109 void DidDestroy( 110 /* A PP_Instance identifying one instance of a module. */ 111 [in] PP_Instance instance); 112 113 /** 114 * Deprecated in 1.1 in favor of the version that takes a Resource. 115 * 116 * DidChangeView() is called when the position, the size, of the clip 117 * rectangle of the element in the browser that corresponds to this 118 * instance has changed. 119 * 120 * A typical implementation will check the size of the <code>position</code> 121 * argument and reallocate the graphics context when a different size is 122 * received. Note that this function will be called for scroll events where 123 * the size doesn't change, so you should always check that the size is 124 * actually different before doing any reallocations. 125 * 126 * @param[in] instance A <code>PP_Instance</code> identifying the instance 127 * that has changed. 128 * 129 * @param[in] position The location on the page of the instance. This is 130 * relative to the top left corner of the viewport, which changes as the 131 * page is scrolled. Generally the size of this value will be used to create 132 * a graphics device, and the position is ignored (most things are relative 133 * to the instance so the absolute position isn't useful in most cases). 134 * 135 * @param[in] clip The visible region of the instance. This is relative to 136 * the top left of the module's coordinate system (not the page). If the 137 * module is invisible, <code>clip</code> will be (0, 0, 0, 0). 138 * 139 * It's recommended to check for invisible instances and to stop 140 * generating graphics updates in this case to save system resources. It's 141 * not usually worthwhile, however, to generate partial updates according to 142 * the clip when the instance is partially visible. Instead, update the entire 143 * region. The time saved doing partial paints is usually not significant and 144 * it can create artifacts when scrolling (this notification is sent 145 * asynchronously from scrolling so there can be flashes of old content in the 146 * exposed regions). 147 */ 148 void DidChangeView( 149 /* A PP_Instance identifying the instance whose view changed. */ 150 [in] PP_Instance instance, 151 /* The new location on the page of this instance. This is relative to 152 * the top left corner of the viewport, which changes as the 153 * page is scrolled. 154 */ 155 [in] PP_Rect position, 156 /* The visible region of the NaCl module. This is relative to the top 157 * left of the plugin's coordinate system (not the page) If the plugin 158 * is invisible, clip will be (0, 0, 0, 0). 159 */ 160 [in] PP_Rect clip); 161 162 /** 163 * <code>DidChangeView() is called when the position, size, or other view 164 * attributes of the instance has changed. 165 */ 166 [version=1.1] 167 void DidChangeView( 168 /* A PP_Instance identifying the instance whose view changed. */ 169 [in] PP_Instance instance, 170 /** 171 * A handle to a <code>PPB_View</code> resource identifying the new view. 172 */ 173 [in] PP_Resource view); 174 175 /** 176 * DidChangeFocus() is called when an instance has gained or lost focus. 177 * Having focus means that keyboard events will be sent to the instance. 178 * An instance's default condition is that it will not have focus. 179 * 180 * The focus flag takes into account both browser tab and window focus as 181 * well as focus of the plugin element on the page. In order to be deemed 182 * to have focus, the browser window must be topmost, the tab must be 183 * selected in the window, and the instance must be the focused element on 184 * the page. 185 * 186 * <strong>Note:</strong>Clicks on instances will give focus only if you 187 * handle the click event. Return <code>true</code> from 188 * <code>HandleInputEvent</code> in <code>PPP_InputEvent</code> (or use 189 * unfiltered events) to signal that the click event was handled. Otherwise, 190 * the browser will bubble the event and give focus to the element on the page 191 * that actually did end up consuming it. If you're not getting focus, check 192 * to make sure you're either requesting them via 193 * <code>RequestInputEvents()<code> (which implicitly marks all input events 194 * as consumed) or via <code>RequestFilteringInputEvents()</code> and 195 * returning true from your event handler. 196 * 197 * @param[in] instance A <code>PP_Instance</code> identifying the instance 198 * receiving the input event. 199 * 200 * @param[in] has_focus Indicates the new focused state of the instance. 201 */ 202 void DidChangeFocus( 203 /* A PP_Instance identifying one instance of a module. */ 204 [in] PP_Instance instance, 205 /* Indicates whether this NaCl module gained or lost event focus. */ 206 [in] PP_Bool has_focus); 207 208 /** 209 * HandleDocumentLoad() is called after initialize for a full-frame 210 * instance that was instantiated based on the MIME type of a DOMWindow 211 * navigation. This situation only applies to modules that are pre-registered 212 * to handle certain MIME types. If you haven't specifically registered to 213 * handle a MIME type or aren't positive this applies to you, your 214 * implementation of this function can just return <code>PP_FALSE</code>. 215 * 216 * The given <code>url_loader</code> corresponds to a 217 * <code>PPB_URLLoader</code> instance that is already opened. Its response 218 * headers may be queried using <code>PPB_URLLoader::GetResponseInfo</code>. 219 * The reference count for the URL loader is not incremented automatically on 220 * behalf of the module. You need to increment the reference count yourself 221 * if you are going to keep a reference to it. 222 * 223 * This method returns <code>PP_FALSE</code> if the module cannot handle the 224 * data. In response to this method, the module should call 225 * ReadResponseBody() to read the incoming data. 226 * 227 * @param[in] instance A <code>PP_Instance</code> identifying the instance 228 * that should do the load. 229 * 230 * @param[in] url_loader An open <code>PPB_URLLoader</code> instance. 231 * 232 * @return <code>PP_TRUE</code> if the data was handled, 233 * <code>PP_FALSE</code> otherwise. If you return false, the load will be 234 * canceled for you. 235 */ 236 PP_Bool HandleDocumentLoad( 237 /* A PP_Instance identifying one instance of a module. */ 238 [in] PP_Instance instance, 239 /* A PP_Resource an open PPB_URLLoader instance. */ 240 [in] PP_Resource url_loader); 241 242 }; 243
