ppapi/api/ppp_instance.idl

   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 };