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