Updated plugin binding API to reflect latest revision from
[WebKit-https.git] / JavaScriptCore / bindings / npruntime.h
1 /*
2  * Copyright (C) 2004 Apple Computer, Inc.  All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions
6  * are met:
7  * 1. Redistributions of source code must retain the above copyright
8  *    notice, this list of conditions and the following disclaimer.
9  * 2. Redistributions in binary form must reproduce the above copyright
10  *    notice, this list of conditions and the following disclaimer in the
11  *    documentation and/or other materials provided with the distribution.
12  *
13  * THIS SOFTWARE IS PROVIDED BY APPLE COMPUTER, INC. ``AS IS'' AND ANY
14  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
16  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE COMPUTER, INC. OR
17  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
18  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
19  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
20  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
21  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
22  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
23  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
24  *
25  * Revision 1 (March 4, 2004):
26  * Initial proposal.
27  *
28  * Revision 2 (March 10, 2004):
29  * All calls into script were made asynchronous.  Results are
30  * provided via the NPScriptResultFunctionPtr callback.
31  *
32  * Revision 3 (March 10, 2004):
33  * Corrected comments to not refer to class retain/release FunctionPtrs.
34  *
35  * Revision 4 (March 11, 2004):
36  * Added additional convenience NPN_SetExceptionWithUTF8().
37  * Changed NPHasPropertyFunctionPtr and NPHasMethodFunctionPtr to take NPClass
38  * pointers instead of NPObject pointers.
39  * Added NPIsValidIdentifier().
40  *
41  * Revision 5 (March 17, 2004):
42  * Added context parameter to result callbacks from ScriptObject functions.
43  *
44  * Revision 6 (March 29, 2004):
45  * Renamed functions implemented by user agent to NPN_*.  Removed _ from
46  * type names.
47  * Renamed "JavaScript" types to "Script".
48  *
49  * Revision 7 (April 21, 2004):
50  * NPIdentifier becomes a void*, was int32_t
51  * Remove NP_IsValidIdentifier, renamed NP_IdentifierFromUTF8 to NP_GetIdentifier
52  * Added NPVariant and modified functions to use this new type.
53  */
54 #ifndef _NP_RUNTIME_H_
55 #define _NP_RUNTIME_H_
56
57 #ifdef __cplusplus
58 extern "C" {
59 #endif
60
61 /*
62     This API is used to facilitate binding code written in C to script
63     objects.  The API in this header does not assume the presence of a
64     user agent.  That is, it can be used to bind C code to scripting environments
65     outside of the context of a user agent.  
66     
67     However, the normal use of the this API is in the context of a scripting
68     environment running in a browser or other user agent.  In particular it is used
69     to support the extended Netscape script-ability API for plugins (NP-SAP).
70     NP-SAP is an extension of the Netscape plugin API.  As such we have adopted the
71     use of the "NP" prefix for this API.  
72     
73     The following NP-SAP entry points were added to the Netscape plugin API (in npsap.h):
74
75     NPObject *NPP_GetNativeObjectForScript (NPP instance);
76     NPScriptObject *NPN_GetWindowScriptObject (NPP instance);
77     NPScriptObject *NPN_GetInstanceScriptObject (NPP instance);
78
79     These functions are used to establish the initial binding between the user agent
80     and native code.  The DOM objects in the user agent can be examined and manipulated using
81     the NPN_ functions that operate on a NPScriptObject described in this header.
82     
83     To the extent possible the assumptions about the scripting language used by
84     the scripting environment have been minimized.
85 */
86
87
88 /*
89     Data passed between 'C' and script is always wrapped in an NPObject.
90     The 'interface' of an NPObject is described by an NPClass.
91 */
92 typedef struct NPObject NPObject;
93 typedef struct NPClass NPClass;
94
95 /*
96     A NPScriptObject wraps a script Object in an NPObject.
97 */
98 typedef NPObject NPScriptObject;
99
100 typedef char NPUTF8;
101 typedef struct _NPString {
102     const NPUTF8 *UTF8Characters;
103     uint32_t UTF8Length;
104 } NPString;
105
106 typedef unsigned char NPBool;
107   
108 typedef enum {
109     NPVariantVoidType,
110     NPVariantNullType,
111     NPVariantUndefinedType,
112     NPVariantBoolType,
113     NPVariantInt32Type,
114     NPVariantDoubleType,
115     NPVariantStringType,
116     NPVariantObjectType
117 } NPVariantType;
118
119 typedef struct _NPVariant {
120     NPVariantType type;
121     union {
122         NPBool boolValue;
123         int32_t intValue;
124         double doubleValue;
125         NPString stringValue;
126         NPObject *objectValue;
127     } value;
128 } NPVariant;
129
130 /*
131     NPN_ReleaseVariantValue is called on all 'out' parameters references.
132     Specifically it is called on variants that are resultant out parameters
133     in NPGetPropertyFunctionPtr and NPInvokeFunctionPtr.  Resultant variants
134     from these two functions should be initialized using the
135     NPN_InitializeVariantXXX() functions.
136     
137     After calling NPReleaseVariantValue, the type of the variant will
138     be set to NPVariantUndefinedType.
139 */
140 void NPN_ReleaseVariantValue (NPVariant *variant);
141
142 NPBool NPN_VariantIsVoid (const NPVariant *variant);
143 NPBool NPN_VariantIsNull (const NPVariant *variant);
144 NPBool NPN_VariantIsUndefined (const NPVariant *variant);
145 NPBool NPN_VariantIsBool (const NPVariant *variant);
146 NPBool NPN_VariantIsInt32 (const NPVariant *variant);
147 NPBool NPN_VariantIsDouble (const NPVariant *variant);
148 NPBool NPN_VariantIsString (const NPVariant *variant);
149 NPBool NPN_VariantIsObject (const NPVariant *variant);
150 NPBool NPN_VariantToBool (const NPVariant *variant, NPBool *result);
151 NPBool NPN_VariantToInt32 (const NPVariant *variant, int32_t *result);
152 NPBool NPN_VariantToDouble (const NPVariant *variant, double *result);
153 NPString NPN_VariantToString (const NPVariant *variant);
154 NPString NPN_VariantToStringCopy (const NPVariant *variant);
155 NPBool NPN_VariantToObject (const NPVariant *variant, NPObject **result);
156
157 /*
158     NPVariants initialized with the NPN_InitializeVariantXXX() functions
159     must be released using the NPN_ReleaseVariantValue() function.
160 */
161 void NPN_InitializeVariantAsVoid (NPVariant *variant);
162 void NPN_InitializeVariantAsNull (NPVariant *variant);
163 void NPN_InitializeVariantAsUndefined (NPVariant *variant);
164 void NPN_InitializeVariantWithBool (NPVariant *variant, NPBool value);
165 void NPN_InitializeVariantWithInt32 (NPVariant *variant, int32_t value);
166 void NPN_InitializeVariantWithDouble (NPVariant *variant, double value);
167
168 /*
169     NPN_InitializeVariantWithString() does not copy string data.  However
170     the string data will be deallocated by calls to NPReleaseVariantValue().
171 */
172 void NPN_InitializeVariantWithString (NPVariant *variant, const NPString *value);
173
174 /*
175     NPN_InitializeVariantWithStringCopy() will copy string data.  The string data
176     will be deallocated by calls to NPReleaseVariantValue().
177 */
178 void NPN_InitializeVariantWithStringCopy (NPVariant *variant, const NPString *value);
179
180 /*
181     NPN_InitializeVariantWithObject() retains the NPObject.  The object will be released
182     by calls to NPReleaseVariantValue();
183 */
184 void NPN_InitializeVariantWithObject (NPVariant *variant, NPObject *value);
185
186 void NPN_InitializeVariantWithVariant (NPVariant *destination, const NPVariant *source);
187
188 /*
189         Type mappings (JavaScript types have been used for illustration
190     purposes):
191
192         script    to                C
193         Boolean                     NPVariant (with type NPVariantBoolType) 
194         Number                      NPVariant (with type NPVariantDoubleType)
195         String                      NPVariant (with type NPVariantStringType)
196         Undefined                   NPVariant (with type NPVariantUndefinedType)
197         Null                        NPVariant (with type NPVariantNullType)
198         Object (including Array)    NPVariant (with type NPVariantObjectType, objectValue will be a NPScriptObject)
199         Object (NPObject wrapper)   NPVariant (with type NPVariantObjectType)
200
201
202         C          to                                         script
203         NPVariant (with type NPVariantBoolType)               Boolean   
204         NPVariant (with type NPVariantInt32Type)              Number
205         NPVariant (with type NPVariantDoubleType)             Number
206         NPVariant (with type NPVariantStringType)             String
207         NPVariant (with type NPVariantUndefinedType)          Undefined
208         NPVariant (with type NPVariantNullType)               Null
209         NPArray                                               Array (restricted)
210         NPScriptObject                                        Object
211         other NPObject                                        Object (NPObject wrapper)
212
213 */
214
215 typedef void *NPIdentifier;
216
217 /*
218     NPObjects have methods and properties.  Methods and properties are named with NPIdentifiers.
219     These identifiers may be reflected in script.  NPIdentifiers can be compared using ==.
220     
221     NPN_IsValidIdentifier will return true if an identifier for the name has already been
222     assigned with either NPIdentifierFromUTF8() or NPN_GetIdentifiers();
223 */
224 NPIdentifier NPN_GetIdentifier (const NPUTF8 *name);
225 void NPN_GetIdentifiers (const NPUTF8 **names, int nameCount, NPIdentifier *identifiers);
226
227 /*
228     The NPUTF8 returned from NPN_UTF8FromIdentifier should NOT be freed.
229 */
230 const NPUTF8 *NPN_UTF8FromIdentifier (NPIdentifier identifier);
231
232 /*
233     NPObject behavior is implemented using the following set of callback functions.
234     
235     The NPVariant *result parameter of NPInvokeFunctionPtr and NPGetPropertyFunctionPtr functions
236     should be initialized using one of the NPN_InitializeVariantXXX functions.  The variant result
237     of the two functions will be released using NPN_ReleaseVariantValue().
238 */
239 typedef NPObject *(*NPAllocateFunctionPtr)();
240 typedef void (*NPDeallocateFunctionPtr)(NPObject *obj);
241 typedef void (*NPInvalidateFunctionPtr)(NPObject *obj);
242 typedef bool (*NPHasMethodFunctionPtr)(NPClass *theClass, NPIdentifier name);
243 typedef void (*NPInvokeFunctionPtr)(NPObject *obj, NPIdentifier name, NPVariant *args, unsigned argCount, NPVariant *result);
244 typedef bool (*NPHasPropertyFunctionPtr)(NPClass *theClass, NPIdentifier name);
245 typedef void (*NPGetPropertyFunctionPtr)(NPObject *obj, NPIdentifier name, NPVariant *result);
246 typedef void (*NPSetPropertyFunctionPtr)(NPObject *obj, NPIdentifier name, const NPVariant *value);
247
248 /*
249     NPObjects returned by create, retain, invoke, and getProperty 
250     pass a reference count to the caller.  That is, the callee adds a reference
251     count which passes to the caller.  It is the caller's responsibility
252     to release the returned object.
253
254     NPInvokeFunctionPtr function may return 0 to indicate a void result.
255     
256     NPInvalidateFunctionPtr is called by the scripting environment when the native code is
257     shutdown.  Any attempt to message a NPScriptObject instance after the invalidate
258     callback has been called will result in undefined behavior, even if the
259     native code is still retaining those NPScriptObject instances.
260     (The runtime will typically return immediately, with 0 or NULL, from an attempt to
261     dispatch to a NPScriptObject, but this behavior should not be depended upon.)
262 */
263 struct NPClass
264 {
265     uint32_t structVersion;
266     NPAllocateFunctionPtr allocate;
267     NPDeallocateFunctionPtr deallocate;
268     NPInvalidateFunctionPtr invalidate;
269     NPHasMethodFunctionPtr hasMethod;
270     NPInvokeFunctionPtr invoke;
271     NPHasPropertyFunctionPtr hasProperty;
272     NPGetPropertyFunctionPtr getProperty;
273     NPSetPropertyFunctionPtr setProperty;
274 };
275
276 #define kNPClassStructVersion1 1
277 #define kNPClassStructVersionCurrent kNPClassStructVersion1
278
279 struct NPObject {
280     NPClass *_class;
281     uint32_t referenceCount;
282     // Additional space may be allocated here by types of NPObjects
283 };
284
285 /*
286     If the class has an allocate function, NPN_CreateObject invokes that function,
287     otherwise a NPObject is allocated and returned.  If a class has an allocate
288     function it is the responsibility of that implementation to set the initial retain
289     count to 1.
290 */
291 NPObject *NPN_CreateObject (NPClass *aClass);
292
293 /*
294     Increment the NPObject's reference count.
295 */
296 NPObject *NPN_RetainObject (NPObject *obj);
297
298 /*
299     Decremented the NPObject's reference count.  If the reference
300     count goes to zero, the class's destroy function is invoke if
301     specified, otherwise the object is freed directly.
302 */
303 void NPN_ReleaseObject (NPObject *obj);
304
305 /*
306     Built-in data types.  These classes can be passed to NPN_IsKindOfClass().
307 */
308 extern NPClass *NPArrayClass;
309 extern NPClass *NPScriptObjectClass;
310
311 typedef NPObject NPArray;
312
313 /*
314     Functions to access script objects represented by NPScriptObject.
315     
316     Calls to script objects are asynchronous.  If a function returns a value, it
317     will be supplied via the NPScriptResultFunctionPtr callback.
318     
319     Calls made from plugin code to script may be made from any thread.
320     
321     Calls made from script to the plugin will always be made on the main
322     user agent thread, this include calls to NPScriptResultFunctionPtr callbacks.
323 */
324 typedef void (*NPScriptResultFunctionPtr)(const NPVariant *result, void *resultContext);
325
326 void NPN_Call (NPScriptObject *obj, NPIdentifier methodName, const NPVariant *args, unsigned argCount, NPScriptResultFunctionPtr resultCallback);
327 void NPN_Evaluate (NPScriptObject *obj, NPString *script, NPScriptResultFunctionPtr resultCallback, void *resultContext);
328 void NPN_GetProperty (NPScriptObject *obj, NPIdentifier  propertyName, NPScriptResultFunctionPtr resultCallback, void *resultContext);
329 void NPN_SetProperty (NPScriptObject *obj, NPIdentifier  propertyName, const NPVariant *value);
330 void NPN_RemoveProperty (NPScriptObject *obj, NPIdentifier propertyName);
331 void NPN_ToString (NPScriptObject *obj, NPScriptResultFunctionPtr result, void *resultContext);
332 void NPN_GetPropertyAtIndex (NPScriptObject *obj, int32_t index, NPScriptResultFunctionPtr resultCallback, void *resultContext);
333 void NPN_SetPropertyAtIndex (NPScriptObject *obj, unsigned index, const NPVariant *value);
334
335 /*
336     NPArrays are immutable.  They are used to pass arguments to 
337     the script functions that expect arrays, or to export 
338     arrays of properties.  NPArray is represented in JavaScript
339     by a restricted Array.  The Array in JavaScript is read-only,
340     only has index accessors, and may not be resized.
341     
342     Objects added to arrays are retained by the array.
343 */
344 NPArray *NPN_CreateArray (NPVariant **, int32_t count);
345 NPArray *NPN_CreateArrayV (int32_t count, ...);
346
347 /*
348     Objects returned by NPN_ObjectAtIndex pass a reference count
349     to the caller.  The caller must release the object.
350 */
351 NPObject *NPN_ObjectAtIndex (NPArray *array, int32_t index);
352
353 /*
354     Returns true if the object is a kind of class as specified by
355     aClass.
356 */
357 bool NPN_IsKindOfClass (const NPObject *obj, const NPClass *aClass);
358
359 /*
360     NPN_SetException may be called to trigger a script exception upon return
361     from entry points into NPObjects.  A reference count of the message passes
362     to the callee.  Typical usage:
363
364     NPString *message = NPN_CreateStringWithUTF8("invalid type", -1);
365     NPN_SetException (obj, mesage);
366     NPN_ReleaseObject (message);
367     
368     NPN_SetExceptionWithUTF8() take an UTF8 string and a length.  -1 may be passed for
369     the length if the string is null terminated.
370 */
371 void NPN_SetExceptionWithUTF8 (NPObject *obj, const NPUTF8 *message, int32_t length);
372 void NPN_SetException (NPObject *obj, NPString *message);
373
374 /*
375     Example usage:
376     
377     typedef NPObject MyObject;
378
379     typedef struct
380     {
381         NPObject object;
382         // Properties needed by MyObject are added here.
383         int numChapters;
384         ...
385     } MyObject
386
387     void stop(MyObject *obj)
388     {
389         ...
390     }
391
392     void start(MyObject *obj)
393     {
394         ...
395     }
396
397     void setChapter(MyObject *obj, int chapter)
398     {
399         ...
400     }
401
402     int getChapter(MyObject *obj)
403     {
404         ...
405     }
406
407     static NPIdentifier stopIdentifier;
408     static NPIdentifier startIdentifier;
409     static NPIdentifier setChapterIdentifier;
410     static NPIdentifier getChapterIdentifier;
411     static NPIdentifier numChaptersIdentifier;
412
413     static void initializeIdentifiers()
414     {
415         stopIdentifier = NPIdentifierFromUTF8 ("stop");
416         startIdentifier = NPIdentifierFromUTF8 ("start");
417         setChapterIdentifier = NPIdentifierFromUTF8 ("setChapter");
418         getChapterIdentifier = NPIdentifierFromUTF8 ("getChapter");
419         numChaptersIdentifier = NPIdentifierFromUTF8 ("numChapters");
420     }
421
422     bool myProperty (MyObject *obj, NPIdentifier name)
423     {
424         if (name == numChaptersIdentifier){
425             return true;
426         }
427         return false;
428     }
429
430     bool myHasMethod (MyObject *obj, NPIdentifier name)
431     {
432         if (name == stopIdentifier ||
433             name == startIdentifier ||
434             name == setChapterIdentifier ||
435             name == getChapterIdentifier) {
436             return true;
437         }
438         return false;
439     }
440
441     NPObject *myGetProperty (MyObject *obj, NPIdentifier name)
442     {
443         if (name == numChaptersIdentifier){
444             return NPN_CreateNumberWithInt(obj->numChapters); 
445         }
446         return 0;
447     }
448
449     void mySetProperty (MyObject *obj, NPIdentifier name, NPObject *value)
450     {
451         if (name == numChaptersIdentifier){
452             obj->numChapters = NPN_IntFromNumber(obj)
453         }
454     }
455
456     NPObject *myInvoke (MyObject *obj, NPIdentifier name, NPObject **args, unsigned argCount)
457     {
458
459         if (name == stopIdentifier){
460             stop(obj);
461         }
462         else if (name == startIdentifier){
463             start(obj);
464         }
465         else if (name == setChapterIdentifier){
466             if (NPN_IsKindOfClass (args[0], NPNumberClass)) {
467                 setChapter (obj, NPN_IntFromNumber(args[0]));
468             }
469             else {
470                 NPN_SetException (obj, NPN_CreateStringWithUTF8 ("invalid type"));
471             }
472         }
473         else if (name == getChapterIdentifier){
474             return NPN_CreateNumberWithInt (getChapter (obj));
475         }
476         return 0;
477     }
478
479     NPObject *myAllocate ()
480     {
481         MyFunctionPtrObject *newInstance = (MyFunctionPtrObject *)malloc (sizeof(MyFunctionPtrObject));
482         
483         if (stopIdentifier == 0)
484             initializeIdentifiers();
485             
486         return (NPObject *)newInstance;
487     }
488
489     void myInvalidate ()
490     {
491         // Make sure we've released any remaining references to script
492         // objects.
493     }
494     
495     void myDeallocate (MyObject *obj) 
496     {
497         free ((void *)obj);
498     }
499     
500     static NPClass _myFunctionPtrs = { 
501         (NPAllocateFunctionPtr) myAllocate, 
502         (NPDeallocateFunctionPtr) myDeallocate, 
503         (NPInvalidateFunctionPtr) myInvalidate,
504         (NPHasMethodFunctionPtr) myHasMethod,
505         (NPInvokeFunctionPtr) myInvoke,
506         (NPHasPropertyFunctionPtr) myHasProperty,
507         (NPGetPropertyFunctionPtr) myGetProperty,
508         (NPSetPropertyFunctionPtr) mySetProperty,
509     };
510     static NPClass *myFunctionPtrs = &_myFunctionPtrs;
511
512     // myGetNativeObjectForScript would be set as the entry point for
513     // the plugin's NPP_GetNativeObjectForScript function.
514     // It is invoked by the plugin container, i.e. the browser.
515     NPObject *myGetNativeObjectForScript(NPP instance)
516     {
517         NPObject *myObject = NPN_CreateObject (myFunctionPtrs);
518         return myObject;
519     }
520
521 */
522
523
524 #ifdef __cplusplus
525 }
526 #endif
527
528 #endif