"Fossies" - the Fresh Open Source Software Archive

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