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