1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/dom/plugins/base/npruntime.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,393 @@
1.4 +/* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/*
1.6 + * Copyright (c) 2004, Apple Computer, Inc. and The Mozilla Foundation.
1.7 + * All rights reserved.
1.8 + *
1.9 + * Redistribution and use in source and binary forms, with or without
1.10 + * modification, are permitted provided that the following conditions are
1.11 + * met:
1.12 + *
1.13 + * 1. Redistributions of source code must retain the above copyright
1.14 + * notice, this list of conditions and the following disclaimer.
1.15 + * 2. Redistributions in binary form must reproduce the above copyright
1.16 + * notice, this list of conditions and the following disclaimer in the
1.17 + * documentation and/or other materials provided with the distribution.
1.18 + * 3. Neither the names of Apple Computer, Inc. ("Apple") or The Mozilla
1.19 + * Foundation ("Mozilla") nor the names of their contributors may be used
1.20 + * to endorse or promote products derived from this software without
1.21 + * specific prior written permission.
1.22 + *
1.23 + * THIS SOFTWARE IS PROVIDED BY APPLE, MOZILLA AND THEIR CONTRIBUTORS "AS
1.24 + * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
1.25 + * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
1.26 + * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE, MOZILLA OR
1.27 + * THEIR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
1.28 + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
1.29 + * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
1.30 + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
1.31 + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
1.32 + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
1.33 + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1.34 + *
1.35 + */
1.36 +#ifndef _NP_RUNTIME_H_
1.37 +#define _NP_RUNTIME_H_
1.38 +
1.39 +#ifdef __cplusplus
1.40 +extern "C" {
1.41 +#endif
1.42 +
1.43 +#include "nptypes.h"
1.44 +
1.45 +/*
1.46 + This API is used to facilitate binding code written in C to script
1.47 + objects. The API in this header does not assume the presence of a
1.48 + user agent. That is, it can be used to bind C code to scripting
1.49 + environments outside of the context of a user agent.
1.50 +
1.51 + However, the normal use of the this API is in the context of a
1.52 + scripting environment running in a browser or other user agent.
1.53 + In particular it is used to support the extended Netscape
1.54 + script-ability API for plugins (NP-SAP). NP-SAP is an extension
1.55 + of the Netscape plugin API. As such we have adopted the use of
1.56 + the "NP" prefix for this API.
1.57 +
1.58 + The following NP{N|P}Variables were added to the Netscape plugin
1.59 + API (in npapi.h):
1.60 +
1.61 + NPNVWindowNPObject
1.62 + NPNVPluginElementNPObject
1.63 + NPPVpluginScriptableNPObject
1.64 +
1.65 + These variables are exposed through NPN_GetValue() and
1.66 + NPP_GetValue() (respectively) and are used to establish the
1.67 + initial binding between the user agent and native code. The DOM
1.68 + objects in the user agent can be examined and manipulated using
1.69 + the NPN_ functions that operate on NPObjects described in this
1.70 + header.
1.71 +
1.72 + To the extent possible the assumptions about the scripting
1.73 + language used by the scripting environment have been minimized.
1.74 +*/
1.75 +
1.76 +#define NP_BEGIN_MACRO do {
1.77 +#define NP_END_MACRO } while (0)
1.78 +
1.79 +/*
1.80 + Objects (non-primitive data) passed between 'C' and script is
1.81 + always wrapped in an NPObject. The 'interface' of an NPObject is
1.82 + described by an NPClass.
1.83 +*/
1.84 +typedef struct NPObject NPObject;
1.85 +typedef struct NPClass NPClass;
1.86 +
1.87 +typedef char NPUTF8;
1.88 +typedef struct _NPString {
1.89 + const NPUTF8 *UTF8Characters;
1.90 + uint32_t UTF8Length;
1.91 +} NPString;
1.92 +
1.93 +typedef enum {
1.94 + NPVariantType_Void,
1.95 + NPVariantType_Null,
1.96 + NPVariantType_Bool,
1.97 + NPVariantType_Int32,
1.98 + NPVariantType_Double,
1.99 + NPVariantType_String,
1.100 + NPVariantType_Object
1.101 +} NPVariantType;
1.102 +
1.103 +typedef struct _NPVariant {
1.104 + NPVariantType type;
1.105 + union {
1.106 + bool boolValue;
1.107 + int32_t intValue;
1.108 + double doubleValue;
1.109 + NPString stringValue;
1.110 + NPObject *objectValue;
1.111 + } value;
1.112 +} NPVariant;
1.113 +
1.114 +/*
1.115 + NPN_ReleaseVariantValue is called on all 'out' parameters
1.116 + references. Specifically it is to be called on variants that own
1.117 + their value, as is the case with all non-const NPVariant*
1.118 + arguments after a successful call to any methods (except this one)
1.119 + in this API.
1.120 +
1.121 + After calling NPN_ReleaseVariantValue, the type of the variant
1.122 + will be NPVariantType_Void.
1.123 +*/
1.124 +void NPN_ReleaseVariantValue(NPVariant *variant);
1.125 +
1.126 +#define NPVARIANT_IS_VOID(_v) ((_v).type == NPVariantType_Void)
1.127 +#define NPVARIANT_IS_NULL(_v) ((_v).type == NPVariantType_Null)
1.128 +#define NPVARIANT_IS_BOOLEAN(_v) ((_v).type == NPVariantType_Bool)
1.129 +#define NPVARIANT_IS_INT32(_v) ((_v).type == NPVariantType_Int32)
1.130 +#define NPVARIANT_IS_DOUBLE(_v) ((_v).type == NPVariantType_Double)
1.131 +#define NPVARIANT_IS_STRING(_v) ((_v).type == NPVariantType_String)
1.132 +#define NPVARIANT_IS_OBJECT(_v) ((_v).type == NPVariantType_Object)
1.133 +
1.134 +#define NPVARIANT_TO_BOOLEAN(_v) ((_v).value.boolValue)
1.135 +#define NPVARIANT_TO_INT32(_v) ((_v).value.intValue)
1.136 +#define NPVARIANT_TO_DOUBLE(_v) ((_v).value.doubleValue)
1.137 +#define NPVARIANT_TO_STRING(_v) ((_v).value.stringValue)
1.138 +#define NPVARIANT_TO_OBJECT(_v) ((_v).value.objectValue)
1.139 +
1.140 +#define VOID_TO_NPVARIANT(_v) \
1.141 +NP_BEGIN_MACRO \
1.142 + (_v).type = NPVariantType_Void; \
1.143 + (_v).value.objectValue = NULL; \
1.144 +NP_END_MACRO
1.145 +
1.146 +#define NULL_TO_NPVARIANT(_v) \
1.147 +NP_BEGIN_MACRO \
1.148 + (_v).type = NPVariantType_Null; \
1.149 + (_v).value.objectValue = NULL; \
1.150 +NP_END_MACRO
1.151 +
1.152 +#define BOOLEAN_TO_NPVARIANT(_val, _v) \
1.153 +NP_BEGIN_MACRO \
1.154 + (_v).type = NPVariantType_Bool; \
1.155 + (_v).value.boolValue = !!(_val); \
1.156 +NP_END_MACRO
1.157 +
1.158 +#define INT32_TO_NPVARIANT(_val, _v) \
1.159 +NP_BEGIN_MACRO \
1.160 + (_v).type = NPVariantType_Int32; \
1.161 + (_v).value.intValue = _val; \
1.162 +NP_END_MACRO
1.163 +
1.164 +#define DOUBLE_TO_NPVARIANT(_val, _v) \
1.165 +NP_BEGIN_MACRO \
1.166 + (_v).type = NPVariantType_Double; \
1.167 + (_v).value.doubleValue = _val; \
1.168 +NP_END_MACRO
1.169 +
1.170 +#define STRINGZ_TO_NPVARIANT(_val, _v) \
1.171 +NP_BEGIN_MACRO \
1.172 + (_v).type = NPVariantType_String; \
1.173 + NPString str = { _val, (uint32_t)(strlen(_val)) }; \
1.174 + (_v).value.stringValue = str; \
1.175 +NP_END_MACRO
1.176 +
1.177 +#define STRINGN_TO_NPVARIANT(_val, _len, _v) \
1.178 +NP_BEGIN_MACRO \
1.179 + (_v).type = NPVariantType_String; \
1.180 + NPString str = { _val, (uint32_t)(_len) }; \
1.181 + (_v).value.stringValue = str; \
1.182 +NP_END_MACRO
1.183 +
1.184 +#define OBJECT_TO_NPVARIANT(_val, _v) \
1.185 +NP_BEGIN_MACRO \
1.186 + (_v).type = NPVariantType_Object; \
1.187 + (_v).value.objectValue = _val; \
1.188 +NP_END_MACRO
1.189 +
1.190 +
1.191 +/*
1.192 + Type mappings (JavaScript types have been used for illustration
1.193 + purposes):
1.194 +
1.195 + JavaScript to C (NPVariant with type:)
1.196 + undefined NPVariantType_Void
1.197 + null NPVariantType_Null
1.198 + Boolean NPVariantType_Bool
1.199 + Number NPVariantType_Double or NPVariantType_Int32
1.200 + String NPVariantType_String
1.201 + Object NPVariantType_Object
1.202 +
1.203 + C (NPVariant with type:) to JavaScript
1.204 + NPVariantType_Void undefined
1.205 + NPVariantType_Null null
1.206 + NPVariantType_Bool Boolean
1.207 + NPVariantType_Int32 Number
1.208 + NPVariantType_Double Number
1.209 + NPVariantType_String String
1.210 + NPVariantType_Object Object
1.211 +*/
1.212 +
1.213 +typedef void *NPIdentifier;
1.214 +
1.215 +/*
1.216 + NPObjects have methods and properties. Methods and properties are
1.217 + identified with NPIdentifiers. These identifiers may be reflected
1.218 + in script. NPIdentifiers can be either strings or integers, IOW,
1.219 + methods and properties can be identified by either strings or
1.220 + integers (i.e. foo["bar"] vs foo[1]). NPIdentifiers can be
1.221 + compared using ==. In case of any errors, the requested
1.222 + NPIdentifier(s) will be NULL. NPIdentifier lifetime is controlled
1.223 + by the browser. Plugins do not need to worry about memory management
1.224 + with regards to NPIdentifiers.
1.225 +*/
1.226 +NPIdentifier NPN_GetStringIdentifier(const NPUTF8 *name);
1.227 +void NPN_GetStringIdentifiers(const NPUTF8 **names, int32_t nameCount,
1.228 + NPIdentifier *identifiers);
1.229 +NPIdentifier NPN_GetIntIdentifier(int32_t intid);
1.230 +bool NPN_IdentifierIsString(NPIdentifier identifier);
1.231 +
1.232 +/*
1.233 + The NPUTF8 returned from NPN_UTF8FromIdentifier SHOULD be freed.
1.234 +*/
1.235 +NPUTF8 *NPN_UTF8FromIdentifier(NPIdentifier identifier);
1.236 +
1.237 +/*
1.238 + Get the integer represented by identifier. If identifier is not an
1.239 + integer identifier, the behaviour is undefined.
1.240 +*/
1.241 +int32_t NPN_IntFromIdentifier(NPIdentifier identifier);
1.242 +
1.243 +/*
1.244 + NPObject behavior is implemented using the following set of
1.245 + callback functions.
1.246 +
1.247 + The NPVariant *result argument of these functions (where
1.248 + applicable) should be released using NPN_ReleaseVariantValue().
1.249 +*/
1.250 +typedef NPObject *(*NPAllocateFunctionPtr)(NPP npp, NPClass *aClass);
1.251 +typedef void (*NPDeallocateFunctionPtr)(NPObject *npobj);
1.252 +typedef void (*NPInvalidateFunctionPtr)(NPObject *npobj);
1.253 +typedef bool (*NPHasMethodFunctionPtr)(NPObject *npobj, NPIdentifier name);
1.254 +typedef bool (*NPInvokeFunctionPtr)(NPObject *npobj, NPIdentifier name,
1.255 + const NPVariant *args, uint32_t argCount,
1.256 + NPVariant *result);
1.257 +typedef bool (*NPInvokeDefaultFunctionPtr)(NPObject *npobj,
1.258 + const NPVariant *args,
1.259 + uint32_t argCount,
1.260 + NPVariant *result);
1.261 +typedef bool (*NPHasPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name);
1.262 +typedef bool (*NPGetPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name,
1.263 + NPVariant *result);
1.264 +typedef bool (*NPSetPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name,
1.265 + const NPVariant *value);
1.266 +typedef bool (*NPRemovePropertyFunctionPtr)(NPObject *npobj,
1.267 + NPIdentifier name);
1.268 +typedef bool (*NPEnumerationFunctionPtr)(NPObject *npobj, NPIdentifier **value,
1.269 + uint32_t *count);
1.270 +typedef bool (*NPConstructFunctionPtr)(NPObject *npobj,
1.271 + const NPVariant *args,
1.272 + uint32_t argCount,
1.273 + NPVariant *result);
1.274 +
1.275 +/*
1.276 + NPObjects returned by create, retain, invoke, and getProperty pass
1.277 + a reference count to the caller. That is, the callee adds a
1.278 + reference count which passes to the caller. It is the caller's
1.279 + responsibility to release the returned object.
1.280 +
1.281 + NPInvokeFunctionPtr function may return 0 to indicate a void
1.282 + result.
1.283 +
1.284 + NPInvalidateFunctionPtr is called by the scripting environment
1.285 + when the native code is shutdown. Any attempt to message a
1.286 + NPObject instance after the invalidate callback has been
1.287 + called will result in undefined behavior, even if the native code
1.288 + is still retaining those NPObject instances. (The runtime
1.289 + will typically return immediately, with 0 or NULL, from an
1.290 + attempt to dispatch to a NPObject, but this behavior should not
1.291 + be depended upon.)
1.292 +
1.293 + The NPEnumerationFunctionPtr function may pass an array of
1.294 + NPIdentifiers back to the caller. The callee allocs the memory of
1.295 + the array using NPN_MemAlloc(), and it's the caller's responsibility
1.296 + to release it using NPN_MemFree().
1.297 +*/
1.298 +struct NPClass
1.299 +{
1.300 + uint32_t structVersion;
1.301 + NPAllocateFunctionPtr allocate;
1.302 + NPDeallocateFunctionPtr deallocate;
1.303 + NPInvalidateFunctionPtr invalidate;
1.304 + NPHasMethodFunctionPtr hasMethod;
1.305 + NPInvokeFunctionPtr invoke;
1.306 + NPInvokeDefaultFunctionPtr invokeDefault;
1.307 + NPHasPropertyFunctionPtr hasProperty;
1.308 + NPGetPropertyFunctionPtr getProperty;
1.309 + NPSetPropertyFunctionPtr setProperty;
1.310 + NPRemovePropertyFunctionPtr removeProperty;
1.311 + NPEnumerationFunctionPtr enumerate;
1.312 + NPConstructFunctionPtr construct;
1.313 +};
1.314 +
1.315 +#define NP_CLASS_STRUCT_VERSION 3
1.316 +
1.317 +#define NP_CLASS_STRUCT_VERSION_ENUM 2
1.318 +#define NP_CLASS_STRUCT_VERSION_CTOR 3
1.319 +
1.320 +#define NP_CLASS_STRUCT_VERSION_HAS_ENUM(npclass) \
1.321 + ((npclass)->structVersion >= NP_CLASS_STRUCT_VERSION_ENUM)
1.322 +
1.323 +#define NP_CLASS_STRUCT_VERSION_HAS_CTOR(npclass) \
1.324 + ((npclass)->structVersion >= NP_CLASS_STRUCT_VERSION_CTOR)
1.325 +
1.326 +struct NPObject {
1.327 + NPClass *_class;
1.328 + uint32_t referenceCount;
1.329 + /*
1.330 + * Additional space may be allocated here by types of NPObjects
1.331 + */
1.332 +};
1.333 +
1.334 +/*
1.335 + If the class has an allocate function, NPN_CreateObject invokes
1.336 + that function, otherwise a NPObject is allocated and
1.337 + returned. This method will initialize the referenceCount member of
1.338 + the NPObject to 1.
1.339 +*/
1.340 +NPObject *NPN_CreateObject(NPP npp, NPClass *aClass);
1.341 +
1.342 +/*
1.343 + Increment the NPObject's reference count.
1.344 +*/
1.345 +NPObject *NPN_RetainObject(NPObject *npobj);
1.346 +
1.347 +/*
1.348 + Decremented the NPObject's reference count. If the reference
1.349 + count goes to zero, the class's destroy function is invoke if
1.350 + specified, otherwise the object is freed directly.
1.351 +*/
1.352 +void NPN_ReleaseObject(NPObject *npobj);
1.353 +
1.354 +/*
1.355 + Functions to access script objects represented by NPObject.
1.356 +
1.357 + Calls to script objects are synchronous. If a function returns a
1.358 + value, it will be supplied via the result NPVariant
1.359 + argument. Successful calls will return true, false will be
1.360 + returned in case of an error.
1.361 +
1.362 + Calls made from plugin code to script must be made from the thread
1.363 + on which the plugin was initialized.
1.364 +*/
1.365 +
1.366 +bool NPN_Invoke(NPP npp, NPObject *npobj, NPIdentifier methodName,
1.367 + const NPVariant *args, uint32_t argCount, NPVariant *result);
1.368 +bool NPN_InvokeDefault(NPP npp, NPObject *npobj, const NPVariant *args,
1.369 + uint32_t argCount, NPVariant *result);
1.370 +bool NPN_Evaluate(NPP npp, NPObject *npobj, NPString *script,
1.371 + NPVariant *result);
1.372 +bool NPN_GetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName,
1.373 + NPVariant *result);
1.374 +bool NPN_SetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName,
1.375 + const NPVariant *value);
1.376 +bool NPN_RemoveProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName);
1.377 +bool NPN_HasProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName);
1.378 +bool NPN_HasMethod(NPP npp, NPObject *npobj, NPIdentifier methodName);
1.379 +bool NPN_Enumerate(NPP npp, NPObject *npobj, NPIdentifier **identifier,
1.380 + uint32_t *count);
1.381 +bool NPN_Construct(NPP npp, NPObject *npobj, const NPVariant *args,
1.382 + uint32_t argCount, NPVariant *result);
1.383 +
1.384 +/*
1.385 + NPN_SetException may be called to trigger a script exception upon
1.386 + return from entry points into NPObjects. Typical usage:
1.387 +
1.388 + NPN_SetException (npobj, message);
1.389 +*/
1.390 +void NPN_SetException(NPObject *npobj, const NPUTF8 *message);
1.391 +
1.392 +#ifdef __cplusplus
1.393 +}
1.394 +#endif
1.395 +
1.396 +#endif
