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