modules/plugin/base/public/npruntime.h

   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  * 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
  69 extern "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 */
 113 typedef struct NPObject NPObject;
 114 typedef struct NPClass NPClass;
 115
 116 typedef char NPUTF8;
 117 typedef struct _NPString {
 118     const NPUTF8 *UTF8Characters;
 119     uint32_t UTF8Length;
 120 } NPString;
 121
 122 typedef 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
 132 typedef 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 */
 153 void 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)                                                 \
 170 NP_BEGIN_MACRO                                                                \
 171     (_v).type = NPVariantType_Void;                                           \
 172     (_v).value.objectValue = NULL;                                            \
 173 NP_END_MACRO
 174
 175 #define NULL_TO_NPVARIANT(_v)                                                 \
 176 NP_BEGIN_MACRO                                                                \
 177     (_v).type = NPVariantType_Null;                                           \
 178     (_v).value.objectValue = NULL;                                            \
 179 NP_END_MACRO
 180
 181 #define BOOLEAN_TO_NPVARIANT(_val, _v)                                        \
 182 NP_BEGIN_MACRO                                                                \
 183     (_v).type = NPVariantType_Bool;                                           \
 184     (_v).value.boolValue = !!(_val);                                          \
 185 NP_END_MACRO
 186
 187 #define INT32_TO_NPVARIANT(_val, _v)                                          \
 188 NP_BEGIN_MACRO                                                                \
 189     (_v).type = NPVariantType_Int32;                                          \
 190     (_v).value.intValue = _val;                                               \
 191 NP_END_MACRO
 192
 193 #define DOUBLE_TO_NPVARIANT(_val, _v)                                         \
 194 NP_BEGIN_MACRO                                                                \
 195     (_v).type = NPVariantType_Double;                                         \
 196     (_v).value.doubleValue = _val;                                            \
 197 NP_END_MACRO
 198
 199 #define STRINGZ_TO_NPVARIANT(_val, _v)                                        \
 200 NP_BEGIN_MACRO                                                                \
 201     (_v).type = NPVariantType_String;                                         \
 202     NPString str = { _val, strlen(_val) };                                    \
 203     (_v).value.stringValue = str;                                             \
 204 NP_END_MACRO
 205
 206 #define STRINGN_TO_NPVARIANT(_val, _len, _v)                                  \
 207 NP_BEGIN_MACRO                                                                \
 208     (_v).type = NPVariantType_String;                                         \
 209     NPString str = { _val, _len };                                            \
 210     (_v).value.stringValue = str;                                             \
 211 NP_END_MACRO
 212
 213 #define OBJECT_TO_NPVARIANT(_val, _v)                                         \
 214 NP_BEGIN_MACRO                                                                \
 215     (_v).type = NPVariantType_Object;                                         \
 216     (_v).value.objectValue = _val;                                            \
 217 NP_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
 242 typedef 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. NPIdentifier lifetime is controlled
 252     by the browser. Plugins do not need to worry about memory management
 253     with regards to NPIdentifiers.
 254 */
 255 NPIdentifier NPN_GetStringIdentifier(const NPUTF8 *name);
 256 void NPN_GetStringIdentifiers(const NPUTF8 **names, int32_t nameCount,
 257                               NPIdentifier *identifiers);
 258 NPIdentifier NPN_GetIntIdentifier(int32_t intid);
 259 bool NPN_IdentifierIsString(NPIdentifier identifier);
 260
 261 /*
 262     The NPUTF8 returned from NPN_UTF8FromIdentifier SHOULD be freed.
 263 */
 264 NPUTF8 *NPN_UTF8FromIdentifier(NPIdentifier identifier);
 265
 266 /*
 267     Get the integer represented by identifier. If identifier is not an
 268     integer identifier, the behaviour is undefined.
 269 */
 270 int32_t NPN_IntFromIdentifier(NPIdentifier identifier);
 271
 272 /*
 273     NPObject behavior is implemented using the following set of
 274     callback functions.
 275
 276     The NPVariant *result argument of these functions (where
 277     applicable) should be released using NPN_ReleaseVariantValue().
 278 */
 279 typedef NPObject *(*NPAllocateFunctionPtr)(NPP npp, NPClass *aClass);
 280 typedef void (*NPDeallocateFunctionPtr)(NPObject *npobj);
 281 typedef void (*NPInvalidateFunctionPtr)(NPObject *npobj);
 282 typedef bool (*NPHasMethodFunctionPtr)(NPObject *npobj, NPIdentifier name);
 283 typedef bool (*NPInvokeFunctionPtr)(NPObject *npobj, NPIdentifier name,
 284                                     const NPVariant *args, uint32_t argCount,
 285                                     NPVariant *result);
 286 typedef bool (*NPInvokeDefaultFunctionPtr)(NPObject *npobj,
 287                                            const NPVariant *args,
 288                                            uint32_t argCount,
 289                                            NPVariant *result);
 290 typedef bool (*NPHasPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name);
 291 typedef bool (*NPGetPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name,
 292                                          NPVariant *result);
 293 typedef bool (*NPSetPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name,
 294                                          const NPVariant *value);
 295 typedef bool (*NPRemovePropertyFunctionPtr)(NPObject *npobj,
 296                                             NPIdentifier name);
 297 typedef bool (*NPEnumerationFunctionPtr)(NPObject *npobj, NPIdentifier **value,
 298                                          uint32_t *count);
 299 typedef bool (*NPConstructFunctionPtr)(NPObject *npobj,
 300                                        const NPVariant *args,
 301                                        uint32_t argCount,
 302                                        NPVariant *result);
 303
 304 /*
 305     NPObjects returned by create, retain, invoke, and getProperty pass
 306     a reference count to the caller.  That is, the callee adds a
 307     reference count which passes to the caller.  It is the caller's
 308     responsibility to release the returned object.
 309
 310     NPInvokeFunctionPtr function may return 0 to indicate a void
 311     result.
 312
 313     NPInvalidateFunctionPtr is called by the scripting environment
 314     when the native code is shutdown.  Any attempt to message a
 315     NPObject instance after the invalidate callback has been
 316     called will result in undefined behavior, even if the native code
 317     is still retaining those NPObject instances.  (The runtime
 318     will typically return immediately, with 0 or NULL, from an attempt
 319     to dispatch to a NPObject, but this behavior should not be
 320     depended upon.)
 321
 322     The NPEnumerationFunctionPtr function may pass an array of
 323     NPIdentifiers back to the caller. The callee allocs the memory of
 324     the array using NPN_MemAlloc(), and it's the caller's responsibility
 325     to release it using NPN_MemFree().
 326 */
 327 struct NPClass
 328 {
 329     uint32_t structVersion;
 330     NPAllocateFunctionPtr allocate;
 331     NPDeallocateFunctionPtr deallocate;
 332     NPInvalidateFunctionPtr invalidate;
 333     NPHasMethodFunctionPtr hasMethod;
 334     NPInvokeFunctionPtr invoke;
 335     NPInvokeDefaultFunctionPtr invokeDefault;
 336     NPHasPropertyFunctionPtr hasProperty;
 337     NPGetPropertyFunctionPtr getProperty;
 338     NPSetPropertyFunctionPtr setProperty;
 339     NPRemovePropertyFunctionPtr removeProperty;
 340     NPEnumerationFunctionPtr enumerate;
 341     NPConstructFunctionPtr construct;
 342 };
 343
 344 #define NP_CLASS_STRUCT_VERSION      3
 345
 346 #define NP_CLASS_STRUCT_VERSION_ENUM 2
 347 #define NP_CLASS_STRUCT_VERSION_CTOR 3
 348
 349 #define NP_CLASS_STRUCT_VERSION_HAS_ENUM(npclass)   \
 350         ((npclass)->structVersion >= NP_CLASS_STRUCT_VERSION_ENUM)
 351
 352 #define NP_CLASS_STRUCT_VERSION_HAS_CTOR(npclass)   \
 353         ((npclass)->structVersion >= NP_CLASS_STRUCT_VERSION_CTOR)
 354
 355 struct NPObject {
 356     NPClass *_class;
 357     uint32_t referenceCount;
 358     /*
 359      * Additional space may be allocated here by types of NPObjects
 360      */
 361 };
 362
 363 /*
 364     If the class has an allocate function, NPN_CreateObject invokes
 365     that function, otherwise a NPObject is allocated and
 366     returned. This method will initialize the referenceCount member of
 367     the NPObject to 1.
 368 */
 369 NPObject *NPN_CreateObject(NPP npp, NPClass *aClass);
 370
 371 /*
 372     Increment the NPObject's reference count.
 373 */
 374 NPObject *NPN_RetainObject(NPObject *npobj);
 375
 376 /*
 377     Decremented the NPObject's reference count.  If the reference
 378     count goes to zero, the class's destroy function is invoke if
 379     specified, otherwise the object is freed directly.
 380 */
 381 void NPN_ReleaseObject(NPObject *npobj);
 382
 383 /*
 384     Functions to access script objects represented by NPObject.
 385
 386     Calls to script objects are synchronous.  If a function returns a
 387     value, it will be supplied via the result NPVariant
 388     argument. Successful calls will return true, false will be
 389     returned in case of an error.
 390
 391     Calls made from plugin code to script must be made from the thread
 392     on which the plugin was initialized.
 393 */
 394
 395 bool NPN_Invoke(NPP npp, NPObject *npobj, NPIdentifier methodName,
 396                 const NPVariant *args, uint32_t argCount, NPVariant *result);
 397 bool NPN_InvokeDefault(NPP npp, NPObject *npobj, const NPVariant *args,
 398                        uint32_t argCount, NPVariant *result);
 399 bool NPN_Evaluate(NPP npp, NPObject *npobj, NPString *script,
 400                   NPVariant *result);
 401 bool NPN_GetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName,
 402                      NPVariant *result);
 403 bool NPN_SetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName,
 404                      const NPVariant *value);
 405 bool NPN_RemoveProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName);
 406 bool NPN_HasProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName);
 407 bool NPN_HasMethod(NPP npp, NPObject *npobj, NPIdentifier methodName);
 408 bool NPN_Enumerate(NPP npp, NPObject *npobj, NPIdentifier **identifier,
 409                    uint32_t *count);
 410 bool NPN_Construct(NPP npp, NPObject *npobj, const NPVariant *args,
 411                    uint32_t argCount, NPVariant *result);
 412
 413 /*
 414     NPN_SetException may be called to trigger a script exception upon
 415     return from entry points into NPObjects.  Typical usage:
 416
 417     NPN_SetException (npobj, message);
 418 */
 419 void NPN_SetException(NPObject *npobj, const NPUTF8 *message);
 420
 421 #ifdef __cplusplus
 422 }
 423 #endif
 424
 425 #endif