WebCore:
[WebKit-https.git] / WebKit / Plugins.subproj / npruntime.h
1 /*
2  * Copyright (C) 2004 Apple Computer, Inc.  All rights reserved.
3  *
4  * Revision 1 (March 4, 2004):
5  * Initial proposal.
6  *
7  * Revision 2 (March 10, 2004):
8  * All calls into script were made asynchronous.  Results are
9  * provided via the NPScriptResultFunctionPtr callback.
10  *
11  * Revision 3 (March 10, 2004):
12  * Corrected comments to not refer to class retain/release FunctionPtrs.
13  *
14  * Revision 4 (March 11, 2004):
15  * Added additional convenience NPN_SetExceptionWithUTF8().
16  * Changed NPHasPropertyFunctionPtr and NPHasMethodFunctionPtr to take NPClass
17  * pointers instead of NPObject pointers.
18  * Added NPIsValidIdentifier().
19  *
20  * Revision 5 (March 17, 2004):
21  * Added context parameter to result callbacks from ScriptObject functions.
22  *
23  * Revision 6 (March 29, 2004):
24  * Renamed functions implemented by user agent to NPN_*.  Removed _ from
25  * type names.
26  * Renamed "JavaScript" types to "Script".
27  *
28  * Revision 7 (April 21, 2004):
29  * NPIdentifier becomes a void*, was int32_t
30  * Remove NP_IsValidIdentifier, renamed NP_IdentifierFromUTF8 to NP_GetIdentifier
31  * Added NPVariant and modified functions to use this new type.
32  */
33 #ifndef _NP_RUNTIME_H_
34 #define _NP_RUNTIME_H_
35
36 #ifdef __cplusplus
37 extern "C" {
38 #endif
39
40 /*
41     This API is used to facilitate binding code written in C to script
42     objects.  The API in this header does not assume the presence of a
43     user agent.  That is, it can be used to bind C code to scripting environments
44     outside of the context of a user agent.  
45     
46     However, the normal use of the this API is in the context of a scripting
47     environment running in a browser or other user agent.  In particular it is used
48     to support the extended Netscape script-ability API for plugins (NP-SAP).
49     NP-SAP is an extension of the Netscape plugin API.  As such we have adopted the
50     use of the "NP" prefix for this API.  
51 */
52
53
54 /*
55     Data passed between 'C' and script is always wrapped in an NPObject.
56     The 'interface' of an NPObject is described by an NPClass.
57 */
58 typedef struct NPObject NPObject;
59 typedef struct NPClass NPClass;
60
61 typedef char NPUTF8;
62 typedef struct _NPString {
63     const NPUTF8 *UTF8Characters;
64     uint32_t UTF8Length;
65 } NPString;
66
67 #ifndef _NPAPI_H_
68 // Ack!  Temporary hack to get build working.
69 typedef unsigned char NPBool;
70 #endif
71   
72 typedef enum {
73     NPVariantVoidType,
74     NPVariantNullType,
75     NPVariantUndefinedType,
76     NPVariantBoolType,
77     NPVariantInt32Type,
78     NPVariantDoubleType,
79     NPVariantStringType,
80     NPVariantObjectType
81 } NPVariantType;
82
83 typedef struct _NPVariant {
84     NPVariantType type;
85     union {
86         NPBool boolValue;
87         int32_t intValue;
88         double doubleValue;
89         NPString stringValue;
90         NPObject *objectValue;
91     } value;
92 } NPVariant;
93
94 /*
95     NPN_ReleaseVariantValue is called on all 'out' parameters references.
96     Specifically it is called on variants that are resultant out parameters
97     in NPGetPropertyFunctionPtr and NPInvokeFunctionPtr.  Resultant variants
98     from these two functions should be initialized using the
99     NPN_InitializeVariantXXX() functions.
100     
101     After calling NPReleaseVariantValue, the type of the variant will
102     be set to NPVariantUndefinedType.
103 */
104 void NPN_ReleaseVariantValue (NPVariant *variant);
105
106 NPBool NPN_VariantIsVoid (const NPVariant *variant);
107 NPBool NPN_VariantIsNull (const NPVariant *variant);
108 NPBool NPN_VariantIsUndefined (const NPVariant *variant);
109 NPBool NPN_VariantIsBool (const NPVariant *variant);
110 NPBool NPN_VariantIsInt32 (const NPVariant *variant);
111 NPBool NPN_VariantIsDouble (const NPVariant *variant);
112 NPBool NPN_VariantIsString (const NPVariant *variant);
113 NPBool NPN_VariantIsObject (const NPVariant *variant);
114 NPBool NPN_VariantToBool (const NPVariant *variant, NPBool *result);
115 NPBool NPN_VariantToInt32 (const NPVariant *variant, int32_t *result);
116 NPBool NPN_VariantToDouble (const NPVariant *variant, double *result);
117 NPString NPN_VariantToString (const NPVariant *variant);
118 NPString NPN_VariantToStringCopy (const NPVariant *variant);
119 NPBool NPN_VariantToObject (const NPVariant *variant, NPObject **result);
120
121 /*
122     NPVariants initialized with the NPN_InitializeVariantXXX() functions
123     must be released using the NPN_ReleaseVariantValue() function.
124 */
125 void NPN_InitializeVariantAsVoid (NPVariant *variant);
126 void NPN_InitializeVariantAsNull (NPVariant *variant);
127 void NPN_InitializeVariantAsUndefined (NPVariant *variant);
128 void NPN_InitializeVariantWithBool (NPVariant *variant, NPBool value);
129 void NPN_InitializeVariantWithInt32 (NPVariant *variant, int32_t value);
130 void NPN_InitializeVariantWithDouble (NPVariant *variant, double value);
131
132 /*
133     NPN_InitializeVariantWithString() does not copy string data.  However
134     the string data will be deallocated by calls to NPReleaseVariantValue().
135 */
136 void NPN_InitializeVariantWithString (NPVariant *variant, const NPString *value);
137
138 /*
139     NPN_InitializeVariantWithStringCopy() will copy string data.  The string data
140     will be deallocated by calls to NPReleaseVariantValue().
141 */
142 void NPN_InitializeVariantWithStringCopy (NPVariant *variant, const NPString *value);
143
144 /*
145     NPN_InitializeVariantWithObject() retains the NPObject.  The object will be released
146     by calls to NPReleaseVariantValue();
147 */
148 void NPN_InitializeVariantWithObject (NPVariant *variant, NPObject *value);
149
150 void NPN_InitializeVariantWithVariant (NPVariant *destination, const NPVariant *source);
151
152 /*
153         Type mappings (JavaScript types have been used for illustration
154     purposes):
155
156         script    to                C
157         Boolean                     NPVariant (with type NPVariantBoolType) 
158         Number                      NPVariant (with type NPVariantDoubleType)
159         String                      NPVariant (with type NPVariantStringType)
160         Undefined                   NPVariant (with type NPVariantUndefinedType)
161         Null                        NPVariant (with type NPVariantNullType)
162         Object (including Array)    NPVariant (with type NPVariantObjectType, objectValue will be a NPObject)
163         Object (NPObject wrapper)   NPVariant (with type NPVariantObjectType)
164
165
166         C          to                                         script
167         NPVariant (with type NPVariantBoolType)               Boolean   
168         NPVariant (with type NPVariantInt32Type)              Number
169         NPVariant (with type NPVariantDoubleType)             Number
170         NPVariant (with type NPVariantStringType)             String
171         NPVariant (with type NPVariantUndefinedType)          Undefined
172         NPVariant (with type NPVariantNullType)               Null
173         NPArray                                               Array (restricted)
174         NObject                                               Object or (NPObject wrapper)
175
176 */
177
178 typedef void *NPIdentifier;
179
180 /*
181     NPObjects have methods and properties.  Methods and properties are
182     identified with NPIdentifiers.  These identifiers may be reflected
183     in script.  NPIdentifiers can be either strings or integers, IOW,
184     methods and properties can be identified by either strings or
185     integers (i.e. foo["bar"] vs foo[1]). NPIdentifiers can be
186     compared using ==.  In case of any errors, the requested
187     NPIdentifier(s) will be NULL.
188 */
189 NPIdentifier NPN_GetStringIdentifier(const NPUTF8 *name);
190 void NPN_GetStringIdentifiers(const NPUTF8 **names, int32_t nameCount, NPIdentifier *identifiers);
191 NPIdentifier NPN_GetIntIdentifier(int32_t intid);
192 NPBool NPN_IdentifierIsString(NPIdentifier identifier);
193 NPUTF8 *NPN_UTF8FromIdentifier (NPIdentifier identifier);
194
195 /*
196     NPObject behavior is implemented using the following set of callback functions.
197     
198     The NPVariant *result parameter of NPInvokeFunctionPtr and NPGetPropertyFunctionPtr functions
199     should be initialized using one of the NPN_InitializeVariantXXX functions.  The variant result
200     of the two functions will be released using NPN_ReleaseVariantValue().
201 */
202 typedef NPObject *(*NPAllocateFunctionPtr)();
203 typedef void (*NPDeallocateFunctionPtr)(NPObject *obj);
204 typedef void (*NPInvalidateFunctionPtr)(NPObject *obj);
205 typedef NPBool (*NPHasMethodFunctionPtr)(NPClass *theClass, NPIdentifier name);
206 typedef NPBool (*NPInvokeFunctionPtr)(NPObject *obj, NPIdentifier name, const NPVariant *args, unsigned argCount, NPVariant *result);
207 typedef NPBool (*NPHasPropertyFunctionPtr)(NPClass *theClass, NPIdentifier name);
208 typedef NPBool (*NPGetPropertyFunctionPtr)(NPObject *obj, NPIdentifier name, NPVariant *result);
209 typedef NPBool (*NPSetPropertyFunctionPtr)(NPObject *obj, NPIdentifier name, const NPVariant *value);
210
211 /*
212     NPObjects returned by create have a reference count of one.  It is the caller's responsibility
213     to release the returned object.
214
215     NPInvokeFunctionPtr function may return false to indicate a the method could not be invoked.
216     
217     NPGetPropertyFunctionPtr and NPSetPropertyFunctionPtr may return false to indicate a property doesn't
218     exist.
219     
220     NPInvalidateFunctionPtr is called by the scripting environment when the native code is
221     shutdown.  Any attempt to message a NPObject instance after the invalidate
222     callback has been called will result in undefined behavior, even if the
223     native code is still retaining those NPObject instances.
224     (The runtime will typically return immediately, with 0 or NULL, from an attempt to
225     dispatch to a NPObject, but this behavior should not be depended upon.)
226 */
227 struct NPClass
228 {
229     uint32_t structVersion;
230     NPAllocateFunctionPtr allocate;
231     NPDeallocateFunctionPtr deallocate;
232     NPInvalidateFunctionPtr invalidate;
233     NPHasMethodFunctionPtr hasMethod;
234     NPInvokeFunctionPtr invoke;
235     NPHasPropertyFunctionPtr hasProperty;
236     NPGetPropertyFunctionPtr getProperty;
237     NPSetPropertyFunctionPtr setProperty;
238 };
239
240 #define kNPClassStructVersion1 1
241 #define kNPClassStructVersionCurrent kNPClassStructVersion1
242
243 struct NPObject {
244     NPClass *_class;
245     uint32_t referenceCount;
246     // Additional space may be allocated here by types of NPObjects
247 };
248
249 /*
250     If the class has an allocate function, NPN_CreateObject invokes that function,
251     otherwise a NPObject is allocated and returned.  If a class has an allocate
252     function it is the responsibility of that implementation to set the initial retain
253     count to 1.
254 */
255 NPObject *NPN_CreateObject (NPClass *aClass);
256
257 /*
258     Increment the NPObject's reference count.
259 */
260 NPObject *NPN_RetainObject (NPObject *obj);
261
262 /*
263     Decremented the NPObject's reference count.  If the reference
264     count goes to zero, the class's destroy function is invoke if
265     specified, otherwise the object is freed directly.
266 */
267 void NPN_ReleaseObject (NPObject *obj);
268
269 /*
270     Functions to access script objects represented by NPObject.
271     
272     Calls to script objects are asynchronous.  If a function returns a value, it
273     will be supplied via the NPScriptResultFunctionPtr callback.
274     
275     Calls made from plugin code to script may be made from any thread.
276     
277     Calls made from script to the plugin will always be made on the main
278     user agent thread, this include calls to NPScriptResultFunctionPtr callbacks.
279 */
280 NPBool NPN_Call (NPObject *obj, NPIdentifier methodName, const NPVariant *args, unsigned argCount, NPVariant *result);
281 NPBool NPN_Evaluate (NPObject *obj, NPString *script, NPVariant *result);
282 NPBool NPN_GetProperty (NPObject *obj, NPIdentifier  propertyName, NPVariant *result);
283 NPBool NPN_SetProperty (NPObject *obj, NPIdentifier  propertyName, const NPVariant *value);
284 NPBool NPN_RemoveProperty (NPObject *obj, NPIdentifier propertyName);
285
286 /*
287     NPN_SetException may be called to trigger a script exception upon return
288     from entry points into NPObjects.
289 */
290 void NPN_SetException (NPObject *obj, NPString *message);
291
292 #ifdef __cplusplus
293 }
294 #endif
295
296 #endif