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 */
42struct 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
178typedef struct PPP_Instance_1_1 PPP_Instance;
179
180struct 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
198