1/*
2 * Copyright (C) 2004, Apple Computer, Inc. and The Mozilla Foundation.
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are
7 * met:
8 *
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.
18 *
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.
30 *
31 * Revision 1 (March 4, 2004):
32 * Initial proposal.
33 *
34 * Revision 2 (March 10, 2004):
35 * All calls into script were made asynchronous.  Results are
36 * provided via the NPScriptResultFunctionPtr callback.
37 *
38 * Revision 3 (March 10, 2004):
39 * Corrected comments to not refer to class retain/release FunctionPtrs.
40 *
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().
46 *
47 * Revision 5 (March 17, 2004):
48 * Added context parameter to result callbacks from ScriptObject functions.
49 *
50 * Revision 6 (March 29, 2004):
51 * Renamed functions implemented by user agent to NPN_*.  Removed _ from
52 * type names.
53 * Renamed "JavaScript" types to "Script".
54 *
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.
59 *
60 * Revision 8 (July 9, 2004):
61 * Updated to joint Apple-Mozilla license.
62 *
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.
67 */
68#ifndef _NP_RUNTIME_H_
69#define _NP_RUNTIME_H_
70
71#ifdef __cplusplus
72extern "C" {
73#endif
74
75#include <stdint.h>
76#include "npapi.h"
77
78/*
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.
83
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.
90
91    The following NP{N|P}Variables were added to the Netscape plugin
92    API (in npapi.h):
93
94    NPNVWindowNPObject
95    NPNVPluginElementNPObject
96    NPPVpluginScriptableNPObject
97
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
103    header.
104
105    To the extent possible the assumptions about the scripting
106    language used by the scripting environment have been minimized.
107*/
108
109
110/*
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.
114*/
115typedef struct NPObject NPObject;
116typedef struct NPClass NPClass;
117
118typedef char NPUTF8;
119typedef struct _NPString {
120    const NPUTF8 *UTF8Characters;
121    uint32_t UTF8Length;
122} NPString;
123
124typedef enum {
125    NPVariantType_Void,
126    NPVariantType_Null,
127    NPVariantType_Bool,
128    NPVariantType_Int32,
129    NPVariantType_Double,
130    NPVariantType_String,
131    NPVariantType_Object
132} NPVariantType;
133
134typedef struct _NPVariant {
135    NPVariantType type;
136    union {
137        bool boolValue;
138        int32_t intValue;
139        double doubleValue;
140        NPString stringValue;
141        NPObject *objectValue;
142    } value;
143} NPVariant;
144
145/*
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.
151
152    After calling NPReleaseVariantValue, the type of the variant will
153    be set to NPVariantUndefinedType.
154*/
155void NPN_ReleaseVariantValue (NPVariant *variant);
156
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)
164
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)
170
171#define NP_BEGIN_MACRO  do {
172#define NP_END_MACRO    } while (0)
173
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
182
183/*
184        Type mappings (JavaScript types have been used for illustration
185    purposes):
186
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
194
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
203*/
204
205typedef void *NPIdentifier;
206
207/*
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.
215*/
216NPIdentifier NPN_GetStringIdentifier(const NPUTF8 *name);
217void NPN_GetStringIdentifiers(const NPUTF8 **names, int32_t nameCount, NPIdentifier *identifiers);
218NPIdentifier NPN_GetIntIdentifier(int32_t intid);
219bool NPN_IdentifierIsString(NPIdentifier identifier);
220
221/*
222    The NPUTF8 returned from NPN_UTF8FromIdentifier SHOULD be freed.
223*/
224NPUTF8 *NPN_UTF8FromIdentifier(NPIdentifier identifier);
225
226/*
227    Get the integer represented by identifier. If identifier is not an
228    integer identifier, the behaviour is undefined.
229*/
230int32_t NPN_IntFromIdentifier(NPIdentifier identifier);
231
232/*
233    NPObject behavior is implemented using the following set of
234    callback functions.
235
236    The NPVariant *result argument of these functions (where
237    applicable) should be released using NPN_ReleaseVariantValue().
238*/
239typedef NPObject *(*NPAllocateFunctionPtr)(NPP npp, NPClass *aClass);
240typedef void (*NPDeallocateFunctionPtr)(NPObject *obj);
241typedef void (*NPInvalidateFunctionPtr)(NPObject *obj);
242typedef bool (*NPHasMethodFunctionPtr)(NPObject *obj, NPIdentifier name);
243typedef bool (*NPInvokeFunctionPtr)(NPObject *obj, NPIdentifier name, const NPVariant *args, uint32_t argCount, NPVariant *result);
244typedef bool (*NPInvokeDefaultFunctionPtr)(NPObject *npobj, const NPVariant *args, uint32_t argCount, NPVariant *result);
245typedef bool (*NPHasPropertyFunctionPtr)(NPObject *obj, NPIdentifier name);
246typedef bool (*NPGetPropertyFunctionPtr)(NPObject *obj, NPIdentifier name, NPVariant *result);
247typedef bool (*NPSetPropertyFunctionPtr)(NPObject *obj, NPIdentifier name, const NPVariant *value);
248typedef bool (*NPRemovePropertyFunctionPtr)(NPObject *npobj, NPIdentifier name);
249typedef bool (*NPEnumerationFunctionPtr)(NPObject *npobj, NPIdentifier **value, uint32_t *count);
250typedef bool (*NPConstructFunctionPtr)(NPObject *npobj, const NPVariant *args, uint32_t argCount, NPVariant *result);
251
252/*
253    NPObjects returned by create have a reference count of one.  It is the caller's responsibility
254    to release the returned object.
255
256    NPInvokeFunctionPtr function may return false to indicate a the method could not be invoked.
257
258    NPGetPropertyFunctionPtr and NPSetPropertyFunctionPtr may return false to indicate a property doesn't
259    exist.
260
261    NPInvalidateFunctionPtr is called by the scripting environment when the native code is
262    shutdown.  Any attempt to message a NPObject instance after the invalidate
263    callback has been called will result in undefined behavior, even if the
264    native code is still retaining those NPObject instances.
265    (The runtime will typically return immediately, with 0 or NULL, from an attempt to
266    dispatch to a NPObject, but this behavior should not be depended upon.)
267
268    The NPEnumerationFunctionPtr function may pass an array of
269    NPIdentifiers back to the caller. The callee allocs the memory of
270    the array using NPN_MemAlloc(), and it's the caller's responsibility
271    to release it using NPN_MemFree().
272*/
273struct NPClass
274{
275    uint32_t structVersion;
276    NPAllocateFunctionPtr allocate;
277    NPDeallocateFunctionPtr deallocate;
278    NPInvalidateFunctionPtr invalidate;
279    NPHasMethodFunctionPtr hasMethod;
280    NPInvokeFunctionPtr invoke;
281    NPInvokeDefaultFunctionPtr invokeDefault;
282    NPHasPropertyFunctionPtr hasProperty;
283    NPGetPropertyFunctionPtr getProperty;
284    NPSetPropertyFunctionPtr setProperty;
285    NPRemovePropertyFunctionPtr removeProperty;
286    NPEnumerationFunctionPtr enumerate;
287    NPConstructFunctionPtr construct;
288};
289
290#define NP_CLASS_STRUCT_VERSION      3
291#define NP_CLASS_STRUCT_VERSION_ENUM 2
292#define NP_CLASS_STRUCT_VERSION_CTOR 3
293
294#define NP_CLASS_STRUCT_VERSION_HAS_ENUM(npclass)   \
295    ((npclass)->structVersion >= NP_CLASS_STRUCT_VERSION_ENUM)
296#define NP_CLASS_STRUCT_VERSION_HAS_CTOR(npclass)   \
297    ((npclass)->structVersion >= NP_CLASS_STRUCT_VERSION_CTOR)
298
299struct NPObject {
300    NPClass *_class;
301    uint32_t referenceCount;
302    // Additional space may be allocated here by types of NPObjects
303};
304
305/*
306    If the class has an allocate function, NPN_CreateObject invokes that function,
307    otherwise a NPObject is allocated and returned.  If a class has an allocate
308    function it is the responsibility of that implementation to set the initial retain
309    count to 1.
310*/
311NPObject *NPN_CreateObject(NPP npp, NPClass *aClass);
312
313/*
314    Increment the NPObject's reference count.
315*/
316NPObject *NPN_RetainObject (NPObject *obj);
317
318/*
319    Decremented the NPObject's reference count.  If the reference
320    count goes to zero, the class's destroy function is invoke if
321    specified, otherwise the object is freed directly.
322*/
323void NPN_ReleaseObject (NPObject *obj);
324
325/*
326    Functions to access script objects represented by NPObject.
327
328    Calls to script objects are synchronous.  If a function returns a
329    value, it will be supplied via the result NPVariant
330    argument. Successful calls will return true, false will be
331    returned in case of an error.
332
333    Calls made from plugin code to script must be made from the thread
334    on which the plugin was initialized.
335*/
336bool NPN_Invoke(NPP npp, NPObject *npobj, NPIdentifier methodName, const NPVariant *args, uint32_t argCount, NPVariant *result);
337bool NPN_InvokeDefault(NPP npp, NPObject *npobj, const NPVariant *args, uint32_t argCount, NPVariant *result);
338bool NPN_Evaluate(NPP npp, NPObject *npobj, NPString *script, NPVariant *result);
339bool NPN_GetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName, NPVariant *result);
340bool NPN_SetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName, const NPVariant *value);
341bool NPN_RemoveProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName);
342bool NPN_HasProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName);
343bool NPN_HasMethod(NPP npp, NPObject *npobj, NPIdentifier methodName);
344bool NPN_Enumerate(NPP npp, NPObject *npobj, NPIdentifier **identifier, uint32_t *count);
345bool NPN_Construct(NPP npp, NPObject *npobj, const NPVariant *args, uint32_t argCount, NPVariant *result);
346
347/*
348    NPN_SetException may be called to trigger a script exception upon return
349    from entry points into NPObjects.
350*/
351void NPN_SetException (NPObject *obj, const NPUTF8 *message);
352
353#ifdef __cplusplus
354}
355#endif
356
357#endif
358