WebKit/Plugins.subproj/npruntime.h

   1 /*
   2  * Copyright (C) 2004 Apple Computer, Inc.  All rights reserved.
   3  *
   4  * Revision 1 (March 4, 2004):
   5  * Initial proposal.
   6  *
   7  * Revision 2 (March 10, 2004):
   8  * All calls into script were made asynchronous.  Results are
   9  * provided via the NPScriptResultFunctionPtr callback.
  10  *
  11  * Revision 3 (March 10, 2004):
  12  * Corrected comments to not refer to class retain/release FunctionPtrs.
  13  *
  14  * Revision 4 (March 11, 2004):
  15  * Added additional convenience NPN_SetExceptionWithUTF8().
  16  * Changed NPHasPropertyFunctionPtr and NPHasMethodFunctionPtr to take NPClass
  17  * pointers instead of NPObject pointers.
  18  * Added NPIsValidIdentifier().
  19  *
  20  * Revision 5 (March 17, 2004):
  21  * Added context parameter to result callbacks from ScriptObject functions.
  22  *
  23  * Revision 6 (March 29, 2004):
  24  * Renamed functions implemented by user agent to NPN_*.  Removed _ from
  25  * type names.
  26  * Renamed "JavaScript" types to "Script".
  27  *
  28  * Revision 7 (April 21, 2004):
  29  * NPIdentifier becomes a void*, was int32_t
  30  * Remove NP_IsValidIdentifier, renamed NP_IdentifierFromUTF8 to NP_GetIdentifier
  31  * Added NPVariant and modified functions to use this new type.
  32  */
  33 #ifndef _NP_RUNTIME_H_
  34 #define _NP_RUNTIME_H_
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 /*
  41     This API is used to facilitate binding code written in C to script
  42     objects.  The API in this header does not assume the presence of a
  43     user agent.  That is, it can be used to bind C code to scripting environments
  44     outside of the context of a user agent.
  45
  46     However, the normal use of the this API is in the context of a scripting
  47     environment running in a browser or other user agent.  In particular it is used
  48     to support the extended Netscape script-ability API for plugins (NP-SAP).
  49     NP-SAP is an extension of the Netscape plugin API.  As such we have adopted the
  50     use of the "NP" prefix for this API.
  51 */
  52
  53
  54 /*
  55     Data passed between 'C' and script is always wrapped in an NPObject.
  56     The 'interface' of an NPObject is described by an NPClass.
  57 */
  58 typedef struct NPObject NPObject;
  59 typedef struct NPClass NPClass;
  60
  61 typedef char NPUTF8;
  62 typedef struct _NPString {
  63     const NPUTF8 *UTF8Characters;
  64     uint32_t UTF8Length;
  65 } NPString;
  66
  67 #ifndef _NPAPI_H_
  68 // Ack!  Temporary hack to get build working.
  69 typedef unsigned char NPBool;
  70 #endif
  71
  72 typedef enum {
  73     NPVariantVoidType,
  74     NPVariantNullType,
  75     NPVariantUndefinedType,
  76     NPVariantBoolType,
  77     NPVariantInt32Type,
  78     NPVariantDoubleType,
  79     NPVariantStringType,
  80     NPVariantObjectType
  81 } NPVariantType;
  82
  83 typedef struct _NPVariant {
  84     NPVariantType type;
  85     union {
  86         NPBool boolValue;
  87         int32_t intValue;
  88         double doubleValue;
  89         NPString stringValue;
  90         NPObject *objectValue;
  91     } value;
  92 } NPVariant;
  93
  94 /*
  95     NPN_ReleaseVariantValue is called on all 'out' parameters references.
  96     Specifically it is called on variants that are resultant out parameters
  97     in NPGetPropertyFunctionPtr and NPInvokeFunctionPtr.  Resultant variants
  98     from these two functions should be initialized using the
  99     NPN_InitializeVariantXXX() functions.
 100
 101     After calling NPReleaseVariantValue, the type of the variant will
 102     be set to NPVariantUndefinedType.
 103 */
 104 void NPN_ReleaseVariantValue (NPVariant *variant);
 105
 106 NPBool NPN_VariantIsVoid (const NPVariant *variant);
 107 NPBool NPN_VariantIsNull (const NPVariant *variant);
 108 NPBool NPN_VariantIsUndefined (const NPVariant *variant);
 109 NPBool NPN_VariantIsBool (const NPVariant *variant);
 110 NPBool NPN_VariantIsInt32 (const NPVariant *variant);
 111 NPBool NPN_VariantIsDouble (const NPVariant *variant);
 112 NPBool NPN_VariantIsString (const NPVariant *variant);
 113 NPBool NPN_VariantIsObject (const NPVariant *variant);
 114 NPBool NPN_VariantToBool (const NPVariant *variant, NPBool *result);
 115 NPBool NPN_VariantToInt32 (const NPVariant *variant, int32_t *result);
 116 NPBool NPN_VariantToDouble (const NPVariant *variant, double *result);
 117 NPString NPN_VariantToString (const NPVariant *variant);
 118 NPString NPN_VariantToStringCopy (const NPVariant *variant);
 119 NPBool NPN_VariantToObject (const NPVariant *variant, NPObject **result);
 120
 121 /*
 122     NPVariants initialized with the NPN_InitializeVariantXXX() functions
 123     must be released using the NPN_ReleaseVariantValue() function.
 124 */
 125 void NPN_InitializeVariantAsVoid (NPVariant *variant);
 126 void NPN_InitializeVariantAsNull (NPVariant *variant);
 127 void NPN_InitializeVariantAsUndefined (NPVariant *variant);
 128 void NPN_InitializeVariantWithBool (NPVariant *variant, NPBool value);
 129 void NPN_InitializeVariantWithInt32 (NPVariant *variant, int32_t value);
 130 void NPN_InitializeVariantWithDouble (NPVariant *variant, double value);
 131
 132 /*
 133     NPN_InitializeVariantWithString() does not copy string data.  However
 134     the string data will be deallocated by calls to NPReleaseVariantValue().
 135 */
 136 void NPN_InitializeVariantWithString (NPVariant *variant, const NPString *value);
 137
 138 /*
 139     NPN_InitializeVariantWithStringCopy() will copy string data.  The string data
 140     will be deallocated by calls to NPReleaseVariantValue().
 141 */
 142 void NPN_InitializeVariantWithStringCopy (NPVariant *variant, const NPString *value);
 143
 144 /*
 145     NPN_InitializeVariantWithObject() retains the NPObject.  The object will be released
 146     by calls to NPReleaseVariantValue();
 147 */
 148 void NPN_InitializeVariantWithObject (NPVariant *variant, NPObject *value);
 149
 150 void NPN_InitializeVariantWithVariant (NPVariant *destination, const NPVariant *source);
 151
 152 /*
 153         Type mappings (JavaScript types have been used for illustration
 154     purposes):
 155
 156         script    to                C
 157         Boolean                     NPVariant (with type NPVariantBoolType)
 158         Number                      NPVariant (with type NPVariantDoubleType)
 159         String                      NPVariant (with type NPVariantStringType)
 160         Undefined                   NPVariant (with type NPVariantUndefinedType)
 161         Null                        NPVariant (with type NPVariantNullType)
 162         Object (including Array)    NPVariant (with type NPVariantObjectType, objectValue will be a NPObject)
 163         Object (NPObject wrapper)   NPVariant (with type NPVariantObjectType)
 164
 165
 166         C          to                                         script
 167         NPVariant (with type NPVariantBoolType)               Boolean
 168         NPVariant (with type NPVariantInt32Type)              Number
 169         NPVariant (with type NPVariantDoubleType)             Number
 170         NPVariant (with type NPVariantStringType)             String
 171         NPVariant (with type NPVariantUndefinedType)          Undefined
 172         NPVariant (with type NPVariantNullType)               Null
 173         NPArray                                               Array (restricted)
 174         NObject                                               Object or (NPObject wrapper)
 175
 176 */
 177
 178 typedef void *NPIdentifier;
 179
 180 /*
 181     NPObjects have methods and properties.  Methods and properties are
 182     identified with NPIdentifiers.  These identifiers may be reflected
 183     in script.  NPIdentifiers can be either strings or integers, IOW,
 184     methods and properties can be identified by either strings or
 185     integers (i.e. foo["bar"] vs foo[1]). NPIdentifiers can be
 186     compared using ==.  In case of any errors, the requested
 187     NPIdentifier(s) will be NULL.
 188 */
 189 NPIdentifier NPN_GetStringIdentifier(const NPUTF8 *name);
 190 void NPN_GetStringIdentifiers(const NPUTF8 **names, int32_t nameCount, NPIdentifier *identifiers);
 191 NPIdentifier NPN_GetIntIdentifier(int32_t intid);
 192 NPBool NPN_IdentifierIsString(NPIdentifier identifier);
 193 NPUTF8 *NPN_UTF8FromIdentifier (NPIdentifier identifier);
 194
 195 /*
 196     NPObject behavior is implemented using the following set of callback functions.
 197
 198     The NPVariant *result parameter of NPInvokeFunctionPtr and NPGetPropertyFunctionPtr functions
 199     should be initialized using one of the NPN_InitializeVariantXXX functions.  The variant result
 200     of the two functions will be released using NPN_ReleaseVariantValue().
 201 */
 202 typedef NPObject *(*NPAllocateFunctionPtr)();
 203 typedef void (*NPDeallocateFunctionPtr)(NPObject *obj);
 204 typedef void (*NPInvalidateFunctionPtr)(NPObject *obj);
 205 typedef NPBool (*NPHasMethodFunctionPtr)(NPClass *theClass, NPIdentifier name);
 206 typedef NPBool (*NPInvokeFunctionPtr)(NPObject *obj, NPIdentifier name, const NPVariant *args, unsigned argCount, NPVariant *result);
 207 typedef NPBool (*NPHasPropertyFunctionPtr)(NPClass *theClass, NPIdentifier name);
 208 typedef NPBool (*NPGetPropertyFunctionPtr)(NPObject *obj, NPIdentifier name, NPVariant *result);
 209 typedef NPBool (*NPSetPropertyFunctionPtr)(NPObject *obj, NPIdentifier name, const NPVariant *value);
 210
 211 /*
 212     NPObjects returned by create have a reference count of one.  It is the caller's responsibility
 213     to release the returned object.
 214
 215     NPInvokeFunctionPtr function may return false to indicate a the method could not be invoked.
 216
 217     NPGetPropertyFunctionPtr and NPSetPropertyFunctionPtr may return false to indicate a property doesn't
 218     exist.
 219
 220     NPInvalidateFunctionPtr is called by the scripting environment when the native code is
 221     shutdown.  Any attempt to message a NPObject instance after the invalidate
 222     callback has been called will result in undefined behavior, even if the
 223     native code is still retaining those NPObject instances.
 224     (The runtime will typically return immediately, with 0 or NULL, from an attempt to
 225     dispatch to a NPObject, but this behavior should not be depended upon.)
 226 */
 227 struct NPClass
 228 {
 229     uint32_t structVersion;
 230     NPAllocateFunctionPtr allocate;
 231     NPDeallocateFunctionPtr deallocate;
 232     NPInvalidateFunctionPtr invalidate;
 233     NPHasMethodFunctionPtr hasMethod;
 234     NPInvokeFunctionPtr invoke;
 235     NPHasPropertyFunctionPtr hasProperty;
 236     NPGetPropertyFunctionPtr getProperty;
 237     NPSetPropertyFunctionPtr setProperty;
 238 };
 239
 240 #define kNPClassStructVersion1 1
 241 #define kNPClassStructVersionCurrent kNPClassStructVersion1
 242
 243 struct NPObject {
 244     NPClass *_class;
 245     uint32_t referenceCount;
 246     // Additional space may be allocated here by types of NPObjects
 247 };
 248
 249 /*
 250     If the class has an allocate function, NPN_CreateObject invokes that function,
 251     otherwise a NPObject is allocated and returned.  If a class has an allocate
 252     function it is the responsibility of that implementation to set the initial retain
 253     count to 1.
 254 */
 255 NPObject *NPN_CreateObject (NPClass *aClass);
 256
 257 /*
 258     Increment the NPObject's reference count.
 259 */
 260 NPObject *NPN_RetainObject (NPObject *obj);
 261
 262 /*
 263     Decremented the NPObject's reference count.  If the reference
 264     count goes to zero, the class's destroy function is invoke if
 265     specified, otherwise the object is freed directly.
 266 */
 267 void NPN_ReleaseObject (NPObject *obj);
 268
 269 /*
 270     Functions to access script objects represented by NPObject.
 271
 272     Calls to script objects are asynchronous.  If a function returns a value, it
 273     will be supplied via the NPScriptResultFunctionPtr callback.
 274
 275     Calls made from plugin code to script may be made from any thread.
 276
 277     Calls made from script to the plugin will always be made on the main
 278     user agent thread, this include calls to NPScriptResultFunctionPtr callbacks.
 279 */
 280 NPBool NPN_Call (NPObject *obj, NPIdentifier methodName, const NPVariant *args, unsigned argCount, NPVariant *result);
 281 NPBool NPN_Evaluate (NPObject *obj, NPString *script, NPVariant *result);
 282 NPBool NPN_GetProperty (NPObject *obj, NPIdentifier  propertyName, NPVariant *result);
 283 NPBool NPN_SetProperty (NPObject *obj, NPIdentifier  propertyName, const NPVariant *value);
 284 NPBool NPN_RemoveProperty (NPObject *obj, NPIdentifier propertyName);
 285
 286 /*
 287     NPN_SetException may be called to trigger a script exception upon return
 288     from entry points into NPObjects.
 289 */
 290 void NPN_SetException (NPObject *obj, NPString *message);
 291
 292 #ifdef __cplusplus
 293 }
 294 #endif
 295
 296 #endif