src/ppapi/c/ppp_instance.h

   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