Back to index

lightning-sunbird  0.9+nobinonly
npruntime.h
Go to the documentation of this file.
00001 /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
00002 /*
00003  * Copyright  2004, Apple Computer, Inc. and The Mozilla Foundation. 
00004  * All rights reserved.
00005  * 
00006  * Redistribution and use in source and binary forms, with or without
00007  * modification, are permitted provided that the following conditions are
00008  * met:
00009  * 
00010  * 1. Redistributions of source code must retain the above copyright
00011  * notice, this list of conditions and the following disclaimer.
00012  * 2. Redistributions in binary form must reproduce the above copyright
00013  * notice, this list of conditions and the following disclaimer in the
00014  * documentation and/or other materials provided with the distribution.
00015  * 3. Neither the names of Apple Computer, Inc. ("Apple") or The Mozilla
00016  * Foundation ("Mozilla") nor the names of their contributors may be used
00017  * to endorse or promote products derived from this software without
00018  * specific prior written permission.
00019  * 
00020  * THIS SOFTWARE IS PROVIDED BY APPLE, MOZILLA AND THEIR CONTRIBUTORS "AS
00021  * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
00022  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
00023  * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE, MOZILLA OR
00024  * THEIR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
00025  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
00026  * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
00027  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
00028  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00029  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00030  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00031  *
00032  * Revision 1 (March 4, 2004):
00033  * Initial proposal.
00034  *
00035  * Revision 2 (March 10, 2004):
00036  * All calls into script were made asynchronous.  Results are
00037  * provided via the NPScriptResultFunctionPtr callback.
00038  *
00039  * Revision 3 (March 10, 2004):
00040  * Corrected comments to not refer to class retain/release FunctionPtrs.
00041  *
00042  * Revision 4 (March 11, 2004):
00043  * Added additional convenience NPN_SetExceptionWithUTF8().
00044  * Changed NPHasPropertyFunctionPtr and NPHasMethodFunctionPtr to take NPClass
00045  * pointers instead of NPObject pointers.
00046  * Added NPIsValidIdentifier().
00047  *
00048  * Revision 5 (March 17, 2004):
00049  * Added context parameter to result callbacks from ScriptObject functions.
00050  *
00051  * Revision 6 (March 29, 2004):
00052  * Renamed functions implemented by user agent to NPN_*.  Removed _ from
00053  * type names.
00054  * Renamed "JavaScript" types to "Script".
00055  *
00056  * Revision 7 (April 21, 2004):
00057  * NPIdentifier becomes a void*, was int32_t
00058  * Remove NP_IsValidIdentifier, renamed NP_IdentifierFromUTF8 to NP_GetIdentifier
00059  * Added NPVariant and modified functions to use this new type.
00060  *
00061  * Revision 8 (July 9, 2004):
00062  * Updated to joint Apple-Mozilla license.
00063  *
00064  */
00065 #ifndef _NP_RUNTIME_H_
00066 #define _NP_RUNTIME_H_
00067 
00068 #ifdef __cplusplus
00069 extern "C" {
00070 #endif
00071 
00072 #include "nptypes.h"
00073 
00074 /*
00075     This API is used to facilitate binding code written in C to script
00076     objects.  The API in this header does not assume the presence of a
00077     user agent.  That is, it can be used to bind C code to scripting
00078     environments outside of the context of a user agent.
00079     
00080     However, the normal use of the this API is in the context of a
00081     scripting environment running in a browser or other user agent.
00082     In particular it is used to support the extended Netscape
00083     script-ability API for plugins (NP-SAP).  NP-SAP is an extension
00084     of the Netscape plugin API.  As such we have adopted the use of
00085     the "NP" prefix for this API.
00086 
00087     The following NP{N|P}Variables were added to the Netscape plugin
00088     API (in npapi.h):
00089 
00090     NPNVWindowNPObject
00091     NPNVPluginElementNPObject
00092     NPPVpluginScriptableNPObject
00093 
00094     These variables are exposed through NPN_GetValue() and
00095     NPP_GetValue() (respectively) and are used to establish the
00096     initial binding between the user agent and native code.  The DOM
00097     objects in the user agent can be examined and manipulated using
00098     the NPN_ functions that operate on NPObjects described in this
00099     header.
00100 
00101     To the extent possible the assumptions about the scripting
00102     language used by the scripting environment have been minimized.
00103 */
00104 
00105 #define NP_BEGIN_MACRO  do {
00106 #define NP_END_MACRO    } while (0)
00107 
00108 /*
00109     Objects (non-primitive data) passed between 'C' and script is
00110     always wrapped in an NPObject.  The 'interface' of an NPObject is
00111     described by an NPClass.
00112 */
00113 typedef struct NPObject NPObject;
00114 typedef struct NPClass NPClass;
00115 
00116 typedef char NPUTF8;
00117 typedef struct _NPString {
00118     const NPUTF8 *utf8characters;
00119     uint32_t utf8length;
00120 } NPString;
00121 
00122 typedef enum {
00123     NPVariantType_Void,
00124     NPVariantType_Null,
00125     NPVariantType_Bool,
00126     NPVariantType_Int32,
00127     NPVariantType_Double,
00128     NPVariantType_String,
00129     NPVariantType_Object
00130 } NPVariantType;
00131 
00132 typedef struct _NPVariant {
00133     NPVariantType type;
00134     union {
00135         bool boolValue;
00136         uint32_t intValue;
00137         double doubleValue;
00138         NPString stringValue;
00139         NPObject *objectValue;
00140     } value;
00141 } NPVariant;
00142 
00143 /*
00144     NPN_ReleaseVariantValue is called on all 'out' parameters
00145     references.  Specifically it is to be called on variants that own
00146     their value, as is the case with all non-const NPVariant*
00147     arguments after a successful call to any methods (except this one)
00148     in this API.
00149 
00150     After calling NPN_ReleaseVariantValue, the type of the variant
00151     will be NPVariantType_Void.
00152 */
00153 void NPN_ReleaseVariantValue(NPVariant *variant);
00154 
00155 #define NPVARIANT_IS_VOID(_v)    ((_v).type == NPVariantType_Void)
00156 #define NPVARIANT_IS_NULL(_v)    ((_v).type == NPVariantType_Null)
00157 #define NPVARIANT_IS_BOOLEAN(_v) ((_v).type == NPVariantType_Bool)
00158 #define NPVARIANT_IS_INT32(_v)   ((_v).type == NPVariantType_Int32)
00159 #define NPVARIANT_IS_DOUBLE(_v)  ((_v).type == NPVariantType_Double)
00160 #define NPVARIANT_IS_STRING(_v)  ((_v).type == NPVariantType_String)
00161 #define NPVARIANT_IS_OBJECT(_v)  ((_v).type == NPVariantType_Object)
00162 
00163 #define NPVARIANT_TO_BOOLEAN(_v) ((_v).value.boolValue)
00164 #define NPVARIANT_TO_INT32(_v)   ((_v).value.intValue)
00165 #define NPVARIANT_TO_DOUBLE(_v)  ((_v).value.doubleValue)
00166 #define NPVARIANT_TO_STRING(_v)  ((_v).value.stringValue)
00167 #define NPVARIANT_TO_OBJECT(_v)  ((_v).value.objectValue)
00168 
00169 #define VOID_TO_NPVARIANT(_v)                                                 \
00170 NP_BEGIN_MACRO                                                                \
00171     (_v).type = NPVariantType_Void;                                           \
00172     (_v).value.objectValue = NULL;                                            \
00173 NP_END_MACRO
00174 
00175 #define NULL_TO_NPVARIANT(_v)                                                 \
00176 NP_BEGIN_MACRO                                                                \
00177     (_v).type = NPVariantType_Null;                                           \
00178     (_v).value.objectValue = NULL;                                            \
00179 NP_END_MACRO
00180 
00181 #define BOOLEAN_TO_NPVARIANT(_val, _v)                                        \
00182 NP_BEGIN_MACRO                                                                \
00183     (_v).type = NPVariantType_Bool;                                           \
00184     (_v).value.boolValue = !!(_val);                                          \
00185 NP_END_MACRO
00186 
00187 #define INT32_TO_NPVARIANT(_val, _v)                                          \
00188 NP_BEGIN_MACRO                                                                \
00189     (_v).type = NPVariantType_Int32;                                          \
00190     (_v).value.intValue = _val;                                               \
00191 NP_END_MACRO
00192 
00193 #define DOUBLE_TO_NPVARIANT(_val, _v)                                         \
00194 NP_BEGIN_MACRO                                                                \
00195     (_v).type = NPVariantType_Double;                                         \
00196     (_v).value.doubleValue = _val;                                            \
00197 NP_END_MACRO
00198 
00199 #define STRINGZ_TO_NPVARIANT(_val, _v)                                        \
00200 NP_BEGIN_MACRO                                                                \
00201     (_v).type = NPVariantType_String;                                         \
00202     NPString str = { _val, strlen(_val) };                                    \
00203     (_v).value.stringValue = str;                                             \
00204 NP_END_MACRO
00205 
00206 #define STRINGN_TO_NPVARIANT(_val, _len, _v)                                  \
00207 NP_BEGIN_MACRO                                                                \
00208     (_v).type = NPVariantType_String;                                         \
00209     NPString str = { _val, _len };                                            \
00210     (_v).value.stringValue = str;                                             \
00211 NP_END_MACRO
00212 
00213 #define OBJECT_TO_NPVARIANT(_val, _v)                                         \
00214 NP_BEGIN_MACRO                                                                \
00215     (_v).type = NPVariantType_Object;                                         \
00216     (_v).value.objectValue = _val;                                            \
00217 NP_END_MACRO
00218 
00219 
00220 /*
00221        Type mappings (JavaScript types have been used for illustration
00222     purposes):
00223 
00224        JavaScript       to             C (NPVariant with type:)
00225        undefined                       NPVariantType_Void
00226        null                            NPVariantType_Null
00227        Boolean                         NPVariantType_Bool
00228        Number                          NPVariantType_Double or NPVariantType_Int32
00229        String                          NPVariantType_String
00230        Object                          NPVariantType_Object
00231 
00232        C (NPVariant with type:)   to   JavaScript
00233        NPVariantType_Void              undefined
00234        NPVariantType_Null              null
00235        NPVariantType_Bool              Boolean   
00236        NPVariantType_Int32             Number
00237        NPVariantType_Double            Number
00238        NPVariantType_String            String
00239        NPVariantType_Object            Object
00240 */
00241 
00242 typedef void *NPIdentifier;
00243 
00244 /*
00245     NPObjects have methods and properties.  Methods and properties are
00246     identified with NPIdentifiers.  These identifiers may be reflected
00247     in script.  NPIdentifiers can be either strings or integers, IOW,
00248     methods and properties can be identified by either strings or
00249     integers (i.e. foo["bar"] vs foo[1]). NPIdentifiers can be
00250     compared using ==.  In case of any errors, the requested
00251     NPIdentifier(s) will be NULL.
00252 */
00253 NPIdentifier NPN_GetStringIdentifier(const NPUTF8 *name);
00254 void NPN_GetStringIdentifiers(const NPUTF8 **names, int32_t nameCount,
00255                               NPIdentifier *identifiers);
00256 NPIdentifier NPN_GetIntIdentifier(int32_t intid);
00257 bool NPN_IdentifierIsString(NPIdentifier identifier);
00258 
00259 /*
00260     The NPUTF8 returned from NPN_UTF8FromIdentifier SHOULD be freed.
00261 */
00262 NPUTF8 *NPN_UTF8FromIdentifier(NPIdentifier identifier);
00263 
00264 /*
00265     Get the integer represented by identifier. If identifier is not an
00266     integer identifier, the behaviour is undefined.
00267 */
00268 int32_t NPN_IntFromIdentifier(NPIdentifier identifier);
00269 
00270 /*
00271     NPObject behavior is implemented using the following set of
00272     callback functions.
00273 
00274     The NPVariant *result argument of these functions (where
00275     applicable) should be released using NPN_ReleaseVariantValue().
00276 */
00277 typedef NPObject *(*NPAllocateFunctionPtr)(NPP npp, NPClass *aClass);
00278 typedef void (*NPDeallocateFunctionPtr)(NPObject *npobj);
00279 typedef void (*NPInvalidateFunctionPtr)(NPObject *npobj);
00280 typedef bool (*NPHasMethodFunctionPtr)(NPObject *npobj, NPIdentifier name);
00281 typedef bool (*NPInvokeFunctionPtr)(NPObject *npobj, NPIdentifier name,
00282                                     const NPVariant *args, uint32_t argCount,
00283                                     NPVariant *result);
00284 typedef bool (*NPInvokeDefaultFunctionPtr)(NPObject *npobj,
00285                                            const NPVariant *args,
00286                                            uint32_t argCount,
00287                                            NPVariant *result);
00288 typedef bool (*NPHasPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name);
00289 typedef bool (*NPGetPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name,
00290                                          NPVariant *result);
00291 typedef bool (*NPSetPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name,
00292                                          const NPVariant *value);
00293 typedef bool (*NPRemovePropertyFunctionPtr)(NPObject *npobj,
00294                                             NPIdentifier name);
00295 
00296 /*
00297     NPObjects returned by create, retain, invoke, and getProperty pass
00298     a reference count to the caller.  That is, the callee adds a
00299     reference count which passes to the caller.  It is the caller's
00300     responsibility to release the returned object.
00301 
00302     NPInvokeFunctionPtr function may return 0 to indicate a void
00303     result.
00304 
00305     NPInvalidateFunctionPtr is called by the scripting environment
00306     when the native code is shutdown.  Any attempt to message a
00307     NPObject instance after the invalidate callback has been
00308     called will result in undefined behavior, even if the native code
00309     is still retaining those NPObject instances.  (The runtime
00310     will typically return immediately, with 0 or NULL, from an attempt
00311     to dispatch to a NPObject, but this behavior should not be
00312     depended upon.)
00313 */
00314 struct NPClass
00315 {
00316     uint32_t structVersion;
00317     NPAllocateFunctionPtr allocate;
00318     NPDeallocateFunctionPtr deallocate;
00319     NPInvalidateFunctionPtr invalidate;
00320     NPHasMethodFunctionPtr hasMethod;
00321     NPInvokeFunctionPtr invoke;
00322     NPInvokeDefaultFunctionPtr invokeDefault;
00323     NPHasPropertyFunctionPtr hasProperty;
00324     NPGetPropertyFunctionPtr getProperty;
00325     NPSetPropertyFunctionPtr setProperty;
00326     NPRemovePropertyFunctionPtr removeProperty;
00327 };
00328 
00329 #define NP_CLASS_STRUCT_VERSION 1
00330 
00331 struct NPObject {
00332     NPClass *_class;
00333     uint32_t referenceCount;
00334     /*
00335      * Additional space may be allocated here by types of NPObjects
00336      */
00337 };
00338 
00339 /*
00340     If the class has an allocate function, NPN_CreateObject invokes
00341     that function, otherwise a NPObject is allocated and
00342     returned. This method will initialize the referenceCount member of
00343     the NPObject to 1.
00344 */
00345 NPObject *NPN_CreateObject(NPP npp, NPClass *aClass);
00346 
00347 /*
00348     Increment the NPObject's reference count.
00349 */
00350 NPObject *NPN_RetainObject(NPObject *npobj);
00351 
00352 /*
00353     Decremented the NPObject's reference count.  If the reference
00354     count goes to zero, the class's destroy function is invoke if
00355     specified, otherwise the object is freed directly.
00356 */
00357 void NPN_ReleaseObject(NPObject *npobj);
00358 
00359 /*
00360     Functions to access script objects represented by NPObject.
00361 
00362     Calls to script objects are synchronous.  If a function returns a
00363     value, it will be supplied via the result NPVariant
00364     argument. Successful calls will return true, false will be
00365     returned in case of an error.
00366     
00367     Calls made from plugin code to script must be made from the thread
00368     on which the plugin was initialized.
00369 */
00370 
00371 bool NPN_Invoke(NPP npp, NPObject *npobj, NPIdentifier methodName,
00372                 const NPVariant *args, uint32_t argCount, NPVariant *result);
00373 bool NPN_InvokeDefault(NPP npp, NPObject *npobj, const NPVariant *args,
00374                        uint32_t argCount, NPVariant *result);
00375 bool NPN_Evaluate(NPP npp, NPObject *npobj, NPString *script,
00376                   NPVariant *result);
00377 bool NPN_GetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName,
00378                      NPVariant *result);
00379 bool NPN_SetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName,
00380                      const NPVariant *value);
00381 bool NPN_RemoveProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName);
00382 bool NPN_HasProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName);
00383 bool NPN_HasMethod(NPP npp, NPObject *npobj, NPIdentifier methodName);
00384 
00385 /*
00386     NPN_SetException may be called to trigger a script exception upon
00387     return from entry points into NPObjects.  Typical usage:
00388 
00389     NPN_SetException (npobj, message);
00390 */
00391 void NPN_SetException(NPObject *npobj, const NPUTF8 *message);
00392 
00393 #ifdef __cplusplus
00394 }
00395 #endif
00396 
00397 #endif