461f3f0a2e0c08899251e2d796fcaeb4d8ffeb6b
[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 <<<<<<< npruntime.h
175         NPObject                                               Object or (NPObject wrapper)
176 =======
177         NObject                                               Object or (NPObject wrapper)
178 >>>>>>> 1.18
179
180 */
181
182 typedef void *NPIdentifier;
183
184 /*
185     NPObjects have methods and properties.  Methods and properties are
186     identified with NPIdentifiers.  These identifiers may be reflected
187     in script.  NPIdentifiers can be either strings or integers, IOW,
188     methods and properties can be identified by either strings or
189     integers (i.e. foo["bar"] vs foo[1]). NPIdentifiers can be
190     compared using ==.  In case of any errors, the requested
191     NPIdentifier(s) will be NULL.
192 */
193 NPIdentifier NPN_GetStringIdentifier(const NPUTF8 *name);
194 void NPN_GetStringIdentifiers(const NPUTF8 **names, int32_t nameCount, NPIdentifier *identifiers);
195 NPIdentifier NPN_GetIntIdentifier(int32_t intid);
196 NPBool NPN_IdentifierIsString(NPIdentifier identifier);
197 NPUTF8 *NPN_UTF8FromIdentifier (NPIdentifier identifier);
198
199 /*
200     NPObject behavior is implemented using the following set of callback functions.
201     
202     The NPVariant *result parameter of NPInvokeFunctionPtr and NPGetPropertyFunctionPtr functions
203     should be initialized using one of the NPN_InitializeVariantXXX functions.  The variant result
204     of the two functions will be released using NPN_ReleaseVariantValue().
205 */
206 typedef NPObject *(*NPAllocateFunctionPtr)();
207 typedef void (*NPDeallocateFunctionPtr)(NPObject *obj);
208 typedef void (*NPInvalidateFunctionPtr)(NPObject *obj);
209 typedef NPBool (*NPHasMethodFunctionPtr)(NPClass *theClass, NPIdentifier name);
210 typedef NPBool (*NPInvokeFunctionPtr)(NPObject *obj, NPIdentifier name, const NPVariant *args, unsigned argCount, NPVariant *result);
211 typedef NPBool (*NPHasPropertyFunctionPtr)(NPClass *theClass, NPIdentifier name);
212 typedef NPBool (*NPGetPropertyFunctionPtr)(NPObject *obj, NPIdentifier name, NPVariant *result);
213 typedef NPBool (*NPSetPropertyFunctionPtr)(NPObject *obj, NPIdentifier name, const NPVariant *value);
214
215 /*
216     NPObjects returned by create have a reference count of one.  It is the caller's responsibility
217     to release the returned object.
218
219     NPInvokeFunctionPtr function may return false to indicate a the method could not be invoked.
220     
221     NPGetPropertyFunctionPtr and NPSetPropertyFunctionPtr may return false to indicate a property doesn't
222     exist.
223     
224     NPInvalidateFunctionPtr is called by the scripting environment when the native code is
225     shutdown.  Any attempt to message a NPObject instance after the invalidate
226     callback has been called will result in undefined behavior, even if the
227     native code is still retaining those NPObject instances.
228     (The runtime will typically return immediately, with 0 or NULL, from an attempt to
229     dispatch to a NPObject, but this behavior should not be depended upon.)
230 */
231 struct NPClass
232 {
233     uint32_t structVersion;
234     NPAllocateFunctionPtr allocate;
235     NPDeallocateFunctionPtr deallocate;
236     NPInvalidateFunctionPtr invalidate;
237     NPHasMethodFunctionPtr hasMethod;
238     NPInvokeFunctionPtr invoke;
239     NPHasPropertyFunctionPtr hasProperty;
240     NPGetPropertyFunctionPtr getProperty;
241     NPSetPropertyFunctionPtr setProperty;
242 };
243
244 #define kNPClassStructVersion1 1
245 #define kNPClassStructVersionCurrent kNPClassStructVersion1
246
247 struct NPObject {
248     NPClass *_class;
249     uint32_t referenceCount;
250     // Additional space may be allocated here by types of NPObjects
251 };
252
253 /*
254     If the class has an allocate function, NPN_CreateObject invokes that function,
255     otherwise a NPObject is allocated and returned.  If a class has an allocate
256     function it is the responsibility of that implementation to set the initial retain
257     count to 1.
258 */
259 NPObject *NPN_CreateObject (NPClass *aClass);
260
261 /*
262     Increment the NPObject's reference count.
263 */
264 NPObject *NPN_RetainObject (NPObject *obj);
265
266 /*
267     Decremented the NPObject's reference count.  If the reference
268     count goes to zero, the class's destroy function is invoke if
269     specified, otherwise the object is freed directly.
270 */
271 void NPN_ReleaseObject (NPObject *obj);
272
273 /*
274     Functions to access script objects represented by NPObject.
275     
276     Calls to script objects are asynchronous.  If a function returns a value, it
277     will be supplied via the NPScriptResultFunctionPtr callback.
278     
279     Calls made from plugin code to script may be made from any thread.
280     
281     Calls made from script to the plugin will always be made on the main
282     user agent thread, this include calls to NPScriptResultFunctionPtr callbacks.
283 */
284 NPBool NPN_Call (NPObject *obj, NPIdentifier methodName, const NPVariant *args, unsigned argCount, NPVariant *result);
285 NPBool NPN_Evaluate (NPObject *obj, NPString *script, NPVariant *result);
286 NPBool NPN_GetProperty (NPObject *obj, NPIdentifier  propertyName, NPVariant *result);
287 NPBool NPN_SetProperty (NPObject *obj, NPIdentifier  propertyName, const NPVariant *value);
288 NPBool NPN_RemoveProperty (NPObject *obj, NPIdentifier propertyName);
289
290 /*
291     NPN_SetException may be called to trigger a script exception upon return
292     from entry points into NPObjects.
293 */
294 void NPN_SetException (NPObject *obj, NPString *message);
295
296 #ifdef __cplusplus
297 }
298 #endif
299
300 #endif