OLD | NEW |
| (Empty) |
1 /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ | |
2 /* | |
3 * Copyright (c) 2004, Apple Computer, Inc. and The Mozilla Foundation. | |
4 * All rights reserved. | |
5 * | |
6 * Redistribution and use in source and binary forms, with or without | |
7 * modification, are permitted provided that the following conditions are | |
8 * met: | |
9 * | |
10 * 1. Redistributions of source code must retain the above copyright | |
11 * notice, this list of conditions and the following disclaimer. | |
12 * 2. Redistributions in binary form must reproduce the above copyright | |
13 * notice, this list of conditions and the following disclaimer in the | |
14 * documentation and/or other materials provided with the distribution. | |
15 * 3. Neither the names of Apple Computer, Inc. ("Apple") or The Mozilla | |
16 * Foundation ("Mozilla") nor the names of their contributors may be used | |
17 * to endorse or promote products derived from this software without | |
18 * specific prior written permission. | |
19 * | |
20 * THIS SOFTWARE IS PROVIDED BY APPLE, MOZILLA AND THEIR CONTRIBUTORS "AS | |
21 * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED | |
22 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A | |
23 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE, MOZILLA OR | |
24 * THEIR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
25 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED | |
26 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR | |
27 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF | |
28 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING | |
29 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS | |
30 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
31 * | |
32 */ | |
33 #ifndef _NP_RUNTIME_H_ | |
34 #define _NP_RUNTIME_H_ | |
35 | |
36 // BEGIN GOOGLE MODIFICATIONS | |
37 #include "npapi.h" | |
38 // END GOOGLE MODIFICATIONS | |
39 | |
40 #ifdef __cplusplus | |
41 extern "C" { | |
42 #endif | |
43 | |
44 #include "nptypes.h" | |
45 | |
46 /* | |
47 This API is used to facilitate binding code written in C to script | |
48 objects. The API in this header does not assume the presence of a | |
49 user agent. That is, it can be used to bind C code to scripting | |
50 environments outside of the context of a user agent. | |
51 | |
52 However, the normal use of the this API is in the context of a | |
53 scripting environment running in a browser or other user agent. | |
54 In particular it is used to support the extended Netscape | |
55 script-ability API for plugins (NP-SAP). NP-SAP is an extension | |
56 of the Netscape plugin API. As such we have adopted the use of | |
57 the "NP" prefix for this API. | |
58 | |
59 The following NP{N|P}Variables were added to the Netscape plugin | |
60 API (in npapi.h): | |
61 | |
62 NPNVWindowNPObject | |
63 NPNVPluginElementNPObject | |
64 NPPVpluginScriptableNPObject | |
65 | |
66 These variables are exposed through NPN_GetValue() and | |
67 NPP_GetValue() (respectively) and are used to establish the | |
68 initial binding between the user agent and native code. The DOM | |
69 objects in the user agent can be examined and manipulated using | |
70 the NPN_ functions that operate on NPObjects described in this | |
71 header. | |
72 | |
73 To the extent possible the assumptions about the scripting | |
74 language used by the scripting environment have been minimized. | |
75 */ | |
76 | |
77 #define NP_BEGIN_MACRO do { | |
78 #define NP_END_MACRO } while (0) | |
79 | |
80 /* | |
81 Objects (non-primitive data) passed between 'C' and script is | |
82 always wrapped in an NPObject. The 'interface' of an NPObject is | |
83 described by an NPClass. | |
84 */ | |
85 typedef struct NPObject NPObject; | |
86 typedef struct NPClass NPClass; | |
87 | |
88 typedef char NPUTF8; | |
89 typedef struct _NPString { | |
90 const NPUTF8 *UTF8Characters; | |
91 uint32_t UTF8Length; | |
92 } NPString; | |
93 | |
94 typedef enum { | |
95 NPVariantType_Void, | |
96 NPVariantType_Null, | |
97 NPVariantType_Bool, | |
98 NPVariantType_Int32, | |
99 NPVariantType_Double, | |
100 NPVariantType_String, | |
101 NPVariantType_Object | |
102 } NPVariantType; | |
103 | |
104 typedef struct _NPVariant { | |
105 NPVariantType type; | |
106 union { | |
107 bool boolValue; | |
108 int32_t intValue; | |
109 double doubleValue; | |
110 NPString stringValue; | |
111 NPObject *objectValue; | |
112 } value; | |
113 } NPVariant; | |
114 | |
115 /* | |
116 NPN_ReleaseVariantValue is called on all 'out' parameters | |
117 references. Specifically it is to be called on variants that own | |
118 their value, as is the case with all non-const NPVariant* | |
119 arguments after a successful call to any methods (except this one) | |
120 in this API. | |
121 | |
122 After calling NPN_ReleaseVariantValue, the type of the variant | |
123 will be NPVariantType_Void. | |
124 */ | |
125 void NPN_ReleaseVariantValue(NPVariant *variant); | |
126 | |
127 #define NPVARIANT_IS_VOID(_v) ((_v).type == NPVariantType_Void) | |
128 #define NPVARIANT_IS_NULL(_v) ((_v).type == NPVariantType_Null) | |
129 #define NPVARIANT_IS_BOOLEAN(_v) ((_v).type == NPVariantType_Bool) | |
130 #define NPVARIANT_IS_INT32(_v) ((_v).type == NPVariantType_Int32) | |
131 #define NPVARIANT_IS_DOUBLE(_v) ((_v).type == NPVariantType_Double) | |
132 #define NPVARIANT_IS_STRING(_v) ((_v).type == NPVariantType_String) | |
133 #define NPVARIANT_IS_OBJECT(_v) ((_v).type == NPVariantType_Object) | |
134 | |
135 #define NPVARIANT_TO_BOOLEAN(_v) ((_v).value.boolValue) | |
136 #define NPVARIANT_TO_INT32(_v) ((_v).value.intValue) | |
137 #define NPVARIANT_TO_DOUBLE(_v) ((_v).value.doubleValue) | |
138 #define NPVARIANT_TO_STRING(_v) ((_v).value.stringValue) | |
139 #define NPVARIANT_TO_OBJECT(_v) ((_v).value.objectValue) | |
140 | |
141 #define VOID_TO_NPVARIANT(_v) \ | |
142 NP_BEGIN_MACRO \ | |
143 (_v).type = NPVariantType_Void; \ | |
144 (_v).value.objectValue = NULL; \ | |
145 NP_END_MACRO | |
146 | |
147 #define NULL_TO_NPVARIANT(_v) \ | |
148 NP_BEGIN_MACRO \ | |
149 (_v).type = NPVariantType_Null; \ | |
150 (_v).value.objectValue = NULL; \ | |
151 NP_END_MACRO | |
152 | |
153 #define BOOLEAN_TO_NPVARIANT(_val, _v) \ | |
154 NP_BEGIN_MACRO \ | |
155 (_v).type = NPVariantType_Bool; \ | |
156 (_v).value.boolValue = !!(_val); \ | |
157 NP_END_MACRO | |
158 | |
159 #define INT32_TO_NPVARIANT(_val, _v) \ | |
160 NP_BEGIN_MACRO \ | |
161 (_v).type = NPVariantType_Int32; \ | |
162 (_v).value.intValue = _val; \ | |
163 NP_END_MACRO | |
164 | |
165 #define DOUBLE_TO_NPVARIANT(_val, _v) \ | |
166 NP_BEGIN_MACRO \ | |
167 (_v).type = NPVariantType_Double; \ | |
168 (_v).value.doubleValue = _val; \ | |
169 NP_END_MACRO | |
170 | |
171 #define STRINGZ_TO_NPVARIANT(_val, _v) \ | |
172 NP_BEGIN_MACRO \ | |
173 (_v).type = NPVariantType_String; \ | |
174 NPString str = { _val, (uint32_t)(strlen(_val)) }; \ | |
175 (_v).value.stringValue = str; \ | |
176 NP_END_MACRO | |
177 | |
178 #define STRINGN_TO_NPVARIANT(_val, _len, _v) \ | |
179 NP_BEGIN_MACRO \ | |
180 (_v).type = NPVariantType_String; \ | |
181 NPString str = { _val, (uint32_t)(_len) }; \ | |
182 (_v).value.stringValue = str; \ | |
183 NP_END_MACRO | |
184 | |
185 #define OBJECT_TO_NPVARIANT(_val, _v) \ | |
186 NP_BEGIN_MACRO \ | |
187 (_v).type = NPVariantType_Object; \ | |
188 (_v).value.objectValue = _val; \ | |
189 NP_END_MACRO | |
190 | |
191 | |
192 /* | |
193 Type mappings (JavaScript types have been used for illustration | |
194 purposes): | |
195 | |
196 JavaScript to C (NPVariant with type:) | |
197 undefined NPVariantType_Void | |
198 null NPVariantType_Null | |
199 Boolean NPVariantType_Bool | |
200 Number NPVariantType_Double or NPVariantType_Int32 | |
201 String NPVariantType_String | |
202 Object NPVariantType_Object | |
203 | |
204 C (NPVariant with type:) to JavaScript | |
205 NPVariantType_Void undefined | |
206 NPVariantType_Null null | |
207 NPVariantType_Bool Boolean | |
208 NPVariantType_Int32 Number | |
209 NPVariantType_Double Number | |
210 NPVariantType_String String | |
211 NPVariantType_Object Object | |
212 */ | |
213 | |
214 typedef void *NPIdentifier; | |
215 | |
216 /* | |
217 NPObjects have methods and properties. Methods and properties are | |
218 identified with NPIdentifiers. These identifiers may be reflected | |
219 in script. NPIdentifiers can be either strings or integers, IOW, | |
220 methods and properties can be identified by either strings or | |
221 integers (i.e. foo["bar"] vs foo[1]). NPIdentifiers can be | |
222 compared using ==. In case of any errors, the requested | |
223 NPIdentifier(s) will be NULL. NPIdentifier lifetime is controlled | |
224 by the browser. Plugins do not need to worry about memory management | |
225 with regards to NPIdentifiers. | |
226 */ | |
227 NPIdentifier NPN_GetStringIdentifier(const NPUTF8 *name); | |
228 void NPN_GetStringIdentifiers(const NPUTF8 **names, int32_t nameCount, | |
229 NPIdentifier *identifiers); | |
230 NPIdentifier NPN_GetIntIdentifier(int32_t intid); | |
231 bool NPN_IdentifierIsString(NPIdentifier identifier); | |
232 | |
233 /* | |
234 The NPUTF8 returned from NPN_UTF8FromIdentifier SHOULD be freed. | |
235 */ | |
236 NPUTF8 *NPN_UTF8FromIdentifier(NPIdentifier identifier); | |
237 | |
238 /* | |
239 Get the integer represented by identifier. If identifier is not an | |
240 integer identifier, the behaviour is undefined. | |
241 */ | |
242 int32_t NPN_IntFromIdentifier(NPIdentifier identifier); | |
243 | |
244 /* | |
245 NPObject behavior is implemented using the following set of | |
246 callback functions. | |
247 | |
248 The NPVariant *result argument of these functions (where | |
249 applicable) should be released using NPN_ReleaseVariantValue(). | |
250 */ | |
251 typedef NPObject *(*NPAllocateFunctionPtr)(NPP npp, NPClass *aClass); | |
252 typedef void (*NPDeallocateFunctionPtr)(NPObject *npobj); | |
253 typedef void (*NPInvalidateFunctionPtr)(NPObject *npobj); | |
254 typedef bool (*NPHasMethodFunctionPtr)(NPObject *npobj, NPIdentifier name); | |
255 typedef bool (*NPInvokeFunctionPtr)(NPObject *npobj, NPIdentifier name, | |
256 const NPVariant *args, uint32_t argCount, | |
257 NPVariant *result); | |
258 typedef bool (*NPInvokeDefaultFunctionPtr)(NPObject *npobj, | |
259 const NPVariant *args, | |
260 uint32_t argCount, | |
261 NPVariant *result); | |
262 typedef bool (*NPHasPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name); | |
263 typedef bool (*NPGetPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name, | |
264 NPVariant *result); | |
265 typedef bool (*NPSetPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name, | |
266 const NPVariant *value); | |
267 typedef bool (*NPRemovePropertyFunctionPtr)(NPObject *npobj, | |
268 NPIdentifier name); | |
269 typedef bool (*NPEnumerationFunctionPtr)(NPObject *npobj, NPIdentifier **value, | |
270 uint32_t *count); | |
271 typedef bool (*NPConstructFunctionPtr)(NPObject *npobj, | |
272 const NPVariant *args, | |
273 uint32_t argCount, | |
274 NPVariant *result); | |
275 | |
276 /* | |
277 NPObjects returned by create, retain, invoke, and getProperty pass | |
278 a reference count to the caller. That is, the callee adds a | |
279 reference count which passes to the caller. It is the caller's | |
280 responsibility to release the returned object. | |
281 | |
282 NPInvokeFunctionPtr function may return 0 to indicate a void | |
283 result. | |
284 | |
285 NPInvalidateFunctionPtr is called by the scripting environment | |
286 when the native code is shutdown. Any attempt to message a | |
287 NPObject instance after the invalidate callback has been | |
288 called will result in undefined behavior, even if the native code | |
289 is still retaining those NPObject instances. (The runtime | |
290 will typically return immediately, with 0 or NULL, from an attempt | |
291 to dispatch to a NPObject, but this behavior should not be | |
292 depended upon.) | |
293 | |
294 The NPEnumerationFunctionPtr function may pass an array of | |
295 NPIdentifiers back to the caller. The callee allocs the memory of | |
296 the array using NPN_MemAlloc(), and it's the caller's responsibility | |
297 to release it using NPN_MemFree(). | |
298 */ | |
299 struct NPClass | |
300 { | |
301 uint32_t structVersion; | |
302 NPAllocateFunctionPtr allocate; | |
303 NPDeallocateFunctionPtr deallocate; | |
304 NPInvalidateFunctionPtr invalidate; | |
305 NPHasMethodFunctionPtr hasMethod; | |
306 NPInvokeFunctionPtr invoke; | |
307 NPInvokeDefaultFunctionPtr invokeDefault; | |
308 NPHasPropertyFunctionPtr hasProperty; | |
309 NPGetPropertyFunctionPtr getProperty; | |
310 NPSetPropertyFunctionPtr setProperty; | |
311 NPRemovePropertyFunctionPtr removeProperty; | |
312 NPEnumerationFunctionPtr enumerate; | |
313 NPConstructFunctionPtr construct; | |
314 }; | |
315 | |
316 #define NP_CLASS_STRUCT_VERSION 3 | |
317 | |
318 #define NP_CLASS_STRUCT_VERSION_ENUM 2 | |
319 #define NP_CLASS_STRUCT_VERSION_CTOR 3 | |
320 | |
321 #define NP_CLASS_STRUCT_VERSION_HAS_ENUM(npclass) \ | |
322 ((npclass)->structVersion >= NP_CLASS_STRUCT_VERSION_ENUM) | |
323 | |
324 #define NP_CLASS_STRUCT_VERSION_HAS_CTOR(npclass) \ | |
325 ((npclass)->structVersion >= NP_CLASS_STRUCT_VERSION_CTOR) | |
326 | |
327 struct NPObject { | |
328 NPClass *_class; | |
329 uint32_t referenceCount; | |
330 /* | |
331 * Additional space may be allocated here by types of NPObjects | |
332 */ | |
333 }; | |
334 | |
335 /* | |
336 If the class has an allocate function, NPN_CreateObject invokes | |
337 that function, otherwise a NPObject is allocated and | |
338 returned. This method will initialize the referenceCount member of | |
339 the NPObject to 1. | |
340 */ | |
341 NPObject *NPN_CreateObject(NPP npp, NPClass *aClass); | |
342 | |
343 /* | |
344 Increment the NPObject's reference count. | |
345 */ | |
346 NPObject *NPN_RetainObject(NPObject *npobj); | |
347 | |
348 /* | |
349 Decremented the NPObject's reference count. If the reference | |
350 count goes to zero, the class's destroy function is invoke if | |
351 specified, otherwise the object is freed directly. | |
352 */ | |
353 void NPN_ReleaseObject(NPObject *npobj); | |
354 | |
355 /* | |
356 Functions to access script objects represented by NPObject. | |
357 | |
358 Calls to script objects are synchronous. If a function returns a | |
359 value, it will be supplied via the result NPVariant | |
360 argument. Successful calls will return true, false will be | |
361 returned in case of an error. | |
362 | |
363 Calls made from plugin code to script must be made from the thread | |
364 on which the plugin was initialized. | |
365 */ | |
366 | |
367 bool NPN_Invoke(NPP npp, NPObject *npobj, NPIdentifier methodName, | |
368 const NPVariant *args, uint32_t argCount, NPVariant *result); | |
369 bool NPN_InvokeDefault(NPP npp, NPObject *npobj, const NPVariant *args, | |
370 uint32_t argCount, NPVariant *result); | |
371 bool NPN_Evaluate(NPP npp, NPObject *npobj, NPString *script, | |
372 NPVariant *result); | |
373 bool NPN_GetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName, | |
374 NPVariant *result); | |
375 bool NPN_SetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName, | |
376 const NPVariant *value); | |
377 bool NPN_RemoveProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName); | |
378 bool NPN_HasProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName); | |
379 bool NPN_HasMethod(NPP npp, NPObject *npobj, NPIdentifier methodName); | |
380 bool NPN_Enumerate(NPP npp, NPObject *npobj, NPIdentifier **identifier, | |
381 uint32_t *count); | |
382 bool NPN_Construct(NPP npp, NPObject *npobj, const NPVariant *args, | |
383 uint32_t argCount, NPVariant *result); | |
384 | |
385 /* | |
386 NPN_SetException may be called to trigger a script exception upon | |
387 return from entry points into NPObjects. Typical usage: | |
388 | |
389 NPN_SetException (npobj, message); | |
390 */ | |
391 void NPN_SetException(NPObject *npobj, const NPUTF8 *message); | |
392 | |
393 #ifdef __cplusplus | |
394 } | |
395 #endif | |
396 | |
397 #endif | |
OLD | NEW |