|
1 /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ |
|
2 /* |
|
3 * Copyright © 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 * Revision 1 (March 4, 2004): |
|
33 * Initial proposal. |
|
34 * |
|
35 * Revision 2 (March 10, 2004): |
|
36 * All calls into script were made asynchronous. Results are |
|
37 * provided via the NPScriptResultFunctionPtr callback. |
|
38 * |
|
39 * Revision 3 (March 10, 2004): |
|
40 * Corrected comments to not refer to class retain/release FunctionPtrs. |
|
41 * |
|
42 * Revision 4 (March 11, 2004): |
|
43 * Added additional convenience NPN_SetExceptionWithUTF8(). |
|
44 * Changed NPHasPropertyFunctionPtr and NPHasMethodFunctionPtr to take NPClass |
|
45 * pointers instead of NPObject pointers. |
|
46 * Added NPIsValidIdentifier(). |
|
47 * |
|
48 * Revision 5 (March 17, 2004): |
|
49 * Added context parameter to result callbacks from ScriptObject functions. |
|
50 * |
|
51 * Revision 6 (March 29, 2004): |
|
52 * Renamed functions implemented by user agent to NPN_*. Removed _ from |
|
53 * type names. |
|
54 * Renamed "JavaScript" types to "Script". |
|
55 * |
|
56 * Revision 7 (April 21, 2004): |
|
57 * NPIdentifier becomes a void*, was int32_t |
|
58 * Remove NP_IsValidIdentifier, renamed NP_IdentifierFromUTF8 to NP_GetIdentifier |
|
59 * Added NPVariant and modified functions to use this new type. |
|
60 * |
|
61 * Revision 8 (July 9, 2004): |
|
62 * Updated to joint Apple-Mozilla license. |
|
63 * |
|
64 */ |
|
65 #ifndef _NP_RUNTIME_H_ |
|
66 #define _NP_RUNTIME_H_ |
|
67 |
|
68 #ifdef __cplusplus |
|
69 extern "C" { |
|
70 #endif |
|
71 |
|
72 #include "nptypes.h" |
|
73 |
|
74 /* |
|
75 This API is used to facilitate binding code written in C to script |
|
76 objects. The API in this header does not assume the presence of a |
|
77 user agent. That is, it can be used to bind C code to scripting |
|
78 environments outside of the context of a user agent. |
|
79 |
|
80 However, the normal use of the this API is in the context of a |
|
81 scripting environment running in a browser or other user agent. |
|
82 In particular it is used to support the extended Netscape |
|
83 script-ability API for plugins (NP-SAP). NP-SAP is an extension |
|
84 of the Netscape plugin API. As such we have adopted the use of |
|
85 the "NP" prefix for this API. |
|
86 |
|
87 The following NP{N|P}Variables were added to the Netscape plugin |
|
88 API (in npapi.h): |
|
89 |
|
90 NPNVWindowNPObject |
|
91 NPNVPluginElementNPObject |
|
92 NPPVpluginScriptableNPObject |
|
93 |
|
94 These variables are exposed through NPN_GetValue() and |
|
95 NPP_GetValue() (respectively) and are used to establish the |
|
96 initial binding between the user agent and native code. The DOM |
|
97 objects in the user agent can be examined and manipulated using |
|
98 the NPN_ functions that operate on NPObjects described in this |
|
99 header. |
|
100 |
|
101 To the extent possible the assumptions about the scripting |
|
102 language used by the scripting environment have been minimized. |
|
103 */ |
|
104 |
|
105 #define NP_BEGIN_MACRO do { |
|
106 #define NP_END_MACRO } while (0) |
|
107 |
|
108 /* |
|
109 Objects (non-primitive data) passed between 'C' and script is |
|
110 always wrapped in an NPObject. The 'interface' of an NPObject is |
|
111 described by an NPClass. |
|
112 */ |
|
113 typedef struct NPObject NPObject; |
|
114 typedef struct NPClass NPClass; |
|
115 |
|
116 typedef char NPUTF8; |
|
117 typedef struct _NPString { |
|
118 const NPUTF8 *utf8characters; |
|
119 uint32_t utf8length; |
|
120 } NPString; |
|
121 |
|
122 typedef enum { |
|
123 NPVariantType_Void, |
|
124 NPVariantType_Null, |
|
125 NPVariantType_Bool, |
|
126 NPVariantType_Int32, |
|
127 NPVariantType_Double, |
|
128 NPVariantType_String, |
|
129 NPVariantType_Object |
|
130 } NPVariantType; |
|
131 |
|
132 typedef struct _NPVariant { |
|
133 NPVariantType type; |
|
134 union { |
|
135 bool boolValue; |
|
136 int32_t intValue; |
|
137 double doubleValue; |
|
138 NPString stringValue; |
|
139 NPObject *objectValue; |
|
140 } value; |
|
141 } NPVariant; |
|
142 |
|
143 /* |
|
144 NPN_ReleaseVariantValue is called on all 'out' parameters |
|
145 references. Specifically it is to be called on variants that own |
|
146 their value, as is the case with all non-const NPVariant* |
|
147 arguments after a successful call to any methods (except this one) |
|
148 in this API. |
|
149 |
|
150 After calling NPN_ReleaseVariantValue, the type of the variant |
|
151 will be NPVariantType_Void. |
|
152 */ |
|
153 void NPN_ReleaseVariantValue(NPVariant *variant); |
|
154 |
|
155 #define NPVARIANT_IS_VOID(_v) ((_v).type == NPVariantType_Void) |
|
156 #define NPVARIANT_IS_NULL(_v) ((_v).type == NPVariantType_Null) |
|
157 #define NPVARIANT_IS_BOOLEAN(_v) ((_v).type == NPVariantType_Bool) |
|
158 #define NPVARIANT_IS_INT32(_v) ((_v).type == NPVariantType_Int32) |
|
159 #define NPVARIANT_IS_DOUBLE(_v) ((_v).type == NPVariantType_Double) |
|
160 #define NPVARIANT_IS_STRING(_v) ((_v).type == NPVariantType_String) |
|
161 #define NPVARIANT_IS_OBJECT(_v) ((_v).type == NPVariantType_Object) |
|
162 |
|
163 #define NPVARIANT_TO_BOOLEAN(_v) ((_v).value.boolValue) |
|
164 #define NPVARIANT_TO_INT32(_v) ((_v).value.intValue) |
|
165 #define NPVARIANT_TO_DOUBLE(_v) ((_v).value.doubleValue) |
|
166 #define NPVARIANT_TO_STRING(_v) ((_v).value.stringValue) |
|
167 #define NPVARIANT_TO_OBJECT(_v) ((_v).value.objectValue) |
|
168 |
|
169 #define VOID_TO_NPVARIANT(_v) \ |
|
170 NP_BEGIN_MACRO \ |
|
171 (_v).type = NPVariantType_Void; \ |
|
172 (_v).value.objectValue = NULL; \ |
|
173 NP_END_MACRO |
|
174 |
|
175 #define NULL_TO_NPVARIANT(_v) \ |
|
176 NP_BEGIN_MACRO \ |
|
177 (_v).type = NPVariantType_Null; \ |
|
178 (_v).value.objectValue = NULL; \ |
|
179 NP_END_MACRO |
|
180 |
|
181 #define BOOLEAN_TO_NPVARIANT(_val, _v) \ |
|
182 NP_BEGIN_MACRO \ |
|
183 (_v).type = NPVariantType_Bool; \ |
|
184 (_v).value.boolValue = !!(_val); \ |
|
185 NP_END_MACRO |
|
186 |
|
187 #define INT32_TO_NPVARIANT(_val, _v) \ |
|
188 NP_BEGIN_MACRO \ |
|
189 (_v).type = NPVariantType_Int32; \ |
|
190 (_v).value.intValue = _val; \ |
|
191 NP_END_MACRO |
|
192 |
|
193 #define DOUBLE_TO_NPVARIANT(_val, _v) \ |
|
194 NP_BEGIN_MACRO \ |
|
195 (_v).type = NPVariantType_Double; \ |
|
196 (_v).value.doubleValue = _val; \ |
|
197 NP_END_MACRO |
|
198 |
|
199 #define STRINGZ_TO_NPVARIANT(_val, _v) \ |
|
200 NP_BEGIN_MACRO \ |
|
201 (_v).type = NPVariantType_String; \ |
|
202 NPString str = { _val, strlen(_val) }; \ |
|
203 (_v).value.stringValue = str; \ |
|
204 NP_END_MACRO |
|
205 |
|
206 #define STRINGN_TO_NPVARIANT(_val, _len, _v) \ |
|
207 NP_BEGIN_MACRO \ |
|
208 (_v).type = NPVariantType_String; \ |
|
209 NPString str = { _val, _len }; \ |
|
210 (_v).value.stringValue = str; \ |
|
211 NP_END_MACRO |
|
212 |
|
213 #define OBJECT_TO_NPVARIANT(_val, _v) \ |
|
214 NP_BEGIN_MACRO \ |
|
215 (_v).type = NPVariantType_Object; \ |
|
216 (_v).value.objectValue = _val; \ |
|
217 NP_END_MACRO |
|
218 |
|
219 |
|
220 /* |
|
221 Type mappings (JavaScript types have been used for illustration |
|
222 purposes): |
|
223 |
|
224 JavaScript to C (NPVariant with type:) |
|
225 undefined NPVariantType_Void |
|
226 null NPVariantType_Null |
|
227 Boolean NPVariantType_Bool |
|
228 Number NPVariantType_Double or NPVariantType_Int32 |
|
229 String NPVariantType_String |
|
230 Object NPVariantType_Object |
|
231 |
|
232 C (NPVariant with type:) to JavaScript |
|
233 NPVariantType_Void undefined |
|
234 NPVariantType_Null null |
|
235 NPVariantType_Bool Boolean |
|
236 NPVariantType_Int32 Number |
|
237 NPVariantType_Double Number |
|
238 NPVariantType_String String |
|
239 NPVariantType_Object Object |
|
240 */ |
|
241 |
|
242 typedef void *NPIdentifier; |
|
243 |
|
244 /* |
|
245 NPObjects have methods and properties. Methods and properties are |
|
246 identified with NPIdentifiers. These identifiers may be reflected |
|
247 in script. NPIdentifiers can be either strings or integers, IOW, |
|
248 methods and properties can be identified by either strings or |
|
249 integers (i.e. foo["bar"] vs foo[1]). NPIdentifiers can be |
|
250 compared using ==. In case of any errors, the requested |
|
251 NPIdentifier(s) will be NULL. |
|
252 */ |
|
253 NPIdentifier NPN_GetStringIdentifier(const NPUTF8 *name); |
|
254 void NPN_GetStringIdentifiers(const NPUTF8 **names, int32_t nameCount, |
|
255 NPIdentifier *identifiers); |
|
256 NPIdentifier NPN_GetIntIdentifier(int32_t intid); |
|
257 bool NPN_IdentifierIsString(NPIdentifier identifier); |
|
258 |
|
259 /* |
|
260 The NPUTF8 returned from NPN_UTF8FromIdentifier SHOULD be freed. |
|
261 */ |
|
262 NPUTF8 *NPN_UTF8FromIdentifier(NPIdentifier identifier); |
|
263 |
|
264 /* |
|
265 Get the integer represented by identifier. If identifier is not an |
|
266 integer identifier, the behaviour is undefined. |
|
267 */ |
|
268 int32_t NPN_IntFromIdentifier(NPIdentifier identifier); |
|
269 |
|
270 /* |
|
271 NPObject behavior is implemented using the following set of |
|
272 callback functions. |
|
273 |
|
274 The NPVariant *result argument of these functions (where |
|
275 applicable) should be released using NPN_ReleaseVariantValue(). |
|
276 */ |
|
277 typedef NPObject *(*NPAllocateFunctionPtr)(NPP npp, NPClass *aClass); |
|
278 typedef void (*NPDeallocateFunctionPtr)(NPObject *npobj); |
|
279 typedef void (*NPInvalidateFunctionPtr)(NPObject *npobj); |
|
280 typedef bool (*NPHasMethodFunctionPtr)(NPObject *npobj, NPIdentifier name); |
|
281 typedef bool (*NPInvokeFunctionPtr)(NPObject *npobj, NPIdentifier name, |
|
282 const NPVariant *args, uint32_t argCount, |
|
283 NPVariant *result); |
|
284 typedef bool (*NPInvokeDefaultFunctionPtr)(NPObject *npobj, |
|
285 const NPVariant *args, |
|
286 uint32_t argCount, |
|
287 NPVariant *result); |
|
288 typedef bool (*NPHasPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name); |
|
289 typedef bool (*NPGetPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name, |
|
290 NPVariant *result); |
|
291 typedef bool (*NPSetPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name, |
|
292 const NPVariant *value); |
|
293 typedef bool (*NPRemovePropertyFunctionPtr)(NPObject *npobj, |
|
294 NPIdentifier name); |
|
295 typedef bool (*NPEnumerationFunctionPtr)(NPObject *npobj, NPIdentifier **value, |
|
296 uint32_t *count); |
|
297 typedef bool (*NPConstructFunctionPtr)(NPObject *npobj, |
|
298 const NPVariant *args, |
|
299 uint32_t argCount, |
|
300 NPVariant *result); |
|
301 |
|
302 /* |
|
303 NPObjects returned by create, retain, invoke, and getProperty pass |
|
304 a reference count to the caller. That is, the callee adds a |
|
305 reference count which passes to the caller. It is the caller's |
|
306 responsibility to release the returned object. |
|
307 |
|
308 NPInvokeFunctionPtr function may return 0 to indicate a void |
|
309 result. |
|
310 |
|
311 NPInvalidateFunctionPtr is called by the scripting environment |
|
312 when the native code is shutdown. Any attempt to message a |
|
313 NPObject instance after the invalidate callback has been |
|
314 called will result in undefined behavior, even if the native code |
|
315 is still retaining those NPObject instances. (The runtime |
|
316 will typically return immediately, with 0 or NULL, from an attempt |
|
317 to dispatch to a NPObject, but this behavior should not be |
|
318 depended upon.) |
|
319 |
|
320 The NPEnumerationFunctionPtr function may pass an array of |
|
321 NPIdentifiers back to the caller. The callee allocs the memory of |
|
322 the array using NPN_MemAlloc(), and it's the caller's responsibility |
|
323 to release it using NPN_MemFree(). |
|
324 */ |
|
325 struct NPClass |
|
326 { |
|
327 uint32_t structVersion; |
|
328 NPAllocateFunctionPtr allocate; |
|
329 NPDeallocateFunctionPtr deallocate; |
|
330 NPInvalidateFunctionPtr invalidate; |
|
331 NPHasMethodFunctionPtr hasMethod; |
|
332 NPInvokeFunctionPtr invoke; |
|
333 NPInvokeDefaultFunctionPtr invokeDefault; |
|
334 NPHasPropertyFunctionPtr hasProperty; |
|
335 NPGetPropertyFunctionPtr getProperty; |
|
336 NPSetPropertyFunctionPtr setProperty; |
|
337 NPRemovePropertyFunctionPtr removeProperty; |
|
338 NPEnumerationFunctionPtr enumerate; |
|
339 NPConstructFunctionPtr construct; |
|
340 }; |
|
341 |
|
342 #define NP_CLASS_STRUCT_VERSION 3 |
|
343 |
|
344 #define NP_CLASS_STRUCT_VERSION_ENUM 2 |
|
345 #define NP_CLASS_STRUCT_VERSION_CTOR 3 |
|
346 |
|
347 #define NP_CLASS_STRUCT_VERSION_HAS_ENUM(npclass) \ |
|
348 ((npclass)->structVersion >= NP_CLASS_STRUCT_VERSION_ENUM) |
|
349 |
|
350 #define NP_CLASS_STRUCT_VERSION_HAS_CTOR(npclass) \ |
|
351 ((npclass)->structVersion >= NP_CLASS_STRUCT_VERSION_CTOR) |
|
352 |
|
353 struct NPObject { |
|
354 NPClass *_class; |
|
355 uint32_t referenceCount; |
|
356 /* |
|
357 * Additional space may be allocated here by types of NPObjects |
|
358 */ |
|
359 }; |
|
360 |
|
361 /* |
|
362 If the class has an allocate function, NPN_CreateObject invokes |
|
363 that function, otherwise a NPObject is allocated and |
|
364 returned. This method will initialize the referenceCount member of |
|
365 the NPObject to 1. |
|
366 */ |
|
367 NPObject *NPN_CreateObject(NPP npp, NPClass *aClass); |
|
368 |
|
369 /* |
|
370 Increment the NPObject's reference count. |
|
371 */ |
|
372 NPObject *NPN_RetainObject(NPObject *npobj); |
|
373 |
|
374 /* |
|
375 Decremented the NPObject's reference count. If the reference |
|
376 count goes to zero, the class's destroy function is invoke if |
|
377 specified, otherwise the object is freed directly. |
|
378 */ |
|
379 void NPN_ReleaseObject(NPObject *npobj); |
|
380 |
|
381 /* |
|
382 Functions to access script objects represented by NPObject. |
|
383 |
|
384 Calls to script objects are synchronous. If a function returns a |
|
385 value, it will be supplied via the result NPVariant |
|
386 argument. Successful calls will return true, false will be |
|
387 returned in case of an error. |
|
388 |
|
389 Calls made from plugin code to script must be made from the thread |
|
390 on which the plugin was initialized. |
|
391 */ |
|
392 |
|
393 bool NPN_Invoke(NPP npp, NPObject *npobj, NPIdentifier methodName, |
|
394 const NPVariant *args, uint32_t argCount, NPVariant *result); |
|
395 bool NPN_InvokeDefault(NPP npp, NPObject *npobj, const NPVariant *args, |
|
396 uint32_t argCount, NPVariant *result); |
|
397 bool NPN_Evaluate(NPP npp, NPObject *npobj, NPString *script, |
|
398 NPVariant *result); |
|
399 bool NPN_GetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName, |
|
400 NPVariant *result); |
|
401 bool NPN_SetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName, |
|
402 const NPVariant *value); |
|
403 bool NPN_RemoveProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName); |
|
404 bool NPN_HasProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName); |
|
405 bool NPN_HasMethod(NPP npp, NPObject *npobj, NPIdentifier methodName); |
|
406 bool NPN_Enumerate(NPP npp, NPObject *npobj, NPIdentifier **identifier, |
|
407 uint32_t *count); |
|
408 bool NPN_Construct(NPP npp, NPObject *npobj, const NPVariant *args, |
|
409 uint32_t argCount, NPVariant *result); |
|
410 |
|
411 /* |
|
412 NPN_SetException may be called to trigger a script exception upon |
|
413 return from entry points into NPObjects. Typical usage: |
|
414 |
|
415 NPN_SetException (npobj, message); |
|
416 */ |
|
417 void NPN_SetException(NPObject *npobj, const NPUTF8 *message); |
|
418 |
|
419 #ifdef __cplusplus |
|
420 } |
|
421 #endif |
|
422 |
|
423 #endif |