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