| /* Copyright (c) 2012 The Chromium Authors. All rights reserved. |
| * Use of this source code is governed by a BSD-style license that can be |
| * found in the LICENSE file. |
| */ |
| |
| /** |
| * This file defines the <code>PPP_Instance</code> structure - a series of |
| * pointers to methods that you must implement in your module. |
| */ |
| |
| label Chrome { |
| M14 = 1.0, |
| M17 = 1.1 |
| }; |
| |
| /** |
| * The <code>PPP_Instance</code> interface contains pointers to a series of |
| * functions that you must implement in your module. These functions can be |
| * trivial (simply return the default return value) unless you want your module |
| * to handle events such as change of focus or input events (keyboard/mouse) |
| * events. |
| */ |
| interface PPP_Instance { |
| /** |
| * DidCreate() is a creation handler that is called when a new instance is |
| * created. This function is called for each instantiation on the page, |
| * corresponding to one \<embed\> tag on the page. |
| * |
| * Generally you would handle this call by initializing the information |
| * your module associates with an instance and creating a mapping from the |
| * given <code>PP_Instance</code> handle to this data. The |
| * <code>PP_Instance</code> handle will be used in subsequent calls to |
| * identify which instance the call pertains to. |
| * |
| * It's possible for more than one instance to be created in a single module. |
| * This means that you may get more than one <code>OnCreate</code> without an |
| * <code>OnDestroy</code> in between, and should be prepared to maintain |
| * multiple states associated with each instance. |
| * |
| * If this function reports a failure (by returning <code>PP_FALSE</code>), |
| * the instance will be deleted. |
| * |
| * @param[in] instance A new <code>PP_Instance</code> identifying one |
| * instance of a module. This is an opaque handle. |
| * |
| * @param[in] argc The number of arguments contained in <code>argn</code> |
| * and <code>argv</code>. |
| * |
| * @param[in] argn An array of argument names. These argument names are |
| * supplied in the \<embed\> tag, for example: |
| * <code>\<embed id="nacl_module" dimensions="2"\></code> will produce two |
| * argument names: "id" and "dimensions." |
| * |
| * @param[in] argv An array of argument values. These are the values of the |
| * arguments listed in the \<embed\> tag, for example |
| * <code>\<embed id="nacl_module" dimensions="2"\></code> will produce two |
| * argument values: "nacl_module" and "2". The indices of these values match |
| * the indices of the corresponding names in <code>argn</code>. |
| * |
| * @return <code>PP_TRUE</code> on success or <code>PP_FALSE</code> on |
| * failure. |
| */ |
| PP_Bool DidCreate( |
| /* A PP_Instance identifying one instance of a module. */ |
| [in] PP_Instance instance, |
| /* The number of arguments contained in argn and argv. */ |
| [in] uint32_t argc, |
| /* An array of argument names. These argument names are |
| * supplied in the <embed> tag, for example: |
| * <embed id="nacl_module" dimensions="2"> will produce two argument |
| * names: "id" and "dimensions." |
| */ |
| [in, size_as=argc] str_t[] argn, |
| /* An array of argument values. These are the values of the |
| * arguments listed in the <embed> tag, for example |
| * <embed id="nacl_module" dimensions="2"> will produce two argument |
| * values: "nacl_module" and "2." The indices of these values match the |
| * indices of the corresponding names in argn. |
| */ |
| [in, size_as=argc] str_t[] argv); |
| |
| /** |
| * DidDestroy() is an instance destruction handler. This function is called |
| * in many cases (see below) when a module instance is destroyed. It will be |
| * called even if DidCreate() returned failure. |
| * |
| * Generally you will handle this call by deallocating the tracking |
| * information and the <code>PP_Instance</code> mapping you created in the |
| * DidCreate() call. You can also free resources associated with this |
| * instance but this isn't required; all resources associated with the deleted |
| * instance will be automatically freed when this function returns. |
| * |
| * The instance identifier will still be valid during this call, so the module |
| * can perform cleanup-related tasks. Once this function returns, the |
| * <code>PP_Instance</code> handle will be invalid. This means that you can't |
| * do any asynchronous operations like network requests, file writes or |
| * messaging from this function since they will be immediately canceled. |
| * |
| * <strong>Note:</strong> This function will always be skipped on untrusted |
| * (Native Client) implementations. This function may be skipped on trusted |
| * implementations in certain circumstances when Chrome does "fast shutdown" |
| * of a web page. Fast shutdown will happen in some cases when all module |
| * instances are being deleted, and no cleanup functions will be called. |
| * The module will just be unloaded and the process terminated. |
| * |
| * @param[in] instance A <code>PP_Instance</code> identifying one instance |
| * of a module. |
| */ |
| void DidDestroy( |
| /* A PP_Instance identifying one instance of a module. */ |
| [in] PP_Instance instance); |
| |
| /** |
| * Deprecated in 1.1 in favor of the version that takes a Resource. |
| * |
| * DidChangeView() is called when the position, the size, of the clip |
| * rectangle of the element in the browser that corresponds to this |
| * instance has changed. |
| * |
| * A typical implementation will check the size of the <code>position</code> |
| * argument and reallocate the graphics context when a different size is |
| * received. Note that this function will be called for scroll events where |
| * the size doesn't change, so you should always check that the size is |
| * actually different before doing any reallocations. |
| * |
| * @param[in] instance A <code>PP_Instance</code> identifying the instance |
| * that has changed. |
| * |
| * @param[in] position The location on the page of the instance. This is |
| * relative to the top left corner of the viewport, which changes as the |
| * page is scrolled. Generally the size of this value will be used to create |
| * a graphics device, and the position is ignored (most things are relative |
| * to the instance so the absolute position isn't useful in most cases). |
| * |
| * @param[in] clip The visible region of the instance. This is relative to |
| * the top left of the module's coordinate system (not the page). If the |
| * module is invisible, <code>clip</code> will be (0, 0, 0, 0). |
| * |
| * It's recommended to check for invisible instances and to stop |
| * generating graphics updates in this case to save system resources. It's |
| * not usually worthwhile, however, to generate partial updates according to |
| * the clip when the instance is partially visible. Instead, update the entire |
| * region. The time saved doing partial paints is usually not significant and |
| * it can create artifacts when scrolling (this notification is sent |
| * asynchronously from scrolling so there can be flashes of old content in the |
| * exposed regions). |
| */ |
| void DidChangeView( |
| /* A PP_Instance identifying the instance whose view changed. */ |
| [in] PP_Instance instance, |
| /* The new location on the page of this instance. This is relative to |
| * the top left corner of the viewport, which changes as the |
| * page is scrolled. |
| */ |
| [in] PP_Rect position, |
| /* The visible region of the NaCl module. This is relative to the top |
| * left of the plugin's coordinate system (not the page) If the plugin |
| * is invisible, clip will be (0, 0, 0, 0). |
| */ |
| [in] PP_Rect clip); |
| |
| /** |
| * <code>DidChangeView() is called when the position, size, or other view |
| * attributes of the instance has changed. |
| */ |
| [version=1.1] |
| void DidChangeView( |
| /* A PP_Instance identifying the instance whose view changed. */ |
| [in] PP_Instance instance, |
| /** |
| * A handle to a <code>PPB_View</code> resource identifying the new view. |
| */ |
| [in] PP_Resource view); |
| |
| /** |
| * DidChangeFocus() is called when an instance has gained or lost focus. |
| * Having focus means that keyboard events will be sent to the instance. |
| * An instance's default condition is that it will not have focus. |
| * |
| * The focus flag takes into account both browser tab and window focus as |
| * well as focus of the plugin element on the page. In order to be deemed |
| * to have focus, the browser window must be topmost, the tab must be |
| * selected in the window, and the instance must be the focused element on |
| * the page. |
| * |
| * <strong>Note:</strong>Clicks on instances will give focus only if you |
| * handle the click event. Return <code>true</code> from |
| * <code>HandleInputEvent</code> in <code>PPP_InputEvent</code> (or use |
| * unfiltered events) to signal that the click event was handled. Otherwise, |
| * the browser will bubble the event and give focus to the element on the page |
| * that actually did end up consuming it. If you're not getting focus, check |
| * to make sure you're either requesting them via |
| * <code>RequestInputEvents()<code> (which implicitly marks all input events |
| * as consumed) or via <code>RequestFilteringInputEvents()</code> and |
| * returning true from your event handler. |
| * |
| * @param[in] instance A <code>PP_Instance</code> identifying the instance |
| * receiving the input event. |
| * |
| * @param[in] has_focus Indicates the new focused state of the instance. |
| */ |
| void DidChangeFocus( |
| /* A PP_Instance identifying one instance of a module. */ |
| [in] PP_Instance instance, |
| /* Indicates whether this NaCl module gained or lost event focus. */ |
| [in] PP_Bool has_focus); |
| |
| /** |
| * HandleDocumentLoad() is called after initialize for a full-frame |
| * instance that was instantiated based on the MIME type of a DOMWindow |
| * navigation. This situation only applies to modules that are pre-registered |
| * to handle certain MIME types. If you haven't specifically registered to |
| * handle a MIME type or aren't positive this applies to you, your |
| * implementation of this function can just return <code>PP_FALSE</code>. |
| * |
| * The given <code>url_loader</code> corresponds to a |
| * <code>PPB_URLLoader</code> instance that is already opened. Its response |
| * headers may be queried using <code>PPB_URLLoader::GetResponseInfo</code>. |
| * The reference count for the URL loader is not incremented automatically on |
| * behalf of the module. You need to increment the reference count yourself |
| * if you are going to keep a reference to it. |
| * |
| * This method returns <code>PP_FALSE</code> if the module cannot handle the |
| * data. In response to this method, the module should call |
| * ReadResponseBody() to read the incoming data. |
| * |
| * @param[in] instance A <code>PP_Instance</code> identifying the instance |
| * that should do the load. |
| * |
| * @param[in] url_loader An open <code>PPB_URLLoader</code> instance. |
| * |
| * @return <code>PP_TRUE</code> if the data was handled, |
| * <code>PP_FALSE</code> otherwise. If you return false, the load will be |
| * canceled for you. |
| */ |
| PP_Bool HandleDocumentLoad( |
| /* A PP_Instance identifying one instance of a module. */ |
| [in] PP_Instance instance, |
| /* A PP_Resource an open PPB_URLLoader instance. */ |
| [in] PP_Resource url_loader); |
| |
| }; |