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