"Fossies" - the Fresh Open Source Software Archive

Member "google-gadgets-for-linux-0.11.2/third_party/npapi/npruntime.h" (15 Mar 2009, 17376 Bytes) of package /linux/misc/old/google-gadgets-for-linux-0.11.2.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file.

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