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
11label 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 */
23interface 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};
243