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 ppp_instance.idl modified Thu Apr 25 13:07:47 2013. */ 7 8 #ifndef PPAPI_C_PPP_INSTANCE_H_ 9 #define PPAPI_C_PPP_INSTANCE_H_ 10 11 #include "ppapi/c/pp_bool.h" 12 #include "ppapi/c/pp_instance.h" 13 #include "ppapi/c/pp_macros.h" 14 #include "ppapi/c/pp_point.h" 15 #include "ppapi/c/pp_rect.h" 16 #include "ppapi/c/pp_resource.h" 17 #include "ppapi/c/pp_size.h" 18 #include "ppapi/c/pp_stdint.h" 19 20 #define PPP_INSTANCE_INTERFACE_1_0 "PPP_Instance;1.0" 21 #define PPP_INSTANCE_INTERFACE_1_1 "PPP_Instance;1.1" 22 #define PPP_INSTANCE_INTERFACE PPP_INSTANCE_INTERFACE_1_1 23 24 /** 25 * @file 26 * This file defines the <code>PPP_Instance</code> structure - a series of 27 * pointers to methods that you must implement in your module. 28 */ 29 30 31 /** 32 * @addtogroup Interfaces 33 * @{ 34 */ 35 /** 36 * The <code>PPP_Instance</code> interface contains pointers to a series of 37 * functions that you must implement in your module. These functions can be 38 * trivial (simply return the default return value) unless you want your module 39 * to handle events such as change of focus or input events (keyboard/mouse) 40 * events. 41 */ 42 struct PPP_Instance_1_1 { 43 /** 44 * DidCreate() is a creation handler that is called when a new instance is 45 * created. This function is called for each instantiation on the page, 46 * corresponding to one \<embed\> tag on the page. 47 * 48 * Generally you would handle this call by initializing the information 49 * your module associates with an instance and creating a mapping from the 50 * given <code>PP_Instance</code> handle to this data. The 51 * <code>PP_Instance</code> handle will be used in subsequent calls to 52 * identify which instance the call pertains to. 53 * 54 * It's possible for more than one instance to be created in a single module. 55 * This means that you may get more than one <code>OnCreate</code> without an 56 * <code>OnDestroy</code> in between, and should be prepared to maintain 57 * multiple states associated with each instance. 58 * 59 * If this function reports a failure (by returning <code>PP_FALSE</code>), 60 * the instance will be deleted. 61 * 62 * @param[in] instance A new <code>PP_Instance</code> identifying one 63 * instance of a module. This is an opaque handle. 64 * 65 * @param[in] argc The number of arguments contained in <code>argn</code> 66 * and <code>argv</code>. 67 * 68 * @param[in] argn An array of argument names. These argument names are 69 * supplied in the \<embed\> tag, for example: 70 * <code>\<embed id="nacl_module" dimensions="2"\></code> will produce two 71 * argument names: "id" and "dimensions." 72 * 73 * @param[in] argv An array of argument values. These are the values of the 74 * arguments listed in the \<embed\> tag, for example 75 * <code>\<embed id="nacl_module" dimensions="2"\></code> will produce two 76 * argument values: "nacl_module" and "2". The indices of these values match 77 * the indices of the corresponding names in <code>argn</code>. 78 * 79 * @return <code>PP_TRUE</code> on success or <code>PP_FALSE</code> on 80 * failure. 81 */ 82 PP_Bool (*DidCreate)(PP_Instance instance, 83 uint32_t argc, 84 const char* argn[], 85 const char* argv[]); 86 /** 87 * DidDestroy() is an instance destruction handler. This function is called 88 * in many cases (see below) when a module instance is destroyed. It will be 89 * called even if DidCreate() returned failure. 90 * 91 * Generally you will handle this call by deallocating the tracking 92 * information and the <code>PP_Instance</code> mapping you created in the 93 * DidCreate() call. You can also free resources associated with this 94 * instance but this isn't required; all resources associated with the deleted 95 * instance will be automatically freed when this function returns. 96 * 97 * The instance identifier will still be valid during this call, so the module 98 * can perform cleanup-related tasks. Once this function returns, the 99 * <code>PP_Instance</code> handle will be invalid. This means that you can't 100 * do any asynchronous operations like network requests, file writes or 101 * messaging from this function since they will be immediately canceled. 102 * 103 * <strong>Note:</strong> This function will always be skipped on untrusted 104 * (Native Client) implementations. This function may be skipped on trusted 105 * implementations in certain circumstances when Chrome does "fast shutdown" 106 * of a web page. Fast shutdown will happen in some cases when all module 107 * instances are being deleted, and no cleanup functions will be called. 108 * The module will just be unloaded and the process terminated. 109 * 110 * @param[in] instance A <code>PP_Instance</code> identifying one instance 111 * of a module. 112 */ 113 void (*DidDestroy)(PP_Instance instance); 114 /** 115 * <code>DidChangeView() is called when the position, size, or other view 116 * attributes of the instance has changed. 117 */ 118 void (*DidChangeView)(PP_Instance instance, PP_Resource view); 119 /** 120 * DidChangeFocus() is called when an instance has gained or lost focus. 121 * Having focus means that keyboard events will be sent to the instance. 122 * An instance's default condition is that it will not have focus. 123 * 124 * The focus flag takes into account both browser tab and window focus as 125 * well as focus of the plugin element on the page. In order to be deemed 126 * to have focus, the browser window must be topmost, the tab must be 127 * selected in the window, and the instance must be the focused element on 128 * the page. 129 * 130 * <strong>Note:</strong>Clicks on instances will give focus only if you 131 * handle the click event. Return <code>true</code> from 132 * <code>HandleInputEvent</code> in <code>PPP_InputEvent</code> (or use 133 * unfiltered events) to signal that the click event was handled. Otherwise, 134 * the browser will bubble the event and give focus to the element on the page 135 * that actually did end up consuming it. If you're not getting focus, check 136 * to make sure you're either requesting them via 137 * <code>RequestInputEvents()<code> (which implicitly marks all input events 138 * as consumed) or via <code>RequestFilteringInputEvents()</code> and 139 * returning true from your event handler. 140 * 141 * @param[in] instance A <code>PP_Instance</code> identifying the instance 142 * receiving the input event. 143 * 144 * @param[in] has_focus Indicates the new focused state of the instance. 145 */ 146 void (*DidChangeFocus)(PP_Instance instance, PP_Bool has_focus); 147 /** 148 * HandleDocumentLoad() is called after initialize for a full-frame 149 * instance that was instantiated based on the MIME type of a DOMWindow 150 * navigation. This situation only applies to modules that are pre-registered 151 * to handle certain MIME types. If you haven't specifically registered to 152 * handle a MIME type or aren't positive this applies to you, your 153 * implementation of this function can just return <code>PP_FALSE</code>. 154 * 155 * The given <code>url_loader</code> corresponds to a 156 * <code>PPB_URLLoader</code> instance that is already opened. Its response 157 * headers may be queried using <code>PPB_URLLoader::GetResponseInfo</code>. 158 * The reference count for the URL loader is not incremented automatically on 159 * behalf of the module. You need to increment the reference count yourself 160 * if you are going to keep a reference to it. 161 * 162 * This method returns <code>PP_FALSE</code> if the module cannot handle the 163 * data. In response to this method, the module should call 164 * ReadResponseBody() to read the incoming data. 165 * 166 * @param[in] instance A <code>PP_Instance</code> identifying the instance 167 * that should do the load. 168 * 169 * @param[in] url_loader An open <code>PPB_URLLoader</code> instance. 170 * 171 * @return <code>PP_TRUE</code> if the data was handled, 172 * <code>PP_FALSE</code> otherwise. If you return false, the load will be 173 * canceled for you. 174 */ 175 PP_Bool (*HandleDocumentLoad)(PP_Instance instance, PP_Resource url_loader); 176 }; 177 178 typedef struct PPP_Instance_1_1 PPP_Instance; 179 180 struct PPP_Instance_1_0 { 181 PP_Bool (*DidCreate)(PP_Instance instance, 182 uint32_t argc, 183 const char* argn[], 184 const char* argv[]); 185 void (*DidDestroy)(PP_Instance instance); 186 void (*DidChangeView)(PP_Instance instance, 187 const struct PP_Rect* position, 188 const struct PP_Rect* clip); 189 void (*DidChangeFocus)(PP_Instance instance, PP_Bool has_focus); 190 PP_Bool (*HandleDocumentLoad)(PP_Instance instance, PP_Resource url_loader); 191 }; 192 /** 193 * @} 194 */ 195 196 #endif /* PPAPI_C_PPP_INSTANCE_H_ */ 197 198