ppapi/api/ppp_instance.idl

/* Copyright (c) 2011 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 PPP_Instance structure - a series of points to methods
 * that you must implement in your model.
 */

/* The PPP_Instance interface contains 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_0_4 {
  /* Function that is called when a new module is instantiated on the web
   * page. The identifier of the new instance will be passed in as the first
   * argument (this value is generated by the browser and is an opaque
   * handle). This is called for each instantiation of the NaCl module, which
   * is each time the <embed> tag for this module is encountered.
   *
   * It's possible for more than one module instance to be created
   * (i.e. you may get more than one OnCreate without an OnDestroy
   * in between).
   *
   * If this function reports a failure (by returning @a PP_FALSE), the NaCl
   * module will be deleted and DidDestroy will be called.
   *
   * Returns PP_TRUE on success.
   */
  PP_Bool DidCreate(
      /* A PP_Instance indentifying 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_is(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_is(argc)] str_t[] argv);

  /* Function that is called when the module instance is destroyed. This
   * function will always be called, even if DidCreate returned failure.
   * The function should deallocate any data associated with the instance.
   */
  void DidDestroy(
      /* A PP_Instance indentifying one instance of a module. */
      [in] PP_Instance instance);

  /* Function that is called when the position, the size, or the clip
   * rectangle of the element in the browser that corresponds to this instance
   * has changed.
   */
  void DidChangeView(
      /* A PP_Instance indentifying 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);

  /* Function to handle when your instance has gained or lost focus. Having
   * focus means that keyboard events will be sent to the module. An
   * instance's default condition is that it will not have focus.
   *
   * Note: clicks on modules will give focus only if you handle the
   * click event. Return true from HandleInputEvent 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 returning true
   * from the mouse click in HandleInputEvent.
   */
  void DidChangeFocus(
      /* A PP_Instance indentifying one instance of a module. */
      [in] PP_Instance instance,
      /* Indicates whether this NaCl module gained or lost event focus. */
      [in] PP_Bool has_focus);

  /* Function to handle input events.
   *
   * Returns true if the event was handled or false if it was not. If the
   * event was handled, it will not be forwarded to the web page or browser.
   * If it was not handled, it will bubble according to the normal rules. So
   * it is important that a module respond accurately with whether event
   * propogation should continue.
   *
   * Event propogation also controls focus. If you handle an event like a
   * mouse event, typically your module will be given focus. Returning false
   * means that the click will be given to a lower part of the page and your
   * module will not receive focus. This allows a module to be partially
   * transparent, where clicks on the transparent areas will behave like
   * clicks to the underlying page.
   *
   * Returns PP_TRUE if event was handled, PP_FALSE otherwise.
   */
  PP_Bool HandleInputEvent(
      /* A PP_Instance indentifying one instance of a module. */
      [in] PP_Instance instance,
      /* The event. */
      [in] PP_InputEvent event);

  /* This value represents a pointer to a function that is called after
   * initialize for a full-frame plugin that was instantiated based on the MIME
   * type of a DOMWindow navigation. This only applies to modules that are
   * registered to handle certain MIME types (not current Native Client
   * modules).
   *
   * The given url_loader corresponds to a PPB_URLLoader instance that is
   * already opened. Its response headers may be queried using
   * PPB_URLLoader::GetResponseInfo. The url loader is not addrefed on behalf
   * of the module, if you're going to keep a reference to it, you need to
   * addref it yourself.
   *
   * This method returns PP_FALSE if the module cannot handle the data. In
   * response to this method, the module should call ReadResponseBody to read
   * the incoming data.
   *
   * Returns PP_TRUE if the data was handled, PP_FALSE otherwise.
   */
  PP_Bool HandleDocumentLoad(
      /* A PP_Instance indentifying one instance of a module. */
      [in] PP_Instance instance,
      /* A PP_Resource an open PPB_URLLoader instance. */
      [in] PP_Resource url_loader);

  /* This value represents a pointer to a function that returns a Var
   * representing the scriptable object for the given instance. Normally
   * this will be a PPP_Class object that exposes certain methods the page
   * may want to call.
   *
   * On Failure, the returned var should be a "void" var.
   *
   * The returned PP_Var should have a reference added for the caller, which
   * will be responsible for Release()ing that reference.
   *
   * Returns a PP_Var containing scriptable object.
   */
  PP_Var GetInstanceObject(
      /* A PP_Instance indentifying one instance of a module. */
      [in] PP_Instance instance);
};