PageRenderTime 146ms CodeModel.GetById 61ms app.highlight 17ms RepoModel.GetById 63ms app.codeStats 0ms

/gecko_api/include/npruntime.h

http://firefox-mac-pdf.googlecode.com/
C++ Header | 423 lines | 173 code | 40 blank | 210 comment | 8 complexity | 8fded04d0d7cf4019a1150f48cc767ed MD5 | raw file
  1/* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
  2/*
  3 * Copyright Š 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 * Revision 1 (March 4, 2004):
 33 * Initial proposal.
 34 *
 35 * Revision 2 (March 10, 2004):
 36 * All calls into script were made asynchronous.  Results are
 37 * provided via the NPScriptResultFunctionPtr callback.
 38 *
 39 * Revision 3 (March 10, 2004):
 40 * Corrected comments to not refer to class retain/release FunctionPtrs.
 41 *
 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().
 47 *
 48 * Revision 5 (March 17, 2004):
 49 * Added context parameter to result callbacks from ScriptObject functions.
 50 *
 51 * Revision 6 (March 29, 2004):
 52 * Renamed functions implemented by user agent to NPN_*.  Removed _ from
 53 * type names.
 54 * Renamed "JavaScript" types to "Script".
 55 *
 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.
 60 *
 61 * Revision 8 (July 9, 2004):
 62 * Updated to joint Apple-Mozilla license.
 63 *
 64 */
 65#ifndef _NP_RUNTIME_H_
 66#define _NP_RUNTIME_H_
 67
 68#ifdef __cplusplus
 69extern "C" {
 70#endif
 71
 72#include "nptypes.h"
 73
 74/*
 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.
 79    
 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.
 86
 87    The following NP{N|P}Variables were added to the Netscape plugin
 88    API (in npapi.h):
 89
 90    NPNVWindowNPObject
 91    NPNVPluginElementNPObject
 92    NPPVpluginScriptableNPObject
 93
 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
 99    header.
100
101    To the extent possible the assumptions about the scripting
102    language used by the scripting environment have been minimized.
103*/
104
105#define NP_BEGIN_MACRO  do {
106#define NP_END_MACRO    } while (0)
107
108/*
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.
112*/
113typedef struct NPObject NPObject;
114typedef struct NPClass NPClass;
115
116typedef char NPUTF8;
117typedef struct _NPString {
118    const NPUTF8 *utf8characters;
119    uint32_t utf8length;
120} NPString;
121
122typedef enum {
123    NPVariantType_Void,
124    NPVariantType_Null,
125    NPVariantType_Bool,
126    NPVariantType_Int32,
127    NPVariantType_Double,
128    NPVariantType_String,
129    NPVariantType_Object
130} NPVariantType;
131
132typedef struct _NPVariant {
133    NPVariantType type;
134    union {
135        bool boolValue;
136        int32_t intValue;
137        double doubleValue;
138        NPString stringValue;
139        NPObject *objectValue;
140    } value;
141} NPVariant;
142
143/*
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)
148    in this API.
149
150    After calling NPN_ReleaseVariantValue, the type of the variant
151    will be NPVariantType_Void.
152*/
153void NPN_ReleaseVariantValue(NPVariant *variant);
154
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)
162
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)
168
169#define VOID_TO_NPVARIANT(_v)                                                 \
170NP_BEGIN_MACRO                                                                \
171    (_v).type = NPVariantType_Void;                                           \
172    (_v).value.objectValue = NULL;                                            \
173NP_END_MACRO
174
175#define NULL_TO_NPVARIANT(_v)                                                 \
176NP_BEGIN_MACRO                                                                \
177    (_v).type = NPVariantType_Null;                                           \
178    (_v).value.objectValue = NULL;                                            \
179NP_END_MACRO
180
181#define BOOLEAN_TO_NPVARIANT(_val, _v)                                        \
182NP_BEGIN_MACRO                                                                \
183    (_v).type = NPVariantType_Bool;                                           \
184    (_v).value.boolValue = !!(_val);                                          \
185NP_END_MACRO
186
187#define INT32_TO_NPVARIANT(_val, _v)                                          \
188NP_BEGIN_MACRO                                                                \
189    (_v).type = NPVariantType_Int32;                                          \
190    (_v).value.intValue = _val;                                               \
191NP_END_MACRO
192
193#define DOUBLE_TO_NPVARIANT(_val, _v)                                         \
194NP_BEGIN_MACRO                                                                \
195    (_v).type = NPVariantType_Double;                                         \
196    (_v).value.doubleValue = _val;                                            \
197NP_END_MACRO
198
199#define STRINGZ_TO_NPVARIANT(_val, _v)                                        \
200NP_BEGIN_MACRO                                                                \
201    (_v).type = NPVariantType_String;                                         \
202    NPString str = { _val, strlen(_val) };                                    \
203    (_v).value.stringValue = str;                                             \
204NP_END_MACRO
205
206#define STRINGN_TO_NPVARIANT(_val, _len, _v)                                  \
207NP_BEGIN_MACRO                                                                \
208    (_v).type = NPVariantType_String;                                         \
209    NPString str = { _val, _len };                                            \
210    (_v).value.stringValue = str;                                             \
211NP_END_MACRO
212
213#define OBJECT_TO_NPVARIANT(_val, _v)                                         \
214NP_BEGIN_MACRO                                                                \
215    (_v).type = NPVariantType_Object;                                         \
216    (_v).value.objectValue = _val;                                            \
217NP_END_MACRO
218
219
220/*
221	Type mappings (JavaScript types have been used for illustration
222    purposes):
223
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
231
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
240*/
241
242typedef void *NPIdentifier;
243
244/*
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.
252*/
253NPIdentifier NPN_GetStringIdentifier(const NPUTF8 *name);
254void NPN_GetStringIdentifiers(const NPUTF8 **names, int32_t nameCount,
255                              NPIdentifier *identifiers);
256NPIdentifier NPN_GetIntIdentifier(int32_t intid);
257bool NPN_IdentifierIsString(NPIdentifier identifier);
258
259/*
260    The NPUTF8 returned from NPN_UTF8FromIdentifier SHOULD be freed.
261*/
262NPUTF8 *NPN_UTF8FromIdentifier(NPIdentifier identifier);
263
264/*
265    Get the integer represented by identifier. If identifier is not an
266    integer identifier, the behaviour is undefined.
267*/
268int32_t NPN_IntFromIdentifier(NPIdentifier identifier);
269
270/*
271    NPObject behavior is implemented using the following set of
272    callback functions.
273
274    The NPVariant *result argument of these functions (where
275    applicable) should be released using NPN_ReleaseVariantValue().
276*/
277typedef NPObject *(*NPAllocateFunctionPtr)(NPP npp, NPClass *aClass);
278typedef void (*NPDeallocateFunctionPtr)(NPObject *npobj);
279typedef void (*NPInvalidateFunctionPtr)(NPObject *npobj);
280typedef bool (*NPHasMethodFunctionPtr)(NPObject *npobj, NPIdentifier name);
281typedef bool (*NPInvokeFunctionPtr)(NPObject *npobj, NPIdentifier name,
282                                    const NPVariant *args, uint32_t argCount,
283                                    NPVariant *result);
284typedef bool (*NPInvokeDefaultFunctionPtr)(NPObject *npobj,
285                                           const NPVariant *args,
286                                           uint32_t argCount,
287                                           NPVariant *result);
288typedef bool (*NPHasPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name);
289typedef bool (*NPGetPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name,
290                                         NPVariant *result);
291typedef bool (*NPSetPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name,
292                                         const NPVariant *value);
293typedef bool (*NPRemovePropertyFunctionPtr)(NPObject *npobj,
294                                            NPIdentifier name);
295typedef bool (*NPEnumerationFunctionPtr)(NPObject *npobj, NPIdentifier **value,
296                                         uint32_t *count);
297typedef bool (*NPConstructFunctionPtr)(NPObject *npobj,
298                                       const NPVariant *args,
299                                       uint32_t argCount,
300                                       NPVariant *result);
301
302/*
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.
307
308    NPInvokeFunctionPtr function may return 0 to indicate a void
309    result.
310
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
318    depended upon.)
319
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().
324*/
325struct NPClass
326{
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;
340};
341
342#define NP_CLASS_STRUCT_VERSION      3
343
344#define NP_CLASS_STRUCT_VERSION_ENUM 2
345#define NP_CLASS_STRUCT_VERSION_CTOR 3
346
347#define NP_CLASS_STRUCT_VERSION_HAS_ENUM(npclass)   \
348        ((npclass)->structVersion >= NP_CLASS_STRUCT_VERSION_ENUM)
349
350#define NP_CLASS_STRUCT_VERSION_HAS_CTOR(npclass)   \
351        ((npclass)->structVersion >= NP_CLASS_STRUCT_VERSION_CTOR)
352
353struct NPObject {
354    NPClass *_class;
355    uint32_t referenceCount;
356    /*
357     * Additional space may be allocated here by types of NPObjects
358     */
359};
360
361/*
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
365    the NPObject to 1.
366*/
367NPObject *NPN_CreateObject(NPP npp, NPClass *aClass);
368
369/*
370    Increment the NPObject's reference count.
371*/
372NPObject *NPN_RetainObject(NPObject *npobj);
373
374/*
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.
378*/
379void NPN_ReleaseObject(NPObject *npobj);
380
381/*
382    Functions to access script objects represented by NPObject.
383
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.
388    
389    Calls made from plugin code to script must be made from the thread
390    on which the plugin was initialized.
391*/
392
393bool NPN_Invoke(NPP npp, NPObject *npobj, NPIdentifier methodName,
394                const NPVariant *args, uint32_t argCount, NPVariant *result);
395bool NPN_InvokeDefault(NPP npp, NPObject *npobj, const NPVariant *args,
396                       uint32_t argCount, NPVariant *result);
397bool NPN_Evaluate(NPP npp, NPObject *npobj, NPString *script,
398                  NPVariant *result);
399bool NPN_GetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName,
400                     NPVariant *result);
401bool NPN_SetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName,
402                     const NPVariant *value);
403bool NPN_RemoveProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName);
404bool NPN_HasProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName);
405bool NPN_HasMethod(NPP npp, NPObject *npobj, NPIdentifier methodName);
406bool NPN_Enumerate(NPP npp, NPObject *npobj, NPIdentifier **identifier,
407                   uint32_t *count);
408bool NPN_Construct(NPP npp, NPObject *npobj, const NPVariant *args,
409                   uint32_t argCount, NPVariant *result);
410
411/*
412    NPN_SetException may be called to trigger a script exception upon
413    return from entry points into NPObjects.  Typical usage:
414
415    NPN_SetException (npobj, message);
416*/
417void NPN_SetException(NPObject *npobj, const NPUTF8 *message);
418
419#ifdef __cplusplus
420}
421#endif
422
423#endif