WebCore/bridge/npruntime.h

   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
  72 extern "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 */
 115 typedef struct NPObject NPObject;
 116 typedef struct NPClass NPClass;
 117
 118 typedef char NPUTF8;
 119 typedef struct _NPString {
 120     const NPUTF8 *UTF8Characters;
 121     uint32_t UTF8Length;
 122 } NPString;
 123
 124 typedef 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
 134 typedef 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 */
 155 void 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
 205 typedef 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 */
 216 NPIdentifier NPN_GetStringIdentifier(const NPUTF8 *name);
 217 void NPN_GetStringIdentifiers(const NPUTF8 **names, int32_t nameCount, NPIdentifier *identifiers);
 218 NPIdentifier NPN_GetIntIdentifier(int32_t intid);
 219 bool NPN_IdentifierIsString(NPIdentifier identifier);
 220
 221 /*
 222     The NPUTF8 returned from NPN_UTF8FromIdentifier SHOULD be freed.
 223 */
 224 NPUTF8 *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 */
 230 int32_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 */
 239 typedef NPObject *(*NPAllocateFunctionPtr)(NPP npp, NPClass *aClass);
 240 typedef void (*NPDeallocateFunctionPtr)(NPObject *obj);
 241 typedef void (*NPInvalidateFunctionPtr)(NPObject *obj);
 242 typedef bool (*NPHasMethodFunctionPtr)(NPObject *obj, NPIdentifier name);
 243 typedef bool (*NPInvokeFunctionPtr)(NPObject *obj, NPIdentifier name, const NPVariant *args, uint32_t argCount, NPVariant *result);
 244 typedef bool (*NPInvokeDefaultFunctionPtr)(NPObject *npobj, const NPVariant *args, uint32_t argCount, NPVariant *result);
 245 typedef bool (*NPHasPropertyFunctionPtr)(NPObject *obj, NPIdentifier name);
 246 typedef bool (*NPGetPropertyFunctionPtr)(NPObject *obj, NPIdentifier name, NPVariant *result);
 247 typedef bool (*NPSetPropertyFunctionPtr)(NPObject *obj, NPIdentifier name, const NPVariant *value);
 248 typedef bool (*NPRemovePropertyFunctionPtr)(NPObject *npobj, NPIdentifier name);
 249 typedef bool (*NPEnumerationFunctionPtr)(NPObject *npobj, NPIdentifier **value, uint32_t *count);
 250 typedef 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 */
 273 struct 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
 299 struct 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 */
 311 NPObject *NPN_CreateObject(NPP npp, NPClass *aClass);
 312
 313 /*
 314     Increment the NPObject's reference count.
 315 */
 316 NPObject *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 */
 323 void 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 */
 336 bool NPN_Invoke(NPP npp, NPObject *npobj, NPIdentifier methodName, const NPVariant *args, uint32_t argCount, NPVariant *result);
 337 bool NPN_InvokeDefault(NPP npp, NPObject *npobj, const NPVariant *args, uint32_t argCount, NPVariant *result);
 338 bool NPN_Evaluate(NPP npp, NPObject *npobj, NPString *script, NPVariant *result);
 339 bool NPN_GetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName, NPVariant *result);
 340 bool NPN_SetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName, const NPVariant *value);
 341 bool NPN_RemoveProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName);
 342 bool NPN_HasProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName);
 343 bool NPN_HasMethod(NPP npp, NPObject *npobj, NPIdentifier methodName);
 344 bool NPN_Enumerate(NPP npp, NPObject *npobj, NPIdentifier **identifier, uint32_t *count);
 345 bool 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 */
 351 void NPN_SetException (NPObject *obj, const NPUTF8 *message);
 352
 353 #ifdef __cplusplus
 354 }
 355 #endif
 356
 357 #endif