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