WebKit/Plugins.subproj/npruntime.h

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