dom/plugins/base/npruntime.h@b8a032363ba2
dom/plugins/base/npruntime.h
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
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_
36 #ifdef __cplusplus
37 extern "C" {
38 #endif
40 #include "nptypes.h"
42 /*
43 This API is used to facilitate binding code written in C to script
44 objects. The API in this header does not assume the presence of a
45 user agent. That is, it can be used to bind C code to scripting
46 environments outside of the context of a user agent.
48 However, the normal use of the this API is in the context of a
49 scripting environment running in a browser or other user agent.
50 In particular it is used to support the extended Netscape
51 script-ability API for plugins (NP-SAP). NP-SAP is an extension
52 of the Netscape plugin API. As such we have adopted the use of
53 the "NP" prefix for this API.
55 The following NP{N|P}Variables were added to the Netscape plugin
56 API (in npapi.h):
58 NPNVWindowNPObject
59 NPNVPluginElementNPObject
60 NPPVpluginScriptableNPObject
62 These variables are exposed through NPN_GetValue() and
63 NPP_GetValue() (respectively) and are used to establish the
64 initial binding between the user agent and native code. The DOM
65 objects in the user agent can be examined and manipulated using
66 the NPN_ functions that operate on NPObjects described in this
67 header.
69 To the extent possible the assumptions about the scripting
70 language used by the scripting environment have been minimized.
71 */
73 #define NP_BEGIN_MACRO do {
74 #define NP_END_MACRO } while (0)
76 /*
77 Objects (non-primitive data) passed between 'C' and script is
78 always wrapped in an NPObject. The 'interface' of an NPObject is
79 described by an NPClass.
80 */
81 typedef struct NPObject NPObject;
82 typedef struct NPClass NPClass;
84 typedef char NPUTF8;
85 typedef struct _NPString {
86 const NPUTF8 *UTF8Characters;
87 uint32_t UTF8Length;
88 } NPString;
90 typedef enum {
91 NPVariantType_Void,
92 NPVariantType_Null,
93 NPVariantType_Bool,
94 NPVariantType_Int32,
95 NPVariantType_Double,
96 NPVariantType_String,
97 NPVariantType_Object
98 } NPVariantType;
100 typedef struct _NPVariant {
101 NPVariantType type;
102 union {
103 bool boolValue;
104 int32_t intValue;
105 double doubleValue;
106 NPString stringValue;
107 NPObject *objectValue;
108 } value;
109 } NPVariant;
111 /*
112 NPN_ReleaseVariantValue is called on all 'out' parameters
113 references. Specifically it is to be called on variants that own
114 their value, as is the case with all non-const NPVariant*
115 arguments after a successful call to any methods (except this one)
116 in this API.
118 After calling NPN_ReleaseVariantValue, the type of the variant
119 will be NPVariantType_Void.
120 */
121 void NPN_ReleaseVariantValue(NPVariant *variant);
123 #define NPVARIANT_IS_VOID(_v) ((_v).type == NPVariantType_Void)
124 #define NPVARIANT_IS_NULL(_v) ((_v).type == NPVariantType_Null)
125 #define NPVARIANT_IS_BOOLEAN(_v) ((_v).type == NPVariantType_Bool)
126 #define NPVARIANT_IS_INT32(_v) ((_v).type == NPVariantType_Int32)
127 #define NPVARIANT_IS_DOUBLE(_v) ((_v).type == NPVariantType_Double)
128 #define NPVARIANT_IS_STRING(_v) ((_v).type == NPVariantType_String)
129 #define NPVARIANT_IS_OBJECT(_v) ((_v).type == NPVariantType_Object)
131 #define NPVARIANT_TO_BOOLEAN(_v) ((_v).value.boolValue)
132 #define NPVARIANT_TO_INT32(_v) ((_v).value.intValue)
133 #define NPVARIANT_TO_DOUBLE(_v) ((_v).value.doubleValue)
134 #define NPVARIANT_TO_STRING(_v) ((_v).value.stringValue)
135 #define NPVARIANT_TO_OBJECT(_v) ((_v).value.objectValue)
137 #define VOID_TO_NPVARIANT(_v) \
138 NP_BEGIN_MACRO \
139 (_v).type = NPVariantType_Void; \
140 (_v).value.objectValue = NULL; \
141 NP_END_MACRO
143 #define NULL_TO_NPVARIANT(_v) \
144 NP_BEGIN_MACRO \
145 (_v).type = NPVariantType_Null; \
146 (_v).value.objectValue = NULL; \
147 NP_END_MACRO
149 #define BOOLEAN_TO_NPVARIANT(_val, _v) \
150 NP_BEGIN_MACRO \
151 (_v).type = NPVariantType_Bool; \
152 (_v).value.boolValue = !!(_val); \
153 NP_END_MACRO
155 #define INT32_TO_NPVARIANT(_val, _v) \
156 NP_BEGIN_MACRO \
157 (_v).type = NPVariantType_Int32; \
158 (_v).value.intValue = _val; \
159 NP_END_MACRO
161 #define DOUBLE_TO_NPVARIANT(_val, _v) \
162 NP_BEGIN_MACRO \
163 (_v).type = NPVariantType_Double; \
164 (_v).value.doubleValue = _val; \
165 NP_END_MACRO
167 #define STRINGZ_TO_NPVARIANT(_val, _v) \
168 NP_BEGIN_MACRO \
169 (_v).type = NPVariantType_String; \
170 NPString str = { _val, (uint32_t)(strlen(_val)) }; \
171 (_v).value.stringValue = str; \
172 NP_END_MACRO
174 #define STRINGN_TO_NPVARIANT(_val, _len, _v) \
175 NP_BEGIN_MACRO \
176 (_v).type = NPVariantType_String; \
177 NPString str = { _val, (uint32_t)(_len) }; \
178 (_v).value.stringValue = str; \
179 NP_END_MACRO
181 #define OBJECT_TO_NPVARIANT(_val, _v) \
182 NP_BEGIN_MACRO \
183 (_v).type = NPVariantType_Object; \
184 (_v).value.objectValue = _val; \
185 NP_END_MACRO
188 /*
189 Type mappings (JavaScript types have been used for illustration
190 purposes):
192 JavaScript to C (NPVariant with type:)
193 undefined NPVariantType_Void
194 null NPVariantType_Null
195 Boolean NPVariantType_Bool
196 Number NPVariantType_Double or NPVariantType_Int32
197 String NPVariantType_String
198 Object NPVariantType_Object
200 C (NPVariant with type:) to JavaScript
201 NPVariantType_Void undefined
202 NPVariantType_Null null
203 NPVariantType_Bool Boolean
204 NPVariantType_Int32 Number
205 NPVariantType_Double Number
206 NPVariantType_String String
207 NPVariantType_Object Object
208 */
210 typedef void *NPIdentifier;
212 /*
213 NPObjects have methods and properties. Methods and properties are
214 identified with NPIdentifiers. These identifiers may be reflected
215 in script. NPIdentifiers can be either strings or integers, IOW,
216 methods and properties can be identified by either strings or
217 integers (i.e. foo["bar"] vs foo[1]). NPIdentifiers can be
218 compared using ==. In case of any errors, the requested
219 NPIdentifier(s) will be NULL. NPIdentifier lifetime is controlled
220 by the browser. Plugins do not need to worry about memory management
221 with regards to NPIdentifiers.
222 */
223 NPIdentifier NPN_GetStringIdentifier(const NPUTF8 *name);
224 void NPN_GetStringIdentifiers(const NPUTF8 **names, int32_t nameCount,
225 NPIdentifier *identifiers);
226 NPIdentifier NPN_GetIntIdentifier(int32_t intid);
227 bool NPN_IdentifierIsString(NPIdentifier identifier);
229 /*
230 The NPUTF8 returned from NPN_UTF8FromIdentifier SHOULD be freed.
231 */
232 NPUTF8 *NPN_UTF8FromIdentifier(NPIdentifier identifier);
234 /*
235 Get the integer represented by identifier. If identifier is not an
236 integer identifier, the behaviour is undefined.
237 */
238 int32_t NPN_IntFromIdentifier(NPIdentifier identifier);
240 /*
241 NPObject behavior is implemented using the following set of
242 callback functions.
244 The NPVariant *result argument of these functions (where
245 applicable) should be released using NPN_ReleaseVariantValue().
246 */
247 typedef NPObject *(*NPAllocateFunctionPtr)(NPP npp, NPClass *aClass);
248 typedef void (*NPDeallocateFunctionPtr)(NPObject *npobj);
249 typedef void (*NPInvalidateFunctionPtr)(NPObject *npobj);
250 typedef bool (*NPHasMethodFunctionPtr)(NPObject *npobj, NPIdentifier name);
251 typedef bool (*NPInvokeFunctionPtr)(NPObject *npobj, NPIdentifier name,
252 const NPVariant *args, uint32_t argCount,
253 NPVariant *result);
254 typedef bool (*NPInvokeDefaultFunctionPtr)(NPObject *npobj,
255 const NPVariant *args,
256 uint32_t argCount,
257 NPVariant *result);
258 typedef bool (*NPHasPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name);
259 typedef bool (*NPGetPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name,
260 NPVariant *result);
261 typedef bool (*NPSetPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name,
262 const NPVariant *value);
263 typedef bool (*NPRemovePropertyFunctionPtr)(NPObject *npobj,
264 NPIdentifier name);
265 typedef bool (*NPEnumerationFunctionPtr)(NPObject *npobj, NPIdentifier **value,
266 uint32_t *count);
267 typedef bool (*NPConstructFunctionPtr)(NPObject *npobj,
268 const NPVariant *args,
269 uint32_t argCount,
270 NPVariant *result);
272 /*
273 NPObjects returned by create, retain, invoke, and getProperty pass
274 a reference count to the caller. That is, the callee adds a
275 reference count which passes to the caller. It is the caller's
276 responsibility to release the returned object.
278 NPInvokeFunctionPtr function may return 0 to indicate a void
279 result.
281 NPInvalidateFunctionPtr is called by the scripting environment
282 when the native code is shutdown. Any attempt to message a
283 NPObject instance after the invalidate callback has been
284 called will result in undefined behavior, even if the native code
285 is still retaining those NPObject instances. (The runtime
286 will typically return immediately, with 0 or NULL, from an
287 attempt to dispatch to a NPObject, but this behavior should not
288 be depended upon.)
290 The NPEnumerationFunctionPtr function may pass an array of
291 NPIdentifiers back to the caller. The callee allocs the memory of
292 the array using NPN_MemAlloc(), and it's the caller's responsibility
293 to release it using NPN_MemFree().
294 */
295 struct NPClass
296 {
297 uint32_t structVersion;
298 NPAllocateFunctionPtr allocate;
299 NPDeallocateFunctionPtr deallocate;
300 NPInvalidateFunctionPtr invalidate;
301 NPHasMethodFunctionPtr hasMethod;
302 NPInvokeFunctionPtr invoke;
303 NPInvokeDefaultFunctionPtr invokeDefault;
304 NPHasPropertyFunctionPtr hasProperty;
305 NPGetPropertyFunctionPtr getProperty;
306 NPSetPropertyFunctionPtr setProperty;
307 NPRemovePropertyFunctionPtr removeProperty;
308 NPEnumerationFunctionPtr enumerate;
309 NPConstructFunctionPtr construct;
310 };
312 #define NP_CLASS_STRUCT_VERSION 3
314 #define NP_CLASS_STRUCT_VERSION_ENUM 2
315 #define NP_CLASS_STRUCT_VERSION_CTOR 3
317 #define NP_CLASS_STRUCT_VERSION_HAS_ENUM(npclass) \
318 ((npclass)->structVersion >= NP_CLASS_STRUCT_VERSION_ENUM)
320 #define NP_CLASS_STRUCT_VERSION_HAS_CTOR(npclass) \
321 ((npclass)->structVersion >= NP_CLASS_STRUCT_VERSION_CTOR)
323 struct NPObject {
324 NPClass *_class;
325 uint32_t referenceCount;
326 /*
327 * Additional space may be allocated here by types of NPObjects
328 */
329 };
331 /*
332 If the class has an allocate function, NPN_CreateObject invokes
333 that function, otherwise a NPObject is allocated and
334 returned. This method will initialize the referenceCount member of
335 the NPObject to 1.
336 */
337 NPObject *NPN_CreateObject(NPP npp, NPClass *aClass);
339 /*
340 Increment the NPObject's reference count.
341 */
342 NPObject *NPN_RetainObject(NPObject *npobj);
344 /*
345 Decremented the NPObject's reference count. If the reference
346 count goes to zero, the class's destroy function is invoke if
347 specified, otherwise the object is freed directly.
348 */
349 void NPN_ReleaseObject(NPObject *npobj);
351 /*
352 Functions to access script objects represented by NPObject.
354 Calls to script objects are synchronous. If a function returns a
355 value, it will be supplied via the result NPVariant
356 argument. Successful calls will return true, false will be
357 returned in case of an error.
359 Calls made from plugin code to script must be made from the thread
360 on which the plugin was initialized.
361 */
363 bool NPN_Invoke(NPP npp, NPObject *npobj, NPIdentifier methodName,
364 const NPVariant *args, uint32_t argCount, NPVariant *result);
365 bool NPN_InvokeDefault(NPP npp, NPObject *npobj, const NPVariant *args,
366 uint32_t argCount, NPVariant *result);
367 bool NPN_Evaluate(NPP npp, NPObject *npobj, NPString *script,
368 NPVariant *result);
369 bool NPN_GetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName,
370 NPVariant *result);
371 bool NPN_SetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName,
372 const NPVariant *value);
373 bool NPN_RemoveProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName);
374 bool NPN_HasProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName);
375 bool NPN_HasMethod(NPP npp, NPObject *npobj, NPIdentifier methodName);
376 bool NPN_Enumerate(NPP npp, NPObject *npobj, NPIdentifier **identifier,
377 uint32_t *count);
378 bool NPN_Construct(NPP npp, NPObject *npobj, const NPVariant *args,
379 uint32_t argCount, NPVariant *result);
381 /*
382 NPN_SetException may be called to trigger a script exception upon
383 return from entry points into NPObjects. Typical usage:
385 NPN_SetException (npobj, message);
386 */
387 void NPN_SetException(NPObject *npobj, const NPUTF8 *message);
389 #ifdef __cplusplus
390 }
391 #endif
393 #endif
