2
* Copyright (C) 2004, Apple Computer, Inc. and The Mozilla Foundation.
5
* Redistribution and use in source and binary forms, with or without
6
* modification, are permitted provided that the following conditions are
9
* 1. Redistributions of source code must retain the above copyright
10
* notice, this list of conditions and the following disclaimer.
11
* 2. Redistributions in binary form must reproduce the above copyright
12
* notice, this list of conditions and the following disclaimer in the
13
* documentation and/or other materials provided with the distribution.
14
* 3. Neither the names of Apple Computer, Inc. ("Apple") or The Mozilla
15
* Foundation ("Mozilla") nor the names of their contributors may be used
16
* to endorse or promote products derived from this software without
17
* specific prior written permission.
19
* THIS SOFTWARE IS PROVIDED BY APPLE, MOZILLA AND THEIR CONTRIBUTORS "AS
20
* IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
21
* TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
22
* PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE, MOZILLA OR
23
* THEIR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
25
* TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
26
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
27
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
28
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
29
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31
* Revision 1 (March 4, 2004):
34
* Revision 2 (March 10, 2004):
35
* All calls into script were made asynchronous. Results are
36
* provided via the NPScriptResultFunctionPtr callback.
38
* Revision 3 (March 10, 2004):
39
* Corrected comments to not refer to class retain/release FunctionPtrs.
41
* Revision 4 (March 11, 2004):
42
* Added additional convenience NPN_SetExceptionWithUTF8().
43
* Changed NPHasPropertyFunctionPtr and NPHasMethodFunctionPtr to take NPClass
44
* pointers instead of NPObject pointers.
45
* Added NPIsValidIdentifier().
47
* Revision 5 (March 17, 2004):
48
* Added context parameter to result callbacks from ScriptObject functions.
50
* Revision 6 (March 29, 2004):
51
* Renamed functions implemented by user agent to NPN_*. Removed _ from
53
* Renamed "JavaScript" types to "Script".
55
* Revision 7 (April 21, 2004):
56
* NPIdentifier becomes a void*, was int32_t
57
* Remove NP_IsValidIdentifier, renamed NP_IdentifierFromUTF8 to NP_GetIdentifier
58
* Added NPVariant and modified functions to use this new type.
60
* Revision 8 (July 9, 2004):
61
* Updated to joint Apple-Mozilla license.
63
* Revision 9 (August 12, 2004):
64
* Changed NPVariantType enum values to form PVariantType_XXX
65
* Added NPP arguments to NPObject functions.
66
* Replaced NPVariant functions with macros.
68
#ifndef _NP_RUNTIME_H_
69
#define _NP_RUNTIME_H_
79
This API is used to facilitate binding code written in C to script
80
objects. The API in this header does not assume the presence of a
81
user agent. That is, it can be used to bind C code to scripting
82
environments outside of the context of a user agent.
84
However, the normal use of the this API is in the context of a
85
scripting environment running in a browser or other user agent.
86
In particular it is used to support the extended Netscape
87
script-ability API for plugins (NP-SAP). NP-SAP is an extension
88
of the Netscape plugin API. As such we have adopted the use of
89
the "NP" prefix for this API.
91
The following NP{N|P}Variables were added to the Netscape plugin
95
NPNVPluginElementNPObject
96
NPPVpluginScriptableNPObject
98
These variables are exposed through NPN_GetValue() and
99
NPP_GetValue() (respectively) and are used to establish the
100
initial binding between the user agent and native code. The DOM
101
objects in the user agent can be examined and manipulated using
102
the NPN_ functions that operate on NPObjects described in this
105
To the extent possible the assumptions about the scripting
106
language used by the scripting environment have been minimized.
111
Objects (non-primitive data) passed between 'C' and script is
112
always wrapped in an NPObject. The 'interface' of an NPObject is
113
described by an NPClass.
115
typedef struct NPObject NPObject;
116
typedef struct NPClass NPClass;
119
typedef struct _NPString {
120
const NPUTF8 *UTF8Characters;
129
NPVariantType_Double,
130
NPVariantType_String,
134
typedef struct _NPVariant {
140
NPString stringValue;
141
NPObject *objectValue;
146
NPN_ReleaseVariantValue is called on all 'out' parameters references.
147
Specifically it is called on variants that are resultant out parameters
148
in NPGetPropertyFunctionPtr and NPInvokeFunctionPtr. Resultant variants
149
from these two functions should be initialized using the
150
NPN_InitializeVariantXXX() functions.
152
After calling NPReleaseVariantValue, the type of the variant will
153
be set to NPVariantUndefinedType.
155
void NPN_ReleaseVariantValue (NPVariant *variant);
157
#define NPVARIANT_IS_VOID(_v) ((_v).type == NPVariantType_Void)
158
#define NPVARIANT_IS_NULL(_v) ((_v).type == NPVariantType_Null)
159
#define NPVARIANT_IS_BOOLEAN(_v) ((_v).type == NPVariantType_Bool)
160
#define NPVARIANT_IS_INT32(_v) ((_v).type == NPVariantType_Int32)
161
#define NPVARIANT_IS_DOUBLE(_v) ((_v).type == NPVariantType_Double)
162
#define NPVARIANT_IS_STRING(_v) ((_v).type == NPVariantType_String)
163
#define NPVARIANT_IS_OBJECT(_v) ((_v).type == NPVariantType_Object)
165
#define NPVARIANT_TO_BOOLEAN(_v) ((_v).value.boolValue)
166
#define NPVARIANT_TO_INT32(_v) ((_v).value.intValue)
167
#define NPVARIANT_TO_DOUBLE(_v) ((_v).value.doubleValue)
168
#define NPVARIANT_TO_STRING(_v) ((_v).value.stringValue)
169
#define NPVARIANT_TO_OBJECT(_v) ((_v).value.objectValue)
171
#define NP_BEGIN_MACRO do {
172
#define NP_END_MACRO } while (0)
174
#define VOID_TO_NPVARIANT(_v) NP_BEGIN_MACRO (_v).type = NPVariantType_Void; (_v).value.objectValue = NULL; NP_END_MACRO
175
#define NULL_TO_NPVARIANT(_v) NP_BEGIN_MACRO (_v).type = NPVariantType_Null; (_v).value.objectValue = NULL; NP_END_MACRO
176
#define BOOLEAN_TO_NPVARIANT(_val, _v) NP_BEGIN_MACRO (_v).type = NPVariantType_Bool; (_v).value.boolValue = !!(_val); NP_END_MACRO
177
#define INT32_TO_NPVARIANT(_val, _v) NP_BEGIN_MACRO (_v).type = NPVariantType_Int32; (_v).value.intValue = _val; NP_END_MACRO
178
#define DOUBLE_TO_NPVARIANT(_val, _v) NP_BEGIN_MACRO (_v).type = NPVariantType_Double; (_v).value.doubleValue = _val; NP_END_MACRO
179
#define STRINGZ_TO_NPVARIANT(_val, _v) NP_BEGIN_MACRO (_v).type = NPVariantType_String; NPString str = { _val, strlen(_val) }; (_v).value.stringValue = str; NP_END_MACRO
180
#define STRINGN_TO_NPVARIANT(_val, _len, _v) NP_BEGIN_MACRO (_v).type = NPVariantType_String; NPString str = { _val, _len }; (_v).value.stringValue = str; NP_END_MACRO
181
#define OBJECT_TO_NPVARIANT(_val, _v) NP_BEGIN_MACRO (_v).type = NPVariantType_Object; (_v).value.objectValue = _val; NP_END_MACRO
184
Type mappings (JavaScript types have been used for illustration
187
JavaScript to C (NPVariant with type:)
188
undefined NPVariantType_Void
189
null NPVariantType_Null
190
Boolean NPVariantType_Bool
191
Number NPVariantType_Double or NPVariantType_Int32
192
String NPVariantType_String
193
Object NPVariantType_Object
195
C (NPVariant with type:) to JavaScript
196
NPVariantType_Void undefined
197
NPVariantType_Null null
198
NPVariantType_Bool Boolean
199
NPVariantType_Int32 Number
200
NPVariantType_Double Number
201
NPVariantType_String String
202
NPVariantType_Object Object
205
typedef void *NPIdentifier;
208
NPObjects have methods and properties. Methods and properties are
209
identified with NPIdentifiers. These identifiers may be reflected
210
in script. NPIdentifiers can be either strings or integers, IOW,
211
methods and properties can be identified by either strings or
212
integers (i.e. foo["bar"] vs foo[1]). NPIdentifiers can be
213
compared using ==. In case of any errors, the requested
214
NPIdentifier(s) will be NULL.
216
NPIdentifier NPN_GetStringIdentifier(const NPUTF8 *name);
217
void NPN_GetStringIdentifiers(const NPUTF8 **names, int32_t nameCount, NPIdentifier *identifiers);
218
NPIdentifier NPN_GetIntIdentifier(int32_t intid);
219
bool NPN_IdentifierIsString(NPIdentifier identifier);
222
The NPUTF8 returned from NPN_UTF8FromIdentifier SHOULD be freed.
224
NPUTF8 *NPN_UTF8FromIdentifier(NPIdentifier identifier);
227
Get the integer represented by identifier. If identifier is not an
228
integer identifier, the behaviour is undefined.
230
int32_t NPN_IntFromIdentifier(NPIdentifier identifier);
233
NPObject behavior is implemented using the following set of
236
The NPVariant *result argument of these functions (where
237
applicable) should be released using NPN_ReleaseVariantValue().
239
typedef NPObject *(*NPAllocateFunctionPtr)(NPP npp, NPClass *aClass);
240
typedef void (*NPDeallocateFunctionPtr)(NPObject *obj);
241
typedef void (*NPInvalidateFunctionPtr)(NPObject *obj);
242
typedef bool (*NPHasMethodFunctionPtr)(NPObject *obj, NPIdentifier name);
243
typedef bool (*NPInvokeFunctionPtr)(NPObject *obj, NPIdentifier name, const NPVariant *args, uint32_t argCount, NPVariant *result);
244
typedef bool (*NPInvokeDefaultFunctionPtr)(NPObject *npobj, const NPVariant *args, uint32_t argCount, NPVariant *result);
245
typedef bool (*NPHasPropertyFunctionPtr)(NPObject *obj, NPIdentifier name);
246
typedef bool (*NPGetPropertyFunctionPtr)(NPObject *obj, NPIdentifier name, NPVariant *result);
247
typedef bool (*NPSetPropertyFunctionPtr)(NPObject *obj, NPIdentifier name, const NPVariant *value);
248
typedef bool (*NPRemovePropertyFunctionPtr)(NPObject *npobj, NPIdentifier name);
249
typedef bool (*NPEnumerationFunctionPtr)(NPObject *npobj, NPIdentifier **value, uint32_t *count);
252
NPObjects returned by create have a reference count of one. It is the caller's responsibility
253
to release the returned object.
255
NPInvokeFunctionPtr function may return false to indicate a the method could not be invoked.
257
NPGetPropertyFunctionPtr and NPSetPropertyFunctionPtr may return false to indicate a property doesn't
260
NPInvalidateFunctionPtr is called by the scripting environment when the native code is
261
shutdown. Any attempt to message a NPObject instance after the invalidate
262
callback has been called will result in undefined behavior, even if the
263
native code is still retaining those NPObject instances.
264
(The runtime will typically return immediately, with 0 or NULL, from an attempt to
265
dispatch to a NPObject, but this behavior should not be depended upon.)
267
The NPEnumerationFunctionPtr function may pass an array of
268
NPIdentifiers back to the caller. The callee allocs the memory of
269
the array using NPN_MemAlloc(), and it's the caller's responsibility
270
to release it using NPN_MemFree().
274
uint32_t structVersion;
275
NPAllocateFunctionPtr allocate;
276
NPDeallocateFunctionPtr deallocate;
277
NPInvalidateFunctionPtr invalidate;
278
NPHasMethodFunctionPtr hasMethod;
279
NPInvokeFunctionPtr invoke;
280
NPInvokeDefaultFunctionPtr invokeDefault;
281
NPHasPropertyFunctionPtr hasProperty;
282
NPGetPropertyFunctionPtr getProperty;
283
NPSetPropertyFunctionPtr setProperty;
284
NPRemovePropertyFunctionPtr removeProperty;
285
NPEnumerationFunctionPtr enumerate;
288
#define NP_CLASS_STRUCT_VERSION 2
289
#define NP_CLASS_STRUCT_VERSION_ENUM 2
290
#define NP_CLASS_STRUCT_VERSION_HAS_ENUM(npclass) \
291
((npclass)->structVersion >= NP_CLASS_STRUCT_VERSION_ENUM)
295
uint32_t referenceCount;
296
// Additional space may be allocated here by types of NPObjects
300
If the class has an allocate function, NPN_CreateObject invokes that function,
301
otherwise a NPObject is allocated and returned. If a class has an allocate
302
function it is the responsibility of that implementation to set the initial retain
305
NPObject *NPN_CreateObject(NPP npp, NPClass *aClass);
308
Increment the NPObject's reference count.
310
NPObject *NPN_RetainObject (NPObject *obj);
313
Decremented the NPObject's reference count. If the reference
314
count goes to zero, the class's destroy function is invoke if
315
specified, otherwise the object is freed directly.
317
void NPN_ReleaseObject (NPObject *obj);
320
Functions to access script objects represented by NPObject.
322
Calls to script objects are synchronous. If a function returns a
323
value, it will be supplied via the result NPVariant
324
argument. Successful calls will return true, false will be
325
returned in case of an error.
327
Calls made from plugin code to script must be made from the thread
328
on which the plugin was initialized.
330
bool NPN_Invoke(NPP npp, NPObject *npobj, NPIdentifier methodName, const NPVariant *args, uint32_t argCount, NPVariant *result);
331
bool NPN_InvokeDefault(NPP npp, NPObject *npobj, const NPVariant *args, uint32_t argCount, NPVariant *result);
332
bool NPN_Evaluate(NPP npp, NPObject *npobj, NPString *script, NPVariant *result);
333
bool NPN_GetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName, NPVariant *result);
334
bool NPN_SetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName, const NPVariant *value);
335
bool NPN_RemoveProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName);
336
bool NPN_HasProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName);
337
bool NPN_HasMethod(NPP npp, NPObject *npobj, NPIdentifier methodName);
338
bool NPN_Enumerate(NPP npp, NPObject *npobj, NPIdentifier **identifier, uint32_t *count);
339
bool NPN_Construct(NPP npp, NPObject *npobj, const NPVariant *args, uint32_t argCount, NPVariant *result);
342
NPN_SetException may be called to trigger a script exception upon return
343
from entry points into NPObjects.
345
void NPN_SetException (NPObject *obj, const NPUTF8 *message);
added
removed
browser-plugin/npruntime.h
