1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
|
/* 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
* module 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.
*/
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);
};
|
