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