Warning, file /multimedia/kmplayer/src/moz-sdk/npruntime.h was not indexed or was modified since last indexation (in which case cross-reference links may be missing, inaccurate or erroneous).
0001 /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ 0002 /* 0003 * Copyright © 2004, Apple Computer, Inc. and The Mozilla Foundation. 0004 * All rights reserved. 0005 * 0006 * Redistribution and use in source and binary forms, with or without 0007 * modification, are permitted provided that the following conditions are 0008 * met: 0009 * 0010 * 1. Redistributions of source code must retain the above copyright 0011 * notice, this list of conditions and the following disclaimer. 0012 * 2. Redistributions in binary form must reproduce the above copyright 0013 * notice, this list of conditions and the following disclaimer in the 0014 * documentation and/or other materials provided with the distribution. 0015 * 3. Neither the names of Apple Computer, Inc. ("Apple") or The Mozilla 0016 * Foundation ("Mozilla") nor the names of their contributors may be used 0017 * to endorse or promote products derived from this software without 0018 * specific prior written permission. 0019 * 0020 * THIS SOFTWARE IS PROVIDED BY APPLE, MOZILLA AND THEIR CONTRIBUTORS "AS 0021 * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 0022 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 0023 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE, MOZILLA OR 0024 * THEIR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 0025 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 0026 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 0027 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 0028 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 0029 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 0030 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 0031 * 0032 * Revision 1 (March 4, 2004): 0033 * Initial proposal. 0034 * 0035 * Revision 2 (March 10, 2004): 0036 * All calls into script were made asynchronous. Results are 0037 * provided via the NPScriptResultFunctionPtr callback. 0038 * 0039 * Revision 3 (March 10, 2004): 0040 * Corrected comments to not refer to class retain/release FunctionPtrs. 0041 * 0042 * Revision 4 (March 11, 2004): 0043 * Added additional convenience NPN_SetExceptionWithUTF8(). 0044 * Changed NPHasPropertyFunctionPtr and NPHasMethodFunctionPtr to take NPClass 0045 * pointers instead of NPObject pointers. 0046 * Added NPIsValidIdentifier(). 0047 * 0048 * Revision 5 (March 17, 2004): 0049 * Added context parameter to result callbacks from ScriptObject functions. 0050 * 0051 * Revision 6 (March 29, 2004): 0052 * Renamed functions implemented by user agent to NPN_*. Removed _ from 0053 * type names. 0054 * Renamed "JavaScript" types to "Script". 0055 * 0056 * Revision 7 (April 21, 2004): 0057 * NPIdentifier becomes a void*, was int32_t 0058 * Remove NP_IsValidIdentifier, renamed NP_IdentifierFromUTF8 to NP_GetIdentifier 0059 * Added NPVariant and modified functions to use this new type. 0060 * 0061 * Revision 8 (July 9, 2004): 0062 * Updated to joint Apple-Mozilla license. 0063 * 0064 */ 0065 #ifndef _NP_RUNTIME_H_ 0066 #define _NP_RUNTIME_H_ 0067 0068 #ifdef __cplusplus 0069 extern "C" { 0070 #endif 0071 0072 #include "nptypes.h" 0073 0074 /* 0075 This API is used to facilitate binding code written in C to script 0076 objects. The API in this header does not assume the presence of a 0077 user agent. That is, it can be used to bind C code to scripting 0078 environments outside of the context of a user agent. 0079 0080 However, the normal use of the this API is in the context of a 0081 scripting environment running in a browser or other user agent. 0082 In particular it is used to support the extended Netscape 0083 script-ability API for plugins (NP-SAP). NP-SAP is an extension 0084 of the Netscape plugin API. As such we have adopted the use of 0085 the "NP" prefix for this API. 0086 0087 The following NP{N|P}Variables were added to the Netscape plugin 0088 API (in npapi.h): 0089 0090 NPNVWindowNPObject 0091 NPNVPluginElementNPObject 0092 NPPVpluginScriptableNPObject 0093 0094 These variables are exposed through NPN_GetValue() and 0095 NPP_GetValue() (respectively) and are used to establish the 0096 initial binding between the user agent and native code. The DOM 0097 objects in the user agent can be examined and manipulated using 0098 the NPN_ functions that operate on NPObjects described in this 0099 header. 0100 0101 To the extent possible the assumptions about the scripting 0102 language used by the scripting environment have been minimized. 0103 */ 0104 0105 #define NP_BEGIN_MACRO do { 0106 #define NP_END_MACRO } while (0) 0107 0108 /* 0109 Objects (non-primitive data) passed between 'C' and script is 0110 always wrapped in an NPObject. The 'interface' of an NPObject is 0111 described by an NPClass. 0112 */ 0113 typedef struct NPObject NPObject; 0114 typedef struct NPClass NPClass; 0115 0116 typedef char NPUTF8; 0117 typedef struct _NPString { 0118 const NPUTF8 *utf8characters; 0119 uint32_t utf8length; 0120 } NPString; 0121 0122 typedef enum { 0123 NPVariantType_Void, 0124 NPVariantType_Null, 0125 NPVariantType_Bool, 0126 NPVariantType_Int32, 0127 NPVariantType_Double, 0128 NPVariantType_String, 0129 NPVariantType_Object 0130 } NPVariantType; 0131 0132 typedef struct _NPVariant { 0133 NPVariantType type; 0134 union { 0135 bool boolValue; 0136 int32_t intValue; 0137 double doubleValue; 0138 NPString stringValue; 0139 NPObject *objectValue; 0140 } value; 0141 } NPVariant; 0142 0143 /* 0144 NPN_ReleaseVariantValue is called on all 'out' parameters 0145 references. Specifically it is to be called on variants that own 0146 their value, as is the case with all non-const NPVariant* 0147 arguments after a successful call to any methods (except this one) 0148 in this API. 0149 0150 After calling NPN_ReleaseVariantValue, the type of the variant 0151 will be NPVariantType_Void. 0152 */ 0153 void NPN_ReleaseVariantValue(NPVariant *variant); 0154 0155 #define NPVARIANT_IS_VOID(_v) ((_v).type == NPVariantType_Void) 0156 #define NPVARIANT_IS_NULL(_v) ((_v).type == NPVariantType_Null) 0157 #define NPVARIANT_IS_BOOLEAN(_v) ((_v).type == NPVariantType_Bool) 0158 #define NPVARIANT_IS_INT32(_v) ((_v).type == NPVariantType_Int32) 0159 #define NPVARIANT_IS_DOUBLE(_v) ((_v).type == NPVariantType_Double) 0160 #define NPVARIANT_IS_STRING(_v) ((_v).type == NPVariantType_String) 0161 #define NPVARIANT_IS_OBJECT(_v) ((_v).type == NPVariantType_Object) 0162 0163 #define NPVARIANT_TO_BOOLEAN(_v) ((_v).value.boolValue) 0164 #define NPVARIANT_TO_INT32(_v) ((_v).value.intValue) 0165 #define NPVARIANT_TO_DOUBLE(_v) ((_v).value.doubleValue) 0166 #define NPVARIANT_TO_STRING(_v) ((_v).value.stringValue) 0167 #define NPVARIANT_TO_OBJECT(_v) ((_v).value.objectValue) 0168 0169 #define VOID_TO_NPVARIANT(_v) \ 0170 NP_BEGIN_MACRO \ 0171 (_v).type = NPVariantType_Void; \ 0172 (_v).value.objectValue = NULL; \ 0173 NP_END_MACRO 0174 0175 #define NULL_TO_NPVARIANT(_v) \ 0176 NP_BEGIN_MACRO \ 0177 (_v).type = NPVariantType_Null; \ 0178 (_v).value.objectValue = NULL; \ 0179 NP_END_MACRO 0180 0181 #define BOOLEAN_TO_NPVARIANT(_val, _v) \ 0182 NP_BEGIN_MACRO \ 0183 (_v).type = NPVariantType_Bool; \ 0184 (_v).value.boolValue = !!(_val); \ 0185 NP_END_MACRO 0186 0187 #define INT32_TO_NPVARIANT(_val, _v) \ 0188 NP_BEGIN_MACRO \ 0189 (_v).type = NPVariantType_Int32; \ 0190 (_v).value.intValue = _val; \ 0191 NP_END_MACRO 0192 0193 #define DOUBLE_TO_NPVARIANT(_val, _v) \ 0194 NP_BEGIN_MACRO \ 0195 (_v).type = NPVariantType_Double; \ 0196 (_v).value.doubleValue = _val; \ 0197 NP_END_MACRO 0198 0199 #define STRINGZ_TO_NPVARIANT(_val, _v) \ 0200 NP_BEGIN_MACRO \ 0201 (_v).type = NPVariantType_String; \ 0202 NPString str = { _val, strlen(_val) }; \ 0203 (_v).value.stringValue = str; \ 0204 NP_END_MACRO 0205 0206 #define STRINGN_TO_NPVARIANT(_val, _len, _v) \ 0207 NP_BEGIN_MACRO \ 0208 (_v).type = NPVariantType_String; \ 0209 NPString str = { _val, _len }; \ 0210 (_v).value.stringValue = str; \ 0211 NP_END_MACRO 0212 0213 #define OBJECT_TO_NPVARIANT(_val, _v) \ 0214 NP_BEGIN_MACRO \ 0215 (_v).type = NPVariantType_Object; \ 0216 (_v).value.objectValue = _val; \ 0217 NP_END_MACRO 0218 0219 0220 /* 0221 Type mappings (JavaScript types have been used for illustration 0222 purposes): 0223 0224 JavaScript to C (NPVariant with type:) 0225 undefined NPVariantType_Void 0226 null NPVariantType_Null 0227 Boolean NPVariantType_Bool 0228 Number NPVariantType_Double or NPVariantType_Int32 0229 String NPVariantType_String 0230 Object NPVariantType_Object 0231 0232 C (NPVariant with type:) to JavaScript 0233 NPVariantType_Void undefined 0234 NPVariantType_Null null 0235 NPVariantType_Bool Boolean 0236 NPVariantType_Int32 Number 0237 NPVariantType_Double Number 0238 NPVariantType_String String 0239 NPVariantType_Object Object 0240 */ 0241 0242 typedef void *NPIdentifier; 0243 0244 /* 0245 NPObjects have methods and properties. Methods and properties are 0246 identified with NPIdentifiers. These identifiers may be reflected 0247 in script. NPIdentifiers can be either strings or integers, IOW, 0248 methods and properties can be identified by either strings or 0249 integers (i.e. foo["bar"] vs foo[1]). NPIdentifiers can be 0250 compared using ==. In case of any errors, the requested 0251 NPIdentifier(s) will be NULL. 0252 */ 0253 NPIdentifier NPN_GetStringIdentifier(const NPUTF8 *name); 0254 void NPN_GetStringIdentifiers(const NPUTF8 **names, int32_t nameCount, 0255 NPIdentifier *identifiers); 0256 NPIdentifier NPN_GetIntIdentifier(int32_t intid); 0257 bool NPN_IdentifierIsString(NPIdentifier identifier); 0258 0259 /* 0260 The NPUTF8 returned from NPN_UTF8FromIdentifier SHOULD be freed. 0261 */ 0262 NPUTF8 *NPN_UTF8FromIdentifier(NPIdentifier identifier); 0263 0264 /* 0265 Get the integer represented by identifier. If identifier is not an 0266 integer identifier, the behaviour is undefined. 0267 */ 0268 int32_t NPN_IntFromIdentifier(NPIdentifier identifier); 0269 0270 /* 0271 NPObject behavior is implemented using the following set of 0272 callback functions. 0273 0274 The NPVariant *result argument of these functions (where 0275 applicable) should be released using NPN_ReleaseVariantValue(). 0276 */ 0277 typedef NPObject *(*NPAllocateFunctionPtr)(NPP npp, NPClass *aClass); 0278 typedef void (*NPDeallocateFunctionPtr)(NPObject *npobj); 0279 typedef void (*NPInvalidateFunctionPtr)(NPObject *npobj); 0280 typedef bool (*NPHasMethodFunctionPtr)(NPObject *npobj, NPIdentifier name); 0281 typedef bool (*NPInvokeFunctionPtr)(NPObject *npobj, NPIdentifier name, 0282 const NPVariant *args, uint32_t argCount, 0283 NPVariant *result); 0284 typedef bool (*NPInvokeDefaultFunctionPtr)(NPObject *npobj, 0285 const NPVariant *args, 0286 uint32_t argCount, 0287 NPVariant *result); 0288 typedef bool (*NPHasPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name); 0289 typedef bool (*NPGetPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name, 0290 NPVariant *result); 0291 typedef bool (*NPSetPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name, 0292 const NPVariant *value); 0293 typedef bool (*NPRemovePropertyFunctionPtr)(NPObject *npobj, 0294 NPIdentifier name); 0295 typedef bool (*NPEnumerationFunctionPtr)(NPObject *npobj, NPIdentifier **value, 0296 uint32_t *count); 0297 typedef bool (*NPConstructFunctionPtr)(NPObject *npobj, 0298 const NPVariant *args, 0299 uint32_t argCount, 0300 NPVariant *result); 0301 0302 /* 0303 NPObjects returned by create, retain, invoke, and getProperty pass 0304 a reference count to the caller. That is, the callee adds a 0305 reference count which passes to the caller. It is the caller's 0306 responsibility to release the returned object. 0307 0308 NPInvokeFunctionPtr function may return 0 to indicate a void 0309 result. 0310 0311 NPInvalidateFunctionPtr is called by the scripting environment 0312 when the native code is shutdown. Any attempt to message a 0313 NPObject instance after the invalidate callback has been 0314 called will result in undefined behavior, even if the native code 0315 is still retaining those NPObject instances. (The runtime 0316 will typically return immediately, with 0 or NULL, from an attempt 0317 to dispatch to a NPObject, but this behavior should not be 0318 depended upon.) 0319 0320 The NPEnumerationFunctionPtr function may pass an array of 0321 NPIdentifiers back to the caller. The callee allocs the memory of 0322 the array using NPN_MemAlloc(), and it's the caller's responsibility 0323 to release it using NPN_MemFree(). 0324 */ 0325 struct NPClass 0326 { 0327 uint32_t structVersion; 0328 NPAllocateFunctionPtr allocate; 0329 NPDeallocateFunctionPtr deallocate; 0330 NPInvalidateFunctionPtr invalidate; 0331 NPHasMethodFunctionPtr hasMethod; 0332 NPInvokeFunctionPtr invoke; 0333 NPInvokeDefaultFunctionPtr invokeDefault; 0334 NPHasPropertyFunctionPtr hasProperty; 0335 NPGetPropertyFunctionPtr getProperty; 0336 NPSetPropertyFunctionPtr setProperty; 0337 NPRemovePropertyFunctionPtr removeProperty; 0338 NPEnumerationFunctionPtr enumerate; 0339 NPConstructFunctionPtr construct; 0340 }; 0341 0342 #define NP_CLASS_STRUCT_VERSION 3 0343 0344 #define NP_CLASS_STRUCT_VERSION_ENUM 2 0345 #define NP_CLASS_STRUCT_VERSION_CTOR 3 0346 0347 #define NP_CLASS_STRUCT_VERSION_HAS_ENUM(npclass) \ 0348 ((npclass)->structVersion >= NP_CLASS_STRUCT_VERSION_ENUM) 0349 0350 #define NP_CLASS_STRUCT_VERSION_HAS_CTOR(npclass) \ 0351 ((npclass)->structVersion >= NP_CLASS_STRUCT_VERSION_CTOR) 0352 0353 struct NPObject { 0354 NPClass *_class; 0355 uint32_t referenceCount; 0356 /* 0357 * Additional space may be allocated here by types of NPObjects 0358 */ 0359 }; 0360 0361 /* 0362 If the class has an allocate function, NPN_CreateObject invokes 0363 that function, otherwise a NPObject is allocated and 0364 returned. This method will initialize the referenceCount member of 0365 the NPObject to 1. 0366 */ 0367 NPObject *NPN_CreateObject(NPP npp, NPClass *aClass); 0368 0369 /* 0370 Increment the NPObject's reference count. 0371 */ 0372 NPObject *NPN_RetainObject(NPObject *npobj); 0373 0374 /* 0375 Decremented the NPObject's reference count. If the reference 0376 count goes to zero, the class's destroy function is invoke if 0377 specified, otherwise the object is freed directly. 0378 */ 0379 void NPN_ReleaseObject(NPObject *npobj); 0380 0381 /* 0382 Functions to access script objects represented by NPObject. 0383 0384 Calls to script objects are synchronous. If a function returns a 0385 value, it will be supplied via the result NPVariant 0386 argument. Successful calls will return true, false will be 0387 returned in case of an error. 0388 0389 Calls made from plugin code to script must be made from the thread 0390 on which the plugin was initialized. 0391 */ 0392 0393 bool NPN_Invoke(NPP npp, NPObject *npobj, NPIdentifier methodName, 0394 const NPVariant *args, uint32_t argCount, NPVariant *result); 0395 bool NPN_InvokeDefault(NPP npp, NPObject *npobj, const NPVariant *args, 0396 uint32_t argCount, NPVariant *result); 0397 bool NPN_Evaluate(NPP npp, NPObject *npobj, NPString *script, 0398 NPVariant *result); 0399 bool NPN_GetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName, 0400 NPVariant *result); 0401 bool NPN_SetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName, 0402 const NPVariant *value); 0403 bool NPN_RemoveProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName); 0404 bool NPN_HasProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName); 0405 bool NPN_HasMethod(NPP npp, NPObject *npobj, NPIdentifier methodName); 0406 bool NPN_Enumerate(NPP npp, NPObject *npobj, NPIdentifier **identifier, 0407 uint32_t *count); 0408 bool NPN_Construct(NPP npp, NPObject *npobj, const NPVariant *args, 0409 uint32_t argCount, NPVariant *result); 0410 0411 /* 0412 NPN_SetException may be called to trigger a script exception upon 0413 return from entry points into NPObjects. Typical usage: 0414 0415 NPN_SetException (npobj, message); 0416 */ 0417 void NPN_SetException(NPObject *npobj, const NPUTF8 *message); 0418 0419 #ifdef __cplusplus 0420 } 0421 #endif 0422 0423 #endif