bindings/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 #if ENABLE(NETSCAPE_API)
  72
  73 #ifdef __cplusplus
  74 extern "C" {
  75 #endif
  76
  77 #include <stdint.h>
  78 #include "npapi.h"
  79
  80 #if defined(XP_MACOSX) && defined(__LP64__)
  81 #error 64-bit Netscape plug-ins are not supported on Mac OS X
  82 #endif
  83
  84 /*
  85     This API is used to facilitate binding code written in C to script
  86     objects.  The API in this header does not assume the presence of a
  87     user agent.  That is, it can be used to bind C code to scripting
  88     environments outside of the context of a user agent.
  89
  90     However, the normal use of the this API is in the context of a
  91     scripting environment running in a browser or other user agent.
  92     In particular it is used to support the extended Netscape
  93     script-ability API for plugins (NP-SAP).  NP-SAP is an extension
  94     of the Netscape plugin API.  As such we have adopted the use of
  95     the "NP" prefix for this API.
  96
  97     The following NP{N|P}Variables were added to the Netscape plugin
  98     API (in npapi.h):
  99
 100     NPNVWindowNPObject
 101     NPNVPluginElementNPObject
 102     NPPVpluginScriptableNPObject
 103
 104     These variables are exposed through NPN_GetValue() and
 105     NPP_GetValue() (respectively) and are used to establish the
 106     initial binding between the user agent and native code.  The DOM
 107     objects in the user agent can be examined and manipulated using
 108     the NPN_ functions that operate on NPObjects described in this
 109     header.
 110
 111     To the extent possible the assumptions about the scripting
 112     language used by the scripting environment have been minimized.
 113 */
 114
 115
 116 /*
 117     Objects (non-primitive data) passed between 'C' and script is
 118     always wrapped in an NPObject.  The 'interface' of an NPObject is
 119     described by an NPClass.
 120 */
 121 typedef struct NPObject NPObject;
 122 typedef struct NPClass NPClass;
 123
 124 typedef char NPUTF8;
 125 typedef struct _NPString {
 126     const NPUTF8 *UTF8Characters;
 127     uint32_t UTF8Length;
 128 } NPString;
 129
 130 typedef enum {
 131     NPVariantType_Void,
 132     NPVariantType_Null,
 133     NPVariantType_Bool,
 134     NPVariantType_Int32,
 135     NPVariantType_Double,
 136     NPVariantType_String,
 137     NPVariantType_Object
 138 } NPVariantType;
 139
 140 typedef struct _NPVariant {
 141     NPVariantType type;
 142     union {
 143         bool boolValue;
 144         int32_t intValue;
 145         double doubleValue;
 146         NPString stringValue;
 147         NPObject *objectValue;
 148     } value;
 149 } NPVariant;
 150
 151 /*
 152     NPN_ReleaseVariantValue is called on all 'out' parameters references.
 153     Specifically it is called on variants that are resultant out parameters
 154     in NPGetPropertyFunctionPtr and NPInvokeFunctionPtr.  Resultant variants
 155     from these two functions should be initialized using the
 156     NPN_InitializeVariantXXX() functions.
 157
 158     After calling NPReleaseVariantValue, the type of the variant will
 159     be set to NPVariantUndefinedType.
 160 */
 161 void NPN_ReleaseVariantValue (NPVariant *variant);
 162
 163 #define NPVARIANT_IS_VOID(_v)    ((_v).type == NPVariantType_Void)
 164 #define NPVARIANT_IS_NULL(_v)    ((_v).type == NPVariantType_Null)
 165 #define NPVARIANT_IS_BOOLEAN(_v) ((_v).type == NPVariantType_Bool)
 166 #define NPVARIANT_IS_INT32(_v)   ((_v).type == NPVariantType_Int32)
 167 #define NPVARIANT_IS_DOUBLE(_v)  ((_v).type == NPVariantType_Double)
 168 #define NPVARIANT_IS_STRING(_v)  ((_v).type == NPVariantType_String)
 169 #define NPVARIANT_IS_OBJECT(_v)  ((_v).type == NPVariantType_Object)
 170
 171 #define NPVARIANT_TO_BOOLEAN(_v) ((_v).value.boolValue)
 172 #define NPVARIANT_TO_INT32(_v)   ((_v).value.intValue)
 173 #define NPVARIANT_TO_DOUBLE(_v)  ((_v).value.doubleValue)
 174 #define NPVARIANT_TO_STRING(_v)  ((_v).value.stringValue)
 175 #define NPVARIANT_TO_OBJECT(_v)  ((_v).value.objectValue)
 176
 177 #define NP_BEGIN_MACRO  do {
 178 #define NP_END_MACRO    } while (0)
 179
 180 #define VOID_TO_NPVARIANT(_v)                NP_BEGIN_MACRO (_v).type = NPVariantType_Void; (_v).value.objectValue = NULL; NP_END_MACRO
 181 #define NULL_TO_NPVARIANT(_v)                NP_BEGIN_MACRO (_v).type = NPVariantType_Null; (_v).value.objectValue = NULL; NP_END_MACRO
 182 #define BOOLEAN_TO_NPVARIANT(_val, _v)       NP_BEGIN_MACRO (_v).type = NPVariantType_Bool; (_v).value.boolValue = !!(_val); NP_END_MACRO
 183 #define INT32_TO_NPVARIANT(_val, _v)         NP_BEGIN_MACRO (_v).type = NPVariantType_Int32; (_v).value.intValue = _val; NP_END_MACRO
 184 #define DOUBLE_TO_NPVARIANT(_val, _v)        NP_BEGIN_MACRO (_v).type = NPVariantType_Double; (_v).value.doubleValue = _val; NP_END_MACRO
 185 #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
 186 #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
 187 #define OBJECT_TO_NPVARIANT(_val, _v)        NP_BEGIN_MACRO (_v).type = NPVariantType_Object; (_v).value.objectValue = _val; NP_END_MACRO
 188
 189 /*
 190         Type mappings (JavaScript types have been used for illustration
 191     purposes):
 192
 193         JavaScript       to             C (NPVariant with type:)
 194         undefined                       NPVariantType_Void
 195         null                            NPVariantType_Null
 196         Boolean                         NPVariantType_Bool
 197         Number                          NPVariantType_Double or NPVariantType_Int32
 198         String                          NPVariantType_String
 199         Object                          NPVariantType_Object
 200
 201         C (NPVariant with type:)   to   JavaScript
 202         NPVariantType_Void              undefined
 203         NPVariantType_Null              null
 204         NPVariantType_Bool              Boolean
 205         NPVariantType_Int32             Number
 206         NPVariantType_Double            Number
 207         NPVariantType_String            String
 208         NPVariantType_Object            Object
 209 */
 210
 211 typedef void *NPIdentifier;
 212
 213 /*
 214     NPObjects have methods and properties.  Methods and properties are
 215     identified with NPIdentifiers.  These identifiers may be reflected
 216     in script.  NPIdentifiers can be either strings or integers, IOW,
 217     methods and properties can be identified by either strings or
 218     integers (i.e. foo["bar"] vs foo[1]). NPIdentifiers can be
 219     compared using ==.  In case of any errors, the requested
 220     NPIdentifier(s) will be NULL.
 221 */
 222 NPIdentifier NPN_GetStringIdentifier(const NPUTF8 *name);
 223 void NPN_GetStringIdentifiers(const NPUTF8 **names, int32_t nameCount, NPIdentifier *identifiers);
 224 NPIdentifier NPN_GetIntIdentifier(int32_t intid);
 225 bool NPN_IdentifierIsString(NPIdentifier identifier);
 226
 227 /*
 228     The NPUTF8 returned from NPN_UTF8FromIdentifier SHOULD be freed.
 229 */
 230 NPUTF8 *NPN_UTF8FromIdentifier(NPIdentifier identifier);
 231
 232 /*
 233     Get the integer represented by identifier. If identifier is not an
 234     integer identifier, the behaviour is undefined.
 235 */
 236 int32_t NPN_IntFromIdentifier(NPIdentifier identifier);
 237
 238 /*
 239     NPObject behavior is implemented using the following set of
 240     callback functions.
 241
 242     The NPVariant *result argument of these functions (where
 243     applicable) should be released using NPN_ReleaseVariantValue().
 244 */
 245 typedef NPObject *(*NPAllocateFunctionPtr)(NPP npp, NPClass *aClass);
 246 typedef void (*NPDeallocateFunctionPtr)(NPObject *obj);
 247 typedef void (*NPInvalidateFunctionPtr)(NPObject *obj);
 248 typedef bool (*NPHasMethodFunctionPtr)(NPObject *obj, NPIdentifier name);
 249 typedef bool (*NPInvokeFunctionPtr)(NPObject *obj, NPIdentifier name, const NPVariant *args, uint32_t argCount, NPVariant *result);
 250 typedef bool (*NPInvokeDefaultFunctionPtr)(NPObject *npobj, const NPVariant *args, uint32_t argCount, NPVariant *result);
 251 typedef bool (*NPHasPropertyFunctionPtr)(NPObject *obj, NPIdentifier name);
 252 typedef bool (*NPGetPropertyFunctionPtr)(NPObject *obj, NPIdentifier name, NPVariant *result);
 253 typedef bool (*NPSetPropertyFunctionPtr)(NPObject *obj, NPIdentifier name, const NPVariant *value);
 254 typedef bool (*NPRemovePropertyFunctionPtr)(NPObject *npobj, NPIdentifier name);
 255 typedef bool (*NPEnumerationFunctionPtr)(NPObject *npobj, NPIdentifier **value, uint32_t *count);
 256
 257 /*
 258     NPObjects returned by create have a reference count of one.  It is the caller's responsibility
 259     to release the returned object.
 260
 261     NPInvokeFunctionPtr function may return false to indicate a the method could not be invoked.
 262
 263     NPGetPropertyFunctionPtr and NPSetPropertyFunctionPtr may return false to indicate a property doesn't
 264     exist.
 265
 266     NPInvalidateFunctionPtr is called by the scripting environment when the native code is
 267     shutdown.  Any attempt to message a NPObject instance after the invalidate
 268     callback has been called will result in undefined behavior, even if the
 269     native code is still retaining those NPObject instances.
 270     (The runtime will typically return immediately, with 0 or NULL, from an attempt to
 271     dispatch to a NPObject, but this behavior should not be depended upon.)
 272
 273     The NPEnumerationFunctionPtr function may pass an array of
 274     NPIdentifiers back to the caller. The callee allocs the memory of
 275     the array using NPN_MemAlloc(), and it's the caller's responsibility
 276     to release it using NPN_MemFree().
 277 */
 278 struct NPClass
 279 {
 280     uint32_t structVersion;
 281     NPAllocateFunctionPtr allocate;
 282     NPDeallocateFunctionPtr deallocate;
 283     NPInvalidateFunctionPtr invalidate;
 284     NPHasMethodFunctionPtr hasMethod;
 285     NPInvokeFunctionPtr invoke;
 286     NPInvokeDefaultFunctionPtr invokeDefault;
 287     NPHasPropertyFunctionPtr hasProperty;
 288     NPGetPropertyFunctionPtr getProperty;
 289     NPSetPropertyFunctionPtr setProperty;
 290     NPRemovePropertyFunctionPtr removeProperty;
 291     NPEnumerationFunctionPtr enumerate;
 292 };
 293
 294 #define NP_CLASS_STRUCT_VERSION      2
 295 #define NP_CLASS_STRUCT_VERSION_ENUM 2
 296 #define NP_CLASS_STRUCT_VERSION_HAS_ENUM(npclass)   \
 297     ((npclass)->structVersion >= NP_CLASS_STRUCT_VERSION_ENUM)
 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
 346 /*
 347     NPN_SetException may be called to trigger a script exception upon return
 348     from entry points into NPObjects.
 349 */
 350 void NPN_SetException (NPObject *obj, const NPUTF8 *message);
 351
 352 #ifdef __cplusplus
 353 }
 354 #endif
 355
 356 #endif // ENABLE(NETSCAPE_API)
 357
 358 #endif