apps/nsplugins/sdk/npruntime.h

   1 /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * Copyright � 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 #include <QtCore/QtGlobal>
  69 //M.O.:I did s/uint32_t/quint32 to reducde portability headache
  70
  71 #ifdef __cplusplus
  72 extern "C" {
  73 #endif
  74
  75
  76 /*
  77     This API is used to facilitate binding code written in C to script
  78     objects.  The API in this header does not assume the presence of a
  79     user agent.  That is, it can be used to bind C code to scripting
  80     environments outside of the context of a user agent.
  81
  82     However, the normal use of the this API is in the context of a
  83     scripting environment running in a browser or other user agent.
  84     In particular it is used to support the extended Netscape
  85     script-ability API for plugins (NP-SAP).  NP-SAP is an extension
  86     of the Netscape plugin API.  As such we have adopted the use of
  87     the "NP" prefix for this API.
  88
  89     The following NP{N|P}Variables were added to the Netscape plugin
  90     API (in npapi.h):
  91
  92     NPNVWindowNPObject
  93     NPNVPluginElementNPObject
  94     NPPVpluginScriptableNPObject
  95
  96     These variables are exposed through NPN_GetValue() and
  97     NPP_GetValue() (respectively) and are used to establish the
  98     initial binding between the user agent and native code.  The DOM
  99     objects in the user agent can be examined and manipulated using
 100     the NPN_ functions that operate on NPObjects described in this
 101     header.
 102
 103     To the extent possible the assumptions about the scripting
 104     language used by the scripting environment have been minimized.
 105 */
 106
 107 #define NP_BEGIN_MACRO  do {
 108 #define NP_END_MACRO    } while (0)
 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     quint32 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         quint32 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
 147     references.  Specifically it is to be called on variants that own
 148     their value, as is the case with all non-const NPVariant*
 149     arguments after a successful call to any methods (except this one)
 150     in this API.
 151
 152     After calling NPN_ReleaseVariantValue, the type of the variant
 153     will be NPVariantType_Void.
 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 VOID_TO_NPVARIANT(_v)                                                 \
 172 NP_BEGIN_MACRO                                                                \
 173     (_v).type = NPVariantType_Void;                                           \
 174     (_v).value.objectValue = NULL;                                            \
 175 NP_END_MACRO
 176
 177 #define NULL_TO_NPVARIANT(_v)                                                 \
 178 NP_BEGIN_MACRO                                                                \
 179     (_v).type = NPVariantType_Null;                                           \
 180     (_v).value.objectValue = NULL;                                            \
 181 NP_END_MACRO
 182
 183 #define BOOLEAN_TO_NPVARIANT(_val, _v)                                        \
 184 NP_BEGIN_MACRO                                                                \
 185     (_v).type = NPVariantType_Bool;                                           \
 186     (_v).value.boolValue = !!(_val);                                          \
 187 NP_END_MACRO
 188
 189 #define INT32_TO_NPVARIANT(_val, _v)                                          \
 190 NP_BEGIN_MACRO                                                                \
 191     (_v).type = NPVariantType_Int32;                                          \
 192     (_v).value.intValue = _val;                                               \
 193 NP_END_MACRO
 194
 195 #define DOUBLE_TO_NPVARIANT(_val, _v)                                         \
 196 NP_BEGIN_MACRO                                                                \
 197     (_v).type = NPVariantType_Double;                                         \
 198     (_v).value.doubleValue = _val;                                            \
 199 NP_END_MACRO
 200
 201 #define STRINGZ_TO_NPVARIANT(_val, _v)                                        \
 202 NP_BEGIN_MACRO                                                                \
 203     (_v).type = NPVariantType_String;                                         \
 204     NPString str = { _val, strlen(_val) };                                    \
 205     (_v).value.stringValue = str;                                             \
 206 NP_END_MACRO
 207
 208 #define STRINGN_TO_NPVARIANT(_val, _len, _v)                                  \
 209 NP_BEGIN_MACRO                                                                \
 210     (_v).type = NPVariantType_String;                                         \
 211     NPString str = { _val, _len };                                            \
 212     (_v).value.stringValue = str;                                             \
 213 NP_END_MACRO
 214
 215 #define OBJECT_TO_NPVARIANT(_val, _v)                                         \
 216 NP_BEGIN_MACRO                                                                \
 217     (_v).type = NPVariantType_Object;                                         \
 218     (_v).value.objectValue = _val;                                            \
 219 NP_END_MACRO
 220
 221
 222 /*
 223         Type mappings (JavaScript types have been used for illustration
 224     purposes):
 225
 226         JavaScript       to             C (NPVariant with type:)
 227         undefined                       NPVariantType_Void
 228         null                            NPVariantType_Null
 229         Boolean                         NPVariantType_Bool
 230         Number                          NPVariantType_Double or NPVariantType_Int32
 231         String                          NPVariantType_String
 232         Object                          NPVariantType_Object
 233
 234         C (NPVariant with type:)   to   JavaScript
 235         NPVariantType_Void              undefined
 236         NPVariantType_Null              null
 237         NPVariantType_Bool              Boolean
 238         NPVariantType_Int32             Number
 239         NPVariantType_Double            Number
 240         NPVariantType_String            String
 241         NPVariantType_Object            Object
 242 */
 243
 244 typedef void *NPIdentifier;
 245
 246 /*
 247     NPObjects have methods and properties.  Methods and properties are
 248     identified with NPIdentifiers.  These identifiers may be reflected
 249     in script.  NPIdentifiers can be either strings or integers, IOW,
 250     methods and properties can be identified by either strings or
 251     integers (i.e. foo["bar"] vs foo[1]). NPIdentifiers can be
 252     compared using ==.  In case of any errors, the requested
 253     NPIdentifier(s) will be NULL.
 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, quint32 argCount,
 285                                     NPVariant *result);
 286 typedef bool (*NPInvokeDefaultFunctionPtr)(NPObject *npobj,
 287                                            const NPVariant *args,
 288                                            quint32 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
 298 /*
 299     NPObjects returned by create, retain, invoke, and getProperty pass
 300     a reference count to the caller.  That is, the callee adds a
 301     reference count which passes to the caller.  It is the caller's
 302     responsibility to release the returned object.
 303
 304     NPInvokeFunctionPtr function may return 0 to indicate a void
 305     result.
 306
 307     NPInvalidateFunctionPtr is called by the scripting environment
 308     when the native code is shutdown.  Any attempt to message a
 309     NPObject instance after the invalidate callback has been
 310     called will result in undefined behavior, even if the native code
 311     is still retaining those NPObject instances.  (The runtime
 312     will typically return immediately, with 0 or NULL, from an attempt
 313     to dispatch to a NPObject, but this behavior should not be
 314     depended upon.)
 315 */
 316 struct NPClass
 317 {
 318     quint32 structVersion;
 319     NPAllocateFunctionPtr allocate;
 320     NPDeallocateFunctionPtr deallocate;
 321     NPInvalidateFunctionPtr invalidate;
 322     NPHasMethodFunctionPtr hasMethod;
 323     NPInvokeFunctionPtr invoke;
 324     NPInvokeDefaultFunctionPtr invokeDefault;
 325     NPHasPropertyFunctionPtr hasProperty;
 326     NPGetPropertyFunctionPtr getProperty;
 327     NPSetPropertyFunctionPtr setProperty;
 328     NPRemovePropertyFunctionPtr removeProperty;
 329 };
 330
 331 #define NP_CLASS_STRUCT_VERSION 1
 332
 333 struct NPObject {
 334     NPClass *_class;
 335     quint32 referenceCount;
 336     /*
 337      * Additional space may be allocated here by types of NPObjects
 338      */
 339 };
 340
 341 /*
 342     If the class has an allocate function, NPN_CreateObject invokes
 343     that function, otherwise a NPObject is allocated and
 344     returned. This method will initialize the referenceCount member of
 345     the NPObject to 1.
 346 */
 347 NPObject *NPN_CreateObject(NPP npp, NPClass *aClass);
 348
 349 /*
 350     Increment the NPObject's reference count.
 351 */
 352 NPObject *NPN_RetainObject(NPObject *npobj);
 353
 354 /*
 355     Decremented the NPObject's reference count.  If the reference
 356     count goes to zero, the class's destroy function is invoke if
 357     specified, otherwise the object is freed directly.
 358 */
 359 void NPN_ReleaseObject(NPObject *npobj);
 360
 361 /*
 362     Functions to access script objects represented by NPObject.
 363
 364     Calls to script objects are synchronous.  If a function returns a
 365     value, it will be supplied via the result NPVariant
 366     argument. Successful calls will return true, false will be
 367     returned in case of an error.
 368
 369     Calls made from plugin code to script must be made from the thread
 370     on which the plugin was initialized.
 371 */
 372
 373 bool NPN_Invoke(NPP npp, NPObject *npobj, NPIdentifier methodName,
 374                 const NPVariant *args, quint32 argCount, NPVariant *result);
 375 bool NPN_InvokeDefault(NPP npp, NPObject *npobj, const NPVariant *args,
 376                        quint32 argCount, NPVariant *result);
 377 bool NPN_Evaluate(NPP npp, NPObject *npobj, NPString *script,
 378                   NPVariant *result);
 379 bool NPN_GetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName,
 380                      NPVariant *result);
 381 bool NPN_SetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName,
 382                      const NPVariant *value);
 383 bool NPN_RemoveProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName);
 384 bool NPN_HasProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName);
 385 bool NPN_HasMethod(NPP npp, NPObject *npobj, NPIdentifier methodName);
 386
 387 /*
 388     NPN_SetException may be called to trigger a script exception upon
 389     return from entry points into NPObjects.  Typical usage:
 390
 391     NPN_SetException (npobj, message);
 392 */
 393 void NPN_SetException(NPObject *npobj, const NPUTF8 *message);
 394
 395 #ifdef __cplusplus
 396 }
 397 #endif
 398
 399 #endif