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