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_SCRIPT_H_

    69 #define _NP_SCRIPT_H_

    70 

    71 #ifdef __cplusplus

    72 extern "C" {

    73 #endif

    74 

    75 #include <npapi.h>

    76 

    77 typedef unsigned char uint8_t;

    78 typedef signed char int8_t;

    79 typedef unsigned short uint16_t;

    80 typedef short int16_t;

    81 typedef unsigned int uint32_t;

    82 typedef int int32_t;

    83 typedef long long int64_t;

    84 typedef unsigned long long uint64_t;

    85 

    86 typedef unsigned long uintptr_t;

    87 typedef unsigned long intptr_t;

    88 

    89 #if defined(XP_MACOSX) && defined(__LP64__)

    90 #error 64-bit Netscape plug-ins are not supported on Mac OS X

    91 #endif

    92 

    93 /*

    94     This API is used to facilitate binding code written in C to script

    95     objects.  The API in this header does not assume the presence of a

    96     user agent.  That is, it can be used to bind C code to scripting

    97     environments outside of the context of a user agent.

    98     

    99     However, the normal use of the this API is in the context of a

   100     scripting environment running in a browser or other user agent.

   101     In particular it is used to support the extended Netscape

   102     script-ability API for plugins (NP-SAP).  NP-SAP is an extension

   103     of the Netscape plugin API.  As such we have adopted the use of

   104     the "NP" prefix for this API.

   105 

   106     The following NP{N|P}Variables were added to the Netscape plugin

   107     API (in npapi.h):

   108 

   109     NPNVWindowNPObject

   110     NPNVPluginElementNPObject

   111     NPPVpluginScriptableNPObject

   112 

   113     These variables are exposed through NPN_GetValue() and

   114     NPP_GetValue() (respectively) and are used to establish the

   115     initial binding between the user agent and native code.  The DOM

   116     objects in the user agent can be examined and manipulated using

   117     the NPN_ functions that operate on NPObjects described in this

   118     header.

   119 

   120     To the extent possible the assumptions about the scripting

   121     language used by the scripting environment have been minimized.

   122 */

   123 

   124 

   125 /*

   126     Objects (non-primitive data) passed between 'C' and script is

   127     always wrapped in an NPObject.  The 'interface' of an NPObject is

   128     described by an NPClass.

   129 */

   130 typedef struct NPObject NPObject;

   131 typedef struct NPClass NPClass;

   132 

   133 typedef char NPUTF8;

   134 typedef struct _NPString {

   135     const NPUTF8 *UTF8Characters;

   136     uint32_t UTF8Length;

   137 } NPString;

   138   

   139 typedef enum {

   140     NPVariantType_Void,

   141     NPVariantType_Null,

   142     NPVariantType_Bool,

   143     NPVariantType_Int32,

   144     NPVariantType_Double,

   145     NPVariantType_String,

   146     NPVariantType_Object

   147 } NPVariantType;

   148 

   149 typedef struct _NPVariant {

   150     NPVariantType type;

   151     union {

   152         bool boolValue;

   153         int32_t intValue;

   154         double doubleValue;

   155         NPString stringValue;

   156         NPObject *objectValue;

   157     } value;

   158 } NPVariant;

   159 

   160 

   161 #define NPVARIANT_IS_VOID(_v)    ((_v).type == NPVariantType_Void)

   162 #define NPVARIANT_IS_NULL(_v)    ((_v).type == NPVariantType_Null)

   163 #define NPVARIANT_IS_BOOLEAN(_v) ((_v).type == NPVariantType_Bool)

   164 #define NPVARIANT_IS_INT32(_v)   ((_v).type == NPVariantType_Int32)

   165 #define NPVARIANT_IS_DOUBLE(_v)  ((_v).type == NPVariantType_Double)

   166 #define NPVARIANT_IS_STRING(_v)  ((_v).type == NPVariantType_String)

   167 #define NPVARIANT_IS_OBJECT(_v)  ((_v).type == NPVariantType_Object)

   168 

   169 #define NPVARIANT_TO_BOOLEAN(_v) ((_v).value.boolValue)

   170 #define NPVARIANT_TO_INT32(_v)   ((_v).value.intValue)

   171 #define NPVARIANT_TO_DOUBLE(_v)  ((_v).value.doubleValue)

   172 #define NPVARIANT_TO_STRING(_v)  ((_v).value.stringValue)

   173 #define NPVARIANT_TO_OBJECT(_v)  ((_v).value.objectValue)

   174 

   175 #define NP_BEGIN_MACRO  do {

   176 #define NP_END_MACRO    } while (0)

   177 

   178 #define VOID_TO_NPVARIANT(_v)                NP_BEGIN_MACRO (_v).type = NPVariantType_Void; (_v).value.objectValue = NULL; NP_END_MACRO

   179 #define NULL_TO_NPVARIANT(_v)                NP_BEGIN_MACRO (_v).type = NPVariantType_Null; (_v).value.objectValue = NULL; NP_END_MACRO

   180 #define BOOLEAN_TO_NPVARIANT(_val, _v)       NP_BEGIN_MACRO (_v).type = NPVariantType_Bool; (_v).value.boolValue = !!(_val); NP_END_MACRO

   181 #define INT32_TO_NPVARIANT(_val, _v)         NP_BEGIN_MACRO (_v).type = NPVariantType_Int32; (_v).value.intValue = _val; NP_END_MACRO

   182 #define DOUBLE_TO_NPVARIANT(_val, _v)        NP_BEGIN_MACRO (_v).type = NPVariantType_Double; (_v).value.doubleValue = _val; NP_END_MACRO

   183 #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

   184 #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

   185 #define OBJECT_TO_NPVARIANT(_val, _v)        NP_BEGIN_MACRO (_v).type = NPVariantType_Object; (_v).value.objectValue = _val; NP_END_MACRO

   186 

   187 /*

   188         Type mappings (JavaScript types have been used for illustration

   189     purposes):

   190 

   191         JavaScript       to             C (NPVariant with type:)

   192         undefined                       NPVariantType_Void

   193         null                            NPVariantType_Null

   194         Boolean                         NPVariantType_Bool

   195         Number                          NPVariantType_Double or NPVariantType_Int32

   196         String                          NPVariantType_String

   197         Object                          NPVariantType_Object

   198 

   199         C (NPVariant with type:)   to   JavaScript

   200         NPVariantType_Void              undefined

   201         NPVariantType_Null              null

   202         NPVariantType_Bool              Boolean 

   203         NPVariantType_Int32             Number

   204         NPVariantType_Double            Number

   205         NPVariantType_String            String

   206         NPVariantType_Object            Object

   207 */

   208 

   209 typedef void *NPIdentifier;

   210 /*

   211     NPObjects have methods and properties.  Methods and properties are

   212     identified with NPIdentifiers.  These identifiers may be reflected

   213     in script.  NPIdentifiers can be either strings or integers, IOW,

   214     methods and properties can be identified by either strings or

   215     integers (i.e. foo["bar"] vs foo[1]). NPIdentifiers can be

   216     compared using ==.  In case of any errors, the requested

   217     NPIdentifier(s) will be NULL.

   218 */

   219 IMPORT_C NPIdentifier NPN_GetStringIdentifier(const NPUTF8 *name);

   220 IMPORT_C void NPN_GetStringIdentifiers(const NPUTF8 **names, int32_t nameCount, NPIdentifier *identifiers);

   221 IMPORT_C NPIdentifier NPN_GetIntIdentifier(int32_t intid);

   222 IMPORT_C bool NPN_IdentifierIsString(NPIdentifier identifier);

   223 

   224 /*

   225     The NPUTF8 returned from NPN_UTF8FromIdentifier SHOULD be freed.

   226 */

   227 IMPORT_C NPUTF8 *NPN_UTF8FromIdentifier(NPIdentifier identifier);

   228 

   229 /*

   230     Get the integer represented by identifier. If identifier is not an

   231     integer identifier, the behaviour is undefined.

   232 */

   233 IMPORT_C int32_t NPN_IntFromIdentifier(NPIdentifier identifier);

   234 

   235 /*

   236     NPObject behavior is implemented using the following set of

   237     callback functions.

   238 

   239     The NPVariant *result argument of these functions (where

   240     applicable) should be released using NPN_ReleaseVariantValue().

   241 */

   242 typedef NPObject *(*NPAllocateFunctionPtr)(NPP npp, NPClass *aClass);

   243 typedef void (*NPDeallocateFunctionPtr)(NPObject *obj);

   244 typedef void (*NPInvalidateFunctionPtr)(NPObject *obj);

   245 typedef bool (*NPHasMethodFunctionPtr)(NPObject *obj, NPIdentifier name);

   246 typedef bool (*NPInvokeFunctionPtr)(NPObject *obj, NPIdentifier name, const NPVariant *args, uint32_t argCount, NPVariant *result);

   247 typedef bool (*NPInvokeDefaultFunctionPtr)(NPObject *npobj, const NPVariant *args, uint32_t argCount, NPVariant *result);

   248 typedef bool (*NPHasPropertyFunctionPtr)(NPObject *obj, NPIdentifier name);

   249 typedef bool (*NPGetPropertyFunctionPtr)(NPObject *obj, NPIdentifier name, NPVariant *result);

   250 typedef bool (*NPSetPropertyFunctionPtr)(NPObject *obj, NPIdentifier name, const NPVariant *value);

   251 typedef bool (*NPRemovePropertyFunctionPtr)(NPObject *npobj, NPIdentifier name);

   252 typedef bool (*NPEnumerationFunctionPtr)(NPObject *npobj, NPIdentifier **value, uint32_t *count);

   253 

   254 /*

   255     NPObjects returned by create have a reference count of one.  It is the caller's responsibility

   256     to release the returned object.

   257 

   258     NPInvokeFunctionPtr function may return false to indicate a the method could not be invoked.

   259     

   260     NPGetPropertyFunctionPtr and NPSetPropertyFunctionPtr may return false to indicate a property doesn't

   261     exist.

   262     

   263     NPInvalidateFunctionPtr is called by the scripting environment when the native code is

   264     shutdown.  Any attempt to message a NPObject instance after the invalidate

   265     callback has been called will result in undefined behavior, even if the

   266     native code is still retaining those NPObject instances.

   267     (The runtime will typically return immediately, with 0 or NULL, from an attempt to

   268     dispatch to a NPObject, but this behavior should not be depended upon.)

   269     

   270     The NPEnumerationFunctionPtr function may pass an array of                  

   271     NPIdentifiers back to the caller. The callee allocs the memory of           

   272     the array using NPN_MemAlloc(), and it's the caller's responsibility        

   273     to release it using NPN_MemFree().           

   274 */

   275 struct NPClass

   276 {

   277     uint32_t structVersion;

   278     NPAllocateFunctionPtr allocate;

   279     NPDeallocateFunctionPtr deallocate;

   280     NPInvalidateFunctionPtr invalidate;

   281     NPHasMethodFunctionPtr hasMethod;

   282     NPInvokeFunctionPtr invoke;

   283     NPInvokeDefaultFunctionPtr invokeDefault;

   284     NPHasPropertyFunctionPtr hasProperty;

   285     NPGetPropertyFunctionPtr getProperty;

   286     NPSetPropertyFunctionPtr setProperty;

   287     NPRemovePropertyFunctionPtr removeProperty;

   288     NPEnumerationFunctionPtr enumerate;

   289 };

   290 

   291 #define NP_CLASS_STRUCT_VERSION      2

   292 #define NP_CLASS_STRUCT_VERSION_ENUM 2                           

   293 #define NP_CLASS_STRUCT_VERSION_HAS_ENUM(npclass)   \

   294     ((npclass)->structVersion >= NP_CLASS_STRUCT_VERSION_ENUM)

   295 

   296 struct NPObject {

   297     NPClass *_class;

   298     uint32_t referenceCount;

   299     // Additional space may be allocated here by types of NPObjects

   300 };

   301 

   302 /*

   303     If the class has an allocate function, NPN_CreateObject invokes that function,

   304     otherwise a NPObject is allocated and returned.  If a class has an allocate

   305     function it is the responsibility of that implementation to set the initial retain

   306     count to 1.

   307 */

   308 IMPORT_C NPObject *NPN_CreateObject(NPP npp, NPClass *aClass);

   309 

   310 /*

   311     Increment the NPObject's reference count.

   312 */

   313 IMPORT_C NPObject *NPN_RetainObject (NPObject *obj);

   314 

   315 /*

   316     Decremented the NPObject's reference count.  If the reference

   317     count goes to zero, the class's destroy function is invoke if

   318     specified, otherwise the object is freed directly.

   319 */

   320 IMPORT_C void NPN_ReleaseObject (NPObject *obj);

   321 

   322 /*

   323     Functions to access script objects represented by NPObject.

   324 

   325     Calls to script objects are synchronous.  If a function returns a

   326     value, it will be supplied via the result NPVariant

   327     argument. Successful calls will return true, false will be

   328     returned in case of an error.

   329     

   330     Calls made from plugin code to script must be made from the thread

   331     on which the plugin was initialized.

   332 */

   333 IMPORT_C bool NPN_Invoke(NPP npp, NPObject *npobj, NPIdentifier methodName, const NPVariant *args, uint32_t argCount, NPVariant *result);

   334 IMPORT_C bool NPN_InvokeDefault(NPP npp, NPObject *npobj, const NPVariant *args, uint32_t argCount, NPVariant *result);

   335 IMPORT_C bool NPN_Evaluate(NPP npp, NPObject *npobj, NPString *script, NPVariant *result);

   336 IMPORT_C bool NPN_GetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName, NPVariant *result);

   337 IMPORT_C bool NPN_SetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName, const NPVariant *value);

   338 IMPORT_C bool NPN_RemoveProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName);

   339 IMPORT_C bool NPN_HasProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName);

   340 IMPORT_C bool NPN_HasMethod(NPP npp, NPObject *npobj, NPIdentifier methodName);

   341 IMPORT_C bool NPN_Enumerate(NPP npp, NPObject *npobj, NPIdentifier **identifier, uint32_t *count);

   342 IMPORT_C bool NPN_SetException(NPObject *obj, const NPUTF8 *message);

   343 

   344 #ifdef __cplusplus

   345 }

   346 #endif

   347 

   348 #endif