~ubuntu-branches/ubuntu/lucid/kdebase/lucid

« back to all changes in this revision

Viewing changes to nsplugins/sdk/npruntime.h

  • Committer: Bazaar Package Importer
  • Author(s): Ana Beatriz Guerrero Lopez
  • Date: 2009-04-05 05:22:13 UTC
  • mfrom: (0.4.2 experimental) (0.2.2 upstream)
  • mto: This revision was merged to the branch mainline in revision 235.
  • Revision ID: james.westby@ubuntu.com-20090405052213-39thr4l6p2ss07uj
Tags: 4:4.2.2-1
* New upstream release:
  - khtml fixes. (Closes: #290285, #359680)
  - Default konsole sessions can be deleted. (Closes: #286342)
  - Tag widget uses standard application palette. (Closes: #444800)
  - ... and surely many more but we have lost track...

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
/* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2
 
/*
3
 
 * Copyright � 2004, Apple Computer, Inc. and The Mozilla Foundation. 
4
 
 * All rights reserved.
5
 
 * 
6
 
 * Redistribution and use in source and binary forms, with or without
7
 
 * modification, are permitted provided that the following conditions are
8
 
 * met:
9
 
 * 
10
 
 * 1. Redistributions of source code must retain the above copyright
11
 
 * notice, this list of conditions and the following disclaimer.
12
 
 * 2. Redistributions in binary form must reproduce the above copyright
13
 
 * notice, this list of conditions and the following disclaimer in the
14
 
 * documentation and/or other materials provided with the distribution.
15
 
 * 3. Neither the names of Apple Computer, Inc. ("Apple") or The Mozilla
16
 
 * Foundation ("Mozilla") nor the names of their contributors may be used
17
 
 * to endorse or promote products derived from this software without
18
 
 * specific prior written permission.
19
 
 * 
20
 
 * THIS SOFTWARE IS PROVIDED BY APPLE, MOZILLA AND THEIR CONTRIBUTORS "AS
21
 
 * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
22
 
 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
23
 
 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE, MOZILLA OR
24
 
 * THEIR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25
 
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
26
 
 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
27
 
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
28
 
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
29
 
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
30
 
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31
 
 *
32
 
 * Revision 1 (March 4, 2004):
33
 
 * Initial proposal.
34
 
 *
35
 
 * Revision 2 (March 10, 2004):
36
 
 * All calls into script were made asynchronous.  Results are
37
 
 * provided via the NPScriptResultFunctionPtr callback.
38
 
 *
39
 
 * Revision 3 (March 10, 2004):
40
 
 * Corrected comments to not refer to class retain/release FunctionPtrs.
41
 
 *
42
 
 * Revision 4 (March 11, 2004):
43
 
 * Added additional convenience NPN_SetExceptionWithUTF8().
44
 
 * Changed NPHasPropertyFunctionPtr and NPHasMethodFunctionPtr to take NPClass
45
 
 * pointers instead of NPObject pointers.
46
 
 * Added NPIsValidIdentifier().
47
 
 *
48
 
 * Revision 5 (March 17, 2004):
49
 
 * Added context parameter to result callbacks from ScriptObject functions.
50
 
 *
51
 
 * Revision 6 (March 29, 2004):
52
 
 * Renamed functions implemented by user agent to NPN_*.  Removed _ from
53
 
 * type names.
54
 
 * Renamed "JavaScript" types to "Script".
55
 
 *
56
 
 * Revision 7 (April 21, 2004):
57
 
 * NPIdentifier becomes a void*, was int32_t
58
 
 * Remove NP_IsValidIdentifier, renamed NP_IdentifierFromUTF8 to NP_GetIdentifier
59
 
 * Added NPVariant and modified functions to use this new type.
60
 
 *
61
 
 * Revision 8 (July 9, 2004):
62
 
 * Updated to joint Apple-Mozilla license.
63
 
 *
64
 
 */
65
 
#ifndef _NP_RUNTIME_H_
66
 
#define _NP_RUNTIME_H_
67
 
 
68
 
#include <qglobal.h>
69
 
typedef Q_UINT32 uint32_t;
70
 
 
71
 
#ifdef __cplusplus
72
 
extern "C" {
73
 
#endif
74
 
 
75
 
 
76
 
/*
77
 
    This API is used to facilitate binding code written in C to script
78
 
    objects.  The API in this header does not assume the presence of a
79
 
    user agent.  That is, it can be used to bind C code to scripting
80
 
    environments outside of the context of a user agent.
81
 
    
82
 
    However, the normal use of the this API is in the context of a
83
 
    scripting environment running in a browser or other user agent.
84
 
    In particular it is used to support the extended Netscape
85
 
    script-ability API for plugins (NP-SAP).  NP-SAP is an extension
86
 
    of the Netscape plugin API.  As such we have adopted the use of
87
 
    the "NP" prefix for this API.
88
 
 
89
 
    The following NP{N|P}Variables were added to the Netscape plugin
90
 
    API (in npapi.h):
91
 
 
92
 
    NPNVWindowNPObject
93
 
    NPNVPluginElementNPObject
94
 
    NPPVpluginScriptableNPObject
95
 
 
96
 
    These variables are exposed through NPN_GetValue() and
97
 
    NPP_GetValue() (respectively) and are used to establish the
98
 
    initial binding between the user agent and native code.  The DOM
99
 
    objects in the user agent can be examined and manipulated using
100
 
    the NPN_ functions that operate on NPObjects described in this
101
 
    header.
102
 
 
103
 
    To the extent possible the assumptions about the scripting
104
 
    language used by the scripting environment have been minimized.
105
 
*/
106
 
 
107
 
#define NP_BEGIN_MACRO  do {
108
 
#define NP_END_MACRO    } while (0)
109
 
 
110
 
/*
111
 
    Objects (non-primitive data) passed between 'C' and script is
112
 
    always wrapped in an NPObject.  The 'interface' of an NPObject is
113
 
    described by an NPClass.
114
 
*/
115
 
typedef struct NPObject NPObject;
116
 
typedef struct NPClass NPClass;
117
 
 
118
 
typedef char NPUTF8;
119
 
typedef struct _NPString {
120
 
    const NPUTF8 *utf8characters;
121
 
    uint32_t utf8length;
122
 
} NPString;
123
 
 
124
 
typedef enum {
125
 
    NPVariantType_Void,
126
 
    NPVariantType_Null,
127
 
    NPVariantType_Bool,
128
 
    NPVariantType_Int32,
129
 
    NPVariantType_Double,
130
 
    NPVariantType_String,
131
 
    NPVariantType_Object
132
 
} NPVariantType;
133
 
 
134
 
typedef struct _NPVariant {
135
 
    NPVariantType type;
136
 
    union {
137
 
        bool boolValue;
138
 
        uint32_t intValue;
139
 
        double doubleValue;
140
 
        NPString stringValue;
141
 
        NPObject *objectValue;
142
 
    } value;
143
 
} NPVariant;
144
 
 
145
 
/*
146
 
    NPN_ReleaseVariantValue is called on all 'out' parameters
147
 
    references.  Specifically it is to be called on variants that own
148
 
    their value, as is the case with all non-const NPVariant*
149
 
    arguments after a successful call to any methods (except this one)
150
 
    in this API.
151
 
 
152
 
    After calling NPN_ReleaseVariantValue, the type of the variant
153
 
    will be NPVariantType_Void.
154
 
*/
155
 
void NPN_ReleaseVariantValue(NPVariant *variant);
156
 
 
157
 
#define NPVARIANT_IS_VOID(_v)    ((_v).type == NPVariantType_Void)
158
 
#define NPVARIANT_IS_NULL(_v)    ((_v).type == NPVariantType_Null)
159
 
#define NPVARIANT_IS_BOOLEAN(_v) ((_v).type == NPVariantType_Bool)
160
 
#define NPVARIANT_IS_INT32(_v)   ((_v).type == NPVariantType_Int32)
161
 
#define NPVARIANT_IS_DOUBLE(_v)  ((_v).type == NPVariantType_Double)
162
 
#define NPVARIANT_IS_STRING(_v)  ((_v).type == NPVariantType_String)
163
 
#define NPVARIANT_IS_OBJECT(_v)  ((_v).type == NPVariantType_Object)
164
 
 
165
 
#define NPVARIANT_TO_BOOLEAN(_v) ((_v).value.boolValue)
166
 
#define NPVARIANT_TO_INT32(_v)   ((_v).value.intValue)
167
 
#define NPVARIANT_TO_DOUBLE(_v)  ((_v).value.doubleValue)
168
 
#define NPVARIANT_TO_STRING(_v)  ((_v).value.stringValue)
169
 
#define NPVARIANT_TO_OBJECT(_v)  ((_v).value.objectValue)
170
 
 
171
 
#define VOID_TO_NPVARIANT(_v)                                                 \
172
 
NP_BEGIN_MACRO                                                                \
173
 
    (_v).type = NPVariantType_Void;                                           \
174
 
    (_v).value.objectValue = NULL;                                            \
175
 
NP_END_MACRO
176
 
 
177
 
#define NULL_TO_NPVARIANT(_v)                                                 \
178
 
NP_BEGIN_MACRO                                                                \
179
 
    (_v).type = NPVariantType_Null;                                           \
180
 
    (_v).value.objectValue = NULL;                                            \
181
 
NP_END_MACRO
182
 
 
183
 
#define BOOLEAN_TO_NPVARIANT(_val, _v)                                        \
184
 
NP_BEGIN_MACRO                                                                \
185
 
    (_v).type = NPVariantType_Bool;                                           \
186
 
    (_v).value.boolValue = !!(_val);                                          \
187
 
NP_END_MACRO
188
 
 
189
 
#define INT32_TO_NPVARIANT(_val, _v)                                          \
190
 
NP_BEGIN_MACRO                                                                \
191
 
    (_v).type = NPVariantType_Int32;                                          \
192
 
    (_v).value.intValue = _val;                                               \
193
 
NP_END_MACRO
194
 
 
195
 
#define DOUBLE_TO_NPVARIANT(_val, _v)                                         \
196
 
NP_BEGIN_MACRO                                                                \
197
 
    (_v).type = NPVariantType_Double;                                         \
198
 
    (_v).value.doubleValue = _val;                                            \
199
 
NP_END_MACRO
200
 
 
201
 
#define STRINGZ_TO_NPVARIANT(_val, _v)                                        \
202
 
NP_BEGIN_MACRO                                                                \
203
 
    (_v).type = NPVariantType_String;                                         \
204
 
    NPString str = { _val, strlen(_val) };                                    \
205
 
    (_v).value.stringValue = str;                                             \
206
 
NP_END_MACRO
207
 
 
208
 
#define STRINGN_TO_NPVARIANT(_val, _len, _v)                                  \
209
 
NP_BEGIN_MACRO                                                                \
210
 
    (_v).type = NPVariantType_String;                                         \
211
 
    NPString str = { _val, _len };                                            \
212
 
    (_v).value.stringValue = str;                                             \
213
 
NP_END_MACRO
214
 
 
215
 
#define OBJECT_TO_NPVARIANT(_val, _v)                                         \
216
 
NP_BEGIN_MACRO                                                                \
217
 
    (_v).type = NPVariantType_Object;                                         \
218
 
    (_v).value.objectValue = _val;                                            \
219
 
NP_END_MACRO
220
 
 
221
 
 
222
 
/*
223
 
        Type mappings (JavaScript types have been used for illustration
224
 
    purposes):
225
 
 
226
 
        JavaScript       to             C (NPVariant with type:)
227
 
        undefined                       NPVariantType_Void
228
 
        null                            NPVariantType_Null
229
 
        Boolean                         NPVariantType_Bool
230
 
        Number                          NPVariantType_Double or NPVariantType_Int32
231
 
        String                          NPVariantType_String
232
 
        Object                          NPVariantType_Object
233
 
 
234
 
        C (NPVariant with type:)   to   JavaScript
235
 
        NPVariantType_Void              undefined
236
 
        NPVariantType_Null              null
237
 
        NPVariantType_Bool              Boolean 
238
 
        NPVariantType_Int32             Number
239
 
        NPVariantType_Double            Number
240
 
        NPVariantType_String            String
241
 
        NPVariantType_Object            Object
242
 
*/
243
 
 
244
 
typedef void *NPIdentifier;
245
 
 
246
 
/*
247
 
    NPObjects have methods and properties.  Methods and properties are
248
 
    identified with NPIdentifiers.  These identifiers may be reflected
249
 
    in script.  NPIdentifiers can be either strings or integers, IOW,
250
 
    methods and properties can be identified by either strings or
251
 
    integers (i.e. foo["bar"] vs foo[1]). NPIdentifiers can be
252
 
    compared using ==.  In case of any errors, the requested
253
 
    NPIdentifier(s) will be NULL.
254
 
*/
255
 
NPIdentifier NPN_GetStringIdentifier(const NPUTF8 *name);
256
 
void NPN_GetStringIdentifiers(const NPUTF8 **names, int32_t nameCount,
257
 
                              NPIdentifier *identifiers);
258
 
NPIdentifier NPN_GetIntIdentifier(int32_t intid);
259
 
bool NPN_IdentifierIsString(NPIdentifier identifier);
260
 
 
261
 
/*
262
 
    The NPUTF8 returned from NPN_UTF8FromIdentifier SHOULD be freed.
263
 
*/
264
 
NPUTF8 *NPN_UTF8FromIdentifier(NPIdentifier identifier);
265
 
 
266
 
/*
267
 
    Get the integer represented by identifier. If identifier is not an
268
 
    integer identifier, the behaviour is undefined.
269
 
*/
270
 
int32_t NPN_IntFromIdentifier(NPIdentifier identifier);
271
 
 
272
 
/*
273
 
    NPObject behavior is implemented using the following set of
274
 
    callback functions.
275
 
 
276
 
    The NPVariant *result argument of these functions (where
277
 
    applicable) should be released using NPN_ReleaseVariantValue().
278
 
*/
279
 
typedef NPObject *(*NPAllocateFunctionPtr)(NPP npp, NPClass *aClass);
280
 
typedef void (*NPDeallocateFunctionPtr)(NPObject *npobj);
281
 
typedef void (*NPInvalidateFunctionPtr)(NPObject *npobj);
282
 
typedef bool (*NPHasMethodFunctionPtr)(NPObject *npobj, NPIdentifier name);
283
 
typedef bool (*NPInvokeFunctionPtr)(NPObject *npobj, NPIdentifier name,
284
 
                                    const NPVariant *args, uint32_t argCount,
285
 
                                    NPVariant *result);
286
 
typedef bool (*NPInvokeDefaultFunctionPtr)(NPObject *npobj,
287
 
                                           const NPVariant *args,
288
 
                                           uint32_t argCount,
289
 
                                           NPVariant *result);
290
 
typedef bool (*NPHasPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name);
291
 
typedef bool (*NPGetPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name,
292
 
                                         NPVariant *result);
293
 
typedef bool (*NPSetPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name,
294
 
                                         const NPVariant *value);
295
 
typedef bool (*NPRemovePropertyFunctionPtr)(NPObject *npobj,
296
 
                                            NPIdentifier name);
297
 
 
298
 
/*
299
 
    NPObjects returned by create, retain, invoke, and getProperty pass
300
 
    a reference count to the caller.  That is, the callee adds a
301
 
    reference count which passes to the caller.  It is the caller's
302
 
    responsibility to release the returned object.
303
 
 
304
 
    NPInvokeFunctionPtr function may return 0 to indicate a void
305
 
    result.
306
 
 
307
 
    NPInvalidateFunctionPtr is called by the scripting environment
308
 
    when the native code is shutdown.  Any attempt to message a
309
 
    NPObject instance after the invalidate callback has been
310
 
    called will result in undefined behavior, even if the native code
311
 
    is still retaining those NPObject instances.  (The runtime
312
 
    will typically return immediately, with 0 or NULL, from an attempt
313
 
    to dispatch to a NPObject, but this behavior should not be
314
 
    depended upon.)
315
 
*/
316
 
struct NPClass
317
 
{
318
 
    uint32_t structVersion;
319
 
    NPAllocateFunctionPtr allocate;
320
 
    NPDeallocateFunctionPtr deallocate;
321
 
    NPInvalidateFunctionPtr invalidate;
322
 
    NPHasMethodFunctionPtr hasMethod;
323
 
    NPInvokeFunctionPtr invoke;
324
 
    NPInvokeDefaultFunctionPtr invokeDefault;
325
 
    NPHasPropertyFunctionPtr hasProperty;
326
 
    NPGetPropertyFunctionPtr getProperty;
327
 
    NPSetPropertyFunctionPtr setProperty;
328
 
    NPRemovePropertyFunctionPtr removeProperty;
329
 
};
330
 
 
331
 
#define NP_CLASS_STRUCT_VERSION 1
332
 
 
333
 
struct NPObject {
334
 
    NPClass *_class;
335
 
    uint32_t referenceCount;
336
 
    /*
337
 
     * Additional space may be allocated here by types of NPObjects
338
 
     */
339
 
};
340
 
 
341
 
/*
342
 
    If the class has an allocate function, NPN_CreateObject invokes
343
 
    that function, otherwise a NPObject is allocated and
344
 
    returned. This method will initialize the referenceCount member of
345
 
    the NPObject to 1.
346
 
*/
347
 
NPObject *NPN_CreateObject(NPP npp, NPClass *aClass);
348
 
 
349
 
/*
350
 
    Increment the NPObject's reference count.
351
 
*/
352
 
NPObject *NPN_RetainObject(NPObject *npobj);
353
 
 
354
 
/*
355
 
    Decremented the NPObject's reference count.  If the reference
356
 
    count goes to zero, the class's destroy function is invoke if
357
 
    specified, otherwise the object is freed directly.
358
 
*/
359
 
void NPN_ReleaseObject(NPObject *npobj);
360
 
 
361
 
/*
362
 
    Functions to access script objects represented by NPObject.
363
 
 
364
 
    Calls to script objects are synchronous.  If a function returns a
365
 
    value, it will be supplied via the result NPVariant
366
 
    argument. Successful calls will return true, false will be
367
 
    returned in case of an error.
368
 
    
369
 
    Calls made from plugin code to script must be made from the thread
370
 
    on which the plugin was initialized.
371
 
*/
372
 
 
373
 
bool NPN_Invoke(NPP npp, NPObject *npobj, NPIdentifier methodName,
374
 
                const NPVariant *args, uint32_t argCount, NPVariant *result);
375
 
bool NPN_InvokeDefault(NPP npp, NPObject *npobj, const NPVariant *args,
376
 
                       uint32_t argCount, NPVariant *result);
377
 
bool NPN_Evaluate(NPP npp, NPObject *npobj, NPString *script,
378
 
                  NPVariant *result);
379
 
bool NPN_GetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName,
380
 
                     NPVariant *result);
381
 
bool NPN_SetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName,
382
 
                     const NPVariant *value);
383
 
bool NPN_RemoveProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName);
384
 
bool NPN_HasProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName);
385
 
bool NPN_HasMethod(NPP npp, NPObject *npobj, NPIdentifier methodName);
386
 
 
387
 
/*
388
 
    NPN_SetException may be called to trigger a script exception upon
389
 
    return from entry points into NPObjects.  Typical usage:
390
 
 
391
 
    NPN_SetException (npobj, message);
392
 
*/
393
 
void NPN_SetException(NPObject *npobj, const NPUTF8 *message);
394
 
 
395
 
#ifdef __cplusplus
396
 
}
397
 
#endif
398
 
 
399
 
#endif