1
/* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
3
* Copyright � 2004, Apple Computer, Inc. and The Mozilla Foundation.
6
* Redistribution and use in source and binary forms, with or without
7
* modification, are permitted provided that the following conditions are
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.
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.
32
* Revision 1 (March 4, 2004):
35
* Revision 2 (March 10, 2004):
36
* All calls into script were made asynchronous. Results are
37
* provided via the NPScriptResultFunctionPtr callback.
39
* Revision 3 (March 10, 2004):
40
* Corrected comments to not refer to class retain/release FunctionPtrs.
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().
48
* Revision 5 (March 17, 2004):
49
* Added context parameter to result callbacks from ScriptObject functions.
51
* Revision 6 (March 29, 2004):
52
* Renamed functions implemented by user agent to NPN_*. Removed _ from
54
* Renamed "JavaScript" types to "Script".
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.
61
* Revision 8 (July 9, 2004):
62
* Updated to joint Apple-Mozilla license.
65
#ifndef _NP_RUNTIME_H_
66
#define _NP_RUNTIME_H_
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.
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.
87
The following NP{N|P}Variables were added to the Netscape plugin
91
NPNVPluginElementNPObject
92
NPPVpluginScriptableNPObject
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
101
To the extent possible the assumptions about the scripting
102
language used by the scripting environment have been minimized.
105
#define NP_BEGIN_MACRO do {
106
#define NP_END_MACRO } while (0)
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.
113
typedef struct NPObject NPObject;
114
typedef struct NPClass NPClass;
117
typedef struct _NPString {
118
const NPUTF8 *utf8characters;
127
NPVariantType_Double,
128
NPVariantType_String,
132
typedef struct _NPVariant {
138
NPString stringValue;
139
NPObject *objectValue;
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)
150
After calling NPN_ReleaseVariantValue, the type of the variant
151
will be NPVariantType_Void.
153
void NPN_ReleaseVariantValue(NPVariant *variant);
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)
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)
169
#define VOID_TO_NPVARIANT(_v) \
171
(_v).type = NPVariantType_Void; \
172
(_v).value.objectValue = NULL; \
175
#define NULL_TO_NPVARIANT(_v) \
177
(_v).type = NPVariantType_Null; \
178
(_v).value.objectValue = NULL; \
181
#define BOOLEAN_TO_NPVARIANT(_val, _v) \
183
(_v).type = NPVariantType_Bool; \
184
(_v).value.boolValue = !!(_val); \
187
#define INT32_TO_NPVARIANT(_val, _v) \
189
(_v).type = NPVariantType_Int32; \
190
(_v).value.intValue = _val; \
193
#define DOUBLE_TO_NPVARIANT(_val, _v) \
195
(_v).type = NPVariantType_Double; \
196
(_v).value.doubleValue = _val; \
199
#define STRINGZ_TO_NPVARIANT(_val, _v) \
201
(_v).type = NPVariantType_String; \
202
NPString str = { _val, strlen(_val) }; \
203
(_v).value.stringValue = str; \
206
#define STRINGN_TO_NPVARIANT(_val, _len, _v) \
208
(_v).type = NPVariantType_String; \
209
NPString str = { _val, _len }; \
210
(_v).value.stringValue = str; \
213
#define OBJECT_TO_NPVARIANT(_val, _v) \
215
(_v).type = NPVariantType_Object; \
216
(_v).value.objectValue = _val; \
221
Type mappings (JavaScript types have been used for illustration
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
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
242
typedef void *NPIdentifier;
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.
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);
260
The NPUTF8 returned from NPN_UTF8FromIdentifier SHOULD be freed.
262
NPUTF8 *NPN_UTF8FromIdentifier(NPIdentifier identifier);
265
Get the integer represented by identifier. If identifier is not an
266
integer identifier, the behaviour is undefined.
268
int32_t NPN_IntFromIdentifier(NPIdentifier identifier);
271
NPObject behavior is implemented using the following set of
274
The NPVariant *result argument of these functions (where
275
applicable) should be released using NPN_ReleaseVariantValue().
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,
284
typedef bool (*NPInvokeDefaultFunctionPtr)(NPObject *npobj,
285
const NPVariant *args,
288
typedef bool (*NPHasPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name);
289
typedef bool (*NPGetPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name,
291
typedef bool (*NPSetPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name,
292
const NPVariant *value);
293
typedef bool (*NPRemovePropertyFunctionPtr)(NPObject *npobj,
295
typedef bool (*NPEnumerationFunctionPtr)(NPObject *npobj, NPIdentifier **value,
297
typedef bool (*NPConstructFunctionPtr)(NPObject *npobj,
298
const NPVariant *args,
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.
308
NPInvokeFunctionPtr function may return 0 to indicate a void
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
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().
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;
342
#define NP_CLASS_STRUCT_VERSION 3
344
#define NP_CLASS_STRUCT_VERSION_ENUM 2
345
#define NP_CLASS_STRUCT_VERSION_CTOR 3
347
#define NP_CLASS_STRUCT_VERSION_HAS_ENUM(npclass) \
348
((npclass)->structVersion >= NP_CLASS_STRUCT_VERSION_ENUM)
350
#define NP_CLASS_STRUCT_VERSION_HAS_CTOR(npclass) \
351
((npclass)->structVersion >= NP_CLASS_STRUCT_VERSION_CTOR)
355
uint32_t referenceCount;
357
* Additional space may be allocated here by types of NPObjects
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
367
NPObject *NPN_CreateObject(NPP npp, NPClass *aClass);
370
Increment the NPObject's reference count.
372
NPObject *NPN_RetainObject(NPObject *npobj);
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.
379
void NPN_ReleaseObject(NPObject *npobj);
382
Functions to access script objects represented by NPObject.
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.
389
Calls made from plugin code to script must be made from the thread
390
on which the plugin was initialized.
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,
399
bool NPN_GetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName,
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,
408
bool NPN_Construct(NPP npp, NPObject *npobj, const NPVariant *args,
409
uint32_t argCount, NPVariant *result);
412
NPN_SetException may be called to trigger a script exception upon
413
return from entry points into NPObjects. Typical usage:
415
NPN_SetException (npobj, message);
417
void NPN_SetException(NPObject *npobj, const NPUTF8 *message);
added
removed
browser-plugin/npruntime.h
