/* 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 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 tag, for example: * 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 tag, for example * 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); };