12e311b74908fee14a1106fd81e83dfe71abf486
[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  */
50 #ifndef _NP_RUNTIME_H_
51 #define _NP_RUNTIME_H_
52
53 #ifdef __cplusplus
54 extern "C" {
55 #endif
56
57 /*
58     This API is used to facilitate binding code written in C to script
59     objects.  The API in this header does not assume the presence of a
60     user agent.  That is, it can be used to bind C code to scripting environments
61     outside of the context of a user agent.  
62     
63     However, the normal use of the this API is in the context of a scripting
64     environment running in a browser or other user agent.  In particular it is used
65     to support the extended Netscape script-ability API for plugins (NP-SAP).
66     NP-SAP is an extension of the Netscape plugin API.  As such we have adopted the
67     use of the "NP" prefix for this API.  
68     
69     The following NP-SAP entry points were added to the Netscape plugin API (in npsap.h):
70
71     NPObject *NPP_GetNativeObjectForScript (NPP instance);
72     NPScriptObject *NPN_GetWindowScriptObject (NPP instance);
73     NPScriptObject *NPN_GetInstanceScriptObject (NPP instance);
74
75     These functions are used to establish the initial binding between the user agent
76     and native code.  The DOM objects in the user agent can be examined and manipulated using
77     the NPN_ functions that operate on a NPScriptObject described in this header.
78     
79     To the extent possible the assumptions about the scripting language used by
80     the scripting environment have been minimized.
81 */
82
83
84 /*
85     Data passed between 'C' and script is always wrapped in an NPObject.
86     The 'interface' of an NPObject is described by an NPClass.
87 */
88 typedef struct NPObject NPObject;
89 typedef struct NPClass NPClass;
90
91 /*
92     A NPScriptObject wraps a script Object in an NPObject.
93 */
94 typedef NPObject NPScriptObject;
95
96 /*
97         Type mappings (JavaScript types have been used for illustration
98     purposes):
99
100         script    to             C
101         Boolean                  NPBoolean      
102         Number                   NPNumber
103         String                   NPString
104         Undefined                NPUndefined
105         Null                     NPNull
106         Object (including Array) NPScriptObject
107         Object wrapper           NPObject
108
109
110         C          to            script
111         NPBoolean                Boolean        
112         NPNumber                 Number
113         NPString                 String
114         NPUndefined              Undefined
115         NPNull                   Null
116         NPArray                  Array (restricted)
117         NPScriptObject           Object
118         other NPObject           Object wrapper
119
120 */
121
122 typedef uint32_t NPIdentifier;
123
124 /*
125     NPUTF8 strings are null terminated.
126 */
127 typedef char NPUTF8;
128
129 /*
130     NPObjects have methods and properties.  Methods and properties are named with NPIdentifiers.
131     These identifiers may be reflected in script.  NPIdentifiers can be compared using ==.
132     
133     NPN_IsValidIdentifier will return true if an identifier for the name has already been
134     assigned with either NPIdentifierFromUTF8() or NPN_GetIdentifiers();
135 */
136 NPIdentifier NPN_IdentifierFromUTF8 (const NPUTF8 *name);
137 bool NPN_IsValidIdentifier (const NPUTF8 *name);
138 void NPN_GetIdentifiers (const NPUTF8 **names, int nameCount, NPIdentifier *identifiers);
139
140 /*
141     The NPUTF8 returned from NPN_UTF8FromIdentifier should NOT be freed.
142 */
143 const NPUTF8 *NPN_UTF8FromIdentifier (NPIdentifier identifier);
144
145 /*
146     NPObject behavior is implemented using the following set of callback functions.
147 */
148 typedef NPObject *(*NPAllocateFunctionPtr)();
149 typedef void (*NPDeallocateFunctionPtr)(NPObject *obj);
150 typedef void (*NPInvalidateFunctionPtr)();
151 typedef bool (*NPHasMethodFunctionPtr)(NPClass *theClass, NPIdentifier name);
152 typedef NPObject *(*NPInvokeFunctionPtr)(NPObject *obj, NPIdentifier name, NPObject **args, unsigned argCount);
153 typedef bool (*NPHasPropertyFunctionPtr)(NPClass *theClass, NPIdentifier name);
154 typedef NPObject *(*NPGetPropertyFunctionPtr)(NPObject *obj, NPIdentifier name);
155 typedef void (*NPSetPropertyFunctionPtr)(NPObject *obj, NPIdentifier name, NPObject *value);
156
157 /*
158     NPObjects returned by create, retain, invoke, and getProperty 
159     pass a reference count to the caller.  That is, the callee adds a reference
160     count which passes to the caller.  It is the caller's responsibility
161     to release the returned object.
162
163     NPInvokeFunctionPtr function may return 0 to indicate a void result.
164     
165     NPInvalidateFunctionPtr is called by the scripting environment when the native code is
166     shutdown.  Any attempt to message a NPScriptObject instance after the invalidate
167     callback has been called will result in undefined behavior, even if the
168     native code is still retaining those NPScriptObject instances.
169     (The runtime will typically return immediately, with 0 or NULL, from an attempt to
170     dispatch to a NPScriptObject, but this behavior should not be depended upon.)
171 */
172 struct NPClass
173 {
174     uint32_t structVersion;
175     NPAllocateFunctionPtr allocate;
176     NPDeallocateFunctionPtr deallocate;
177     NPInvalidateFunctionPtr invalidate;
178     NPHasMethodFunctionPtr hasMethod;
179     NPInvokeFunctionPtr invoke;
180     NPHasPropertyFunctionPtr hasProperty;
181     NPGetPropertyFunctionPtr getProperty;
182     NPSetPropertyFunctionPtr setProperty;
183 };
184
185 #define kNPClassStructVersion1 1
186 #define kNPClassStructVersionCurrent kNPClassStructVersion1
187
188 struct NPObject {
189     NPClass *_class;
190     uint32_t referenceCount;
191     // Additional space may be allocated here by types of NPObjects
192 };
193
194 /*
195     If the class has an allocate function, NPN_CreateObject invokes that function,
196     otherwise a NPObject is allocated and returned.  If a class has an allocate
197     function it is the responsibility of that implementation to set the initial retain
198     count to 1.
199 */
200 NPObject *NPN_CreateObject (NPClass *aClass);
201
202 /*
203     Increment the NPObject's reference count.
204 */
205 NPObject *NPN_RetainObject (NPObject *obj);
206
207 /*
208     Decremented the NPObject's reference count.  If the reference
209     count goes to zero, the class's destroy function is invoke if
210     specified, otherwise the object is freed directly.
211 */
212 void NPN_ReleaseObject (NPObject *obj);
213
214 /*
215     Built-in data types.  These classes can be passed to NPN_IsKindOfClass().
216 */
217 extern NPClass *NPBooleanClass;
218 extern NPClass *NPNullClass;
219 extern NPClass *NPUndefinedClass;
220 extern NPClass *NPArrayClass;
221 extern NPClass *NPNumberClass;
222 extern NPClass *NPStringClass;
223 extern NPClass *NPScriptObjectClass;
224
225 typedef NPObject NPBoolean;
226 typedef NPObject NPNull;
227 typedef NPObject NPUndefined;
228 typedef NPObject NPArray;
229 typedef NPObject NPNumber;
230 typedef NPObject NPString;
231
232 /*
233     Functions to access script objects represented by NPScriptObject.
234     
235     Calls to script objects are asynchronous.  If a function returns a value, it
236     will be supplied via the NPScriptResultFunctionPtr callback.
237     
238     Calls made from plugin code to script may be made from any thread.
239     
240     Calls made from script to the plugin will always be made on the main
241     user agent thread, this include calls to NPScriptResultFunctionPtr callbacks.
242 */
243 typedef void (*NPScriptResultFunctionPtr)(NPObject *obj, void *resultContext);
244
245 void NPN_Call (NPScriptObject *obj, NPIdentifier methodName, NPObject **args, unsigned argCount, NPScriptResultFunctionPtr resultCallback);
246 void NPN_Evaluate (NPScriptObject *obj, NPString *script, NPScriptResultFunctionPtr resultCallback, void *resultContext);
247 void NPN_GetProperty (NPScriptObject *obj, NPIdentifier  propertyName, NPScriptResultFunctionPtr resultCallback, void *resultContext);
248 void NPN_SetProperty (NPScriptObject *obj, NPIdentifier  propertyName, NPObject *value);
249 void NPN_RemoveProperty (NPScriptObject *obj, NPIdentifier propertyName);
250 void NPN_ToString (NPScriptObject *obj, NPScriptResultFunctionPtr result, void *resultContext);
251 void NPN_GetPropertyAtIndex (NPScriptObject *obj, int32_t index, NPScriptResultFunctionPtr resultCallback, void *resultContext);
252 void NPN_SetPropertyAtIndex (NPScriptObject *obj, unsigned index, NPObject *value);
253
254 /*
255     Functions for dealing with data types.
256 */
257 NPNumber *NPN_CreateNumberWithInt (int i);
258 NPNumber *NPN_CreateNumberWithFloat (float f);
259 NPNumber *NPN_CreateNumberWithDouble (double d);
260 int NPN_IntFromNumber (NPNumber *obj);
261 float NPN_FloatFromNumber (NPNumber *obj);
262 double NPN_DoubleFromNumber (NPNumber *obj);
263
264 /*
265     NPN_CreateStringWithUTF8() takes a UTF8 string and length.  -1 may be passed for the
266     length if the string is null terminated.
267 */
268 NPString *NPN_CreateStringWithUTF8 (const NPUTF8 *utf8String, int32_t length);
269
270 /*
271     Memory returned from NPUTF8FromString must be deallocated
272     by calling NPN_DeallocateUTF8.
273 */
274 NPUTF8 *NPN_UTF8FromString (NPString *obj);
275 void NPN_DeallocateUTF8 (NPUTF8 *UTF8Buffer);
276 int32_t NPN_StringLength (NPString *obj);
277
278 NPBoolean *NPN_CreateBoolean (bool f);
279 bool NPN_BoolFromBoolean (NPBoolean *aBool);
280
281 /*
282     NPNull returns a NPNull singleton.
283 */
284 NPNull *NPN_GetNull();
285
286 /*
287     NPUndefined returns a NPUndefined singleton.
288 */
289 NPUndefined *NPN_GetUndefined ();
290
291 /*
292     NPArrays are immutable.  They are used to pass arguments to 
293     the script functions that expect arrays, or to export 
294     arrays of properties.  NPArray is represented in JavaScript
295     by a restricted Array.  The Array in JavaScript is read-only,
296     only has index accessors, and may not be resized.
297     
298     Objects added to arrays are retained by the array.
299 */
300 NPArray *NPN_CreateArray (NPObject **, int32_t count);
301 NPArray *NPN_CreateArrayV (int32_t count, ...);
302
303 /*
304     Objects returned by NPN_ObjectAtIndex pass a reference count
305     to the caller.  The caller must release the object.
306 */
307 NPObject *NPN_ObjectAtIndex (NPArray *array, int32_t index);
308
309 /*
310     Returns true if the object is a kind of class as specified by
311     aClass.
312 */
313 bool NPN_IsKindOfClass (const NPObject *obj, const NPClass *aClass);
314
315 /*
316     NPN_SetException may be called to trigger a script exception upon return
317     from entry points into NPObjects.  A reference count of the message passes
318     to the callee.  Typical usage:
319
320     NPString *message = NPN_CreateStringWithUTF8("invalid type", -1);
321     NPN_SetException (obj, mesage);
322     NPN_ReleaseObject (message);
323     
324     NPN_SetExceptionWithUTF8() take an UTF8 string and a length.  -1 may be passed for
325     the length if the string is null terminated.
326 */
327 void NPN_SetExceptionWithUTF8 (NPObject *obj, const NPUTF8 *message, int32_t length);
328 void NPN_SetException (NPObject *obj, NPString *message);
329
330 /*
331     Example usage:
332     
333     typedef NPObject MyObject;
334
335     typedef struct
336     {
337         NPObject object;
338         // Properties needed by MyObject are added here.
339         int numChapters;
340         ...
341     } MyObject
342
343     void stop(MyObject *obj)
344     {
345         ...
346     }
347
348     void start(MyObject *obj)
349     {
350         ...
351     }
352
353     void setChapter(MyObject *obj, int chapter)
354     {
355         ...
356     }
357
358     int getChapter(MyObject *obj)
359     {
360         ...
361     }
362
363     static NPIdentifier stopIdentifier;
364     static NPIdentifier startIdentifier;
365     static NPIdentifier setChapterIdentifier;
366     static NPIdentifier getChapterIdentifier;
367     static NPIdentifier numChaptersIdentifier;
368
369     static void initializeIdentifiers()
370     {
371         stopIdentifier = NPIdentifierFromUTF8 ("stop");
372         startIdentifier = NPIdentifierFromUTF8 ("start");
373         setChapterIdentifier = NPIdentifierFromUTF8 ("setChapter");
374         getChapterIdentifier = NPIdentifierFromUTF8 ("getChapter");
375         numChaptersIdentifier = NPIdentifierFromUTF8 ("numChapters");
376     }
377
378     bool myProperty (MyObject *obj, NPIdentifier name)
379     {
380         if (name == numChaptersIdentifier){
381             return true;
382         }
383         return false;
384     }
385
386     bool myHasMethod (MyObject *obj, NPIdentifier name)
387     {
388         if (name == stopIdentifier ||
389             name == startIdentifier ||
390             name == setChapterIdentifier ||
391             name == getChapterIdentifier) {
392             return true;
393         }
394         return false;
395     }
396
397     NPObject *myGetProperty (MyObject *obj, NPIdentifier name)
398     {
399         if (name == numChaptersIdentifier){
400             return NPN_CreateNumberWithInt(obj->numChapters); 
401         }
402         return 0;
403     }
404
405     void mySetProperty (MyObject *obj, NPIdentifier name, NPObject *value)
406     {
407         if (name == numChaptersIdentifier){
408             obj->numChapters = NPN_IntFromNumber(obj)
409         }
410     }
411
412     NPObject *myInvoke (MyObject *obj, NPIdentifier name, NPObject **args, unsigned argCount)
413     {
414
415         if (name == stopIdentifier){
416             stop(obj);
417         }
418         else if (name == startIdentifier){
419             start(obj);
420         }
421         else if (name == setChapterIdentifier){
422             if (NPN_IsKindOfClass (args[0], NPNumberClass)) {
423                 setChapter (obj, NPN_IntFromNumber(args[0]));
424             }
425             else {
426                 NPN_SetException (obj, NPN_CreateStringWithUTF8 ("invalid type"));
427             }
428         }
429         else if (name == getChapterIdentifier){
430             return NPN_CreateNumberWithInt (getChapter (obj));
431         }
432         return 0;
433     }
434
435     NPObject *myAllocate ()
436     {
437         MyFunctionPtrObject *newInstance = (MyFunctionPtrObject *)malloc (sizeof(MyFunctionPtrObject));
438         
439         if (stopIdentifier == 0)
440             initializeIdentifiers();
441             
442         return (NPObject *)newInstance;
443     }
444
445     void myInvalidate ()
446     {
447         // Make sure we've released any remaining references to script
448         // objects.
449     }
450     
451     void myDeallocate (MyObject *obj) 
452     {
453         free ((void *)obj);
454     }
455     
456     static NPClass _myFunctionPtrs = { 
457         (NPAllocateFunctionPtr) myAllocate, 
458         (NPDeallocateFunctionPtr) myDeallocate, 
459         (NPInvalidateFunctionPtr) myInvalidate,
460         (NPHasMethodFunctionPtr) myHasMethod,
461         (NPInvokeFunctionPtr) myInvoke,
462         (NPHasPropertyFunctionPtr) myHasProperty,
463         (NPGetPropertyFunctionPtr) myGetProperty,
464         (NPSetPropertyFunctionPtr) mySetProperty,
465     };
466     static NPClass *myFunctionPtrs = &_myFunctionPtrs;
467
468     // myGetNativeObjectForScript would be set as the entry point for
469     // the plugin's NPP_GetNativeObjectForScript function.
470     // It is invoked by the plugin container, i.e. the browser.
471     NPObject *myGetNativeObjectForScript(NPP instance)
472     {
473         NPObject *myObject = NPN_CreateObject (myFunctionPtrs);
474         return myObject;
475     }
476
477 */
478
479
480 #ifdef __cplusplus
481 }
482 #endif
483
484 #endif