|
|
mozilla/ js/ src/ xpconnect/ idl/ nsIXPConnect.idl |
|
|
Inheritance diagram for nsIXPConnect:
Collaboration diagram for nsIXPConnect:
[ nsIXPConnect Interface Reference | Graph Legend ]
1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
2 *
3 * ***** BEGIN LICENSE BLOCK *****
4 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
5 *
6 * The contents of this file are subject to the Mozilla Public License Version
7 * 1.1 (the "License"); you may not use this file except in compliance with
8 * the License. You may obtain a copy of the License at
9 * http://www.mozilla.org/MPL/
10 *
11 * Software distributed under the License is distributed on an "AS IS" basis,
12 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
13 * for the specific language governing rights and limitations under the
14 * License.
15 *
16 * The Original Code is Mozilla Communicator client code, released
17 * March 31, 1998.
18 *
19 * The Initial Developer of the Original Code is
20 * Netscape Communications Corporation.
21 * Portions created by the Initial Developer are Copyright (C) 1998
22 * the Initial Developer. All Rights Reserved.
23 *
24 * Contributor(s):
25 * John Bandhauer <jband@netscape.com> (original author)
26 * Nate Nielsen <nielsen@memberwebs.com>
27 *
28 * Alternatively, the contents of this file may be used under the terms of
29 * either of the GNU General Public License Version 2 or later (the "GPL"),
30 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
31 * in which case the provisions of the GPL or the LGPL are applicable instead
32 * of those above. If you wish to allow use of your version of this file only
33 * under the terms of either the GPL or the LGPL, and not to allow others to
34 * use your version of this file under the terms of the MPL, indicate your
35 * decision by deleting the provisions above and replace them with the notice
36 * and other provisions required by the GPL or the LGPL. If you do not delete
37 * the provisions above, a recipient may use your version of this file under
38 * the terms of any one of the MPL, the GPL or the LGPL.
39 *
40 * ***** END LICENSE BLOCK ***** */
41
42 /* The core XPConnect public interfaces. */
43
44 #include "nsISupports.idl"
45 #include "nsIClassInfo.idl"
46 #include "xpccomponents.idl"
47 #include "xpcjsid.idl"
48 #include "xpcexception.idl"
49 #include "nsIInterfaceInfo.idl"
50 #include "nsIInterfaceInfoManager.idl"
51 #include "nsIExceptionService.idl"
52 #include "nsIVariant.idl"
53 #include "nsIWeakReference.idl"
54
55 %{ C++
56 #include "jspubtd.h"
57 #include "xptinfo.h"
58 %}
59
60 /***************************************************************************/
61
62 [ptr] native JSContextPtr(JSContext);
63 [ptr] native JSObjectPtr(JSObject);
64 [ptr] native JSValPtr(jsval);
65 native JSVal(jsval);
66 native JSID(jsid);
67 [ptr] native voidPtrPtr(void*);
68
69 /***************************************************************************/
70
71 %{ C++
72 /***************************************************************************/
73 #define GENERATE_XPC_FAILURE(x) \
74 (NS_ERROR_GENERATE_FAILURE(NS_ERROR_MODULE_XPCONNECT,x))
75
76 #define NS_ERROR_XPC_NOT_ENOUGH_ARGS GENERATE_XPC_FAILURE( 1)
77 #define NS_ERROR_XPC_NEED_OUT_OBJECT GENERATE_XPC_FAILURE( 2)
78 #define NS_ERROR_XPC_CANT_SET_OUT_VAL GENERATE_XPC_FAILURE( 3)
79 #define NS_ERROR_XPC_NATIVE_RETURNED_FAILURE GENERATE_XPC_FAILURE( 4)
80 #define NS_ERROR_XPC_CANT_GET_INTERFACE_INFO GENERATE_XPC_FAILURE( 5)
81 #define NS_ERROR_XPC_CANT_GET_PARAM_IFACE_INFO GENERATE_XPC_FAILURE( 6)
82 #define NS_ERROR_XPC_CANT_GET_METHOD_INFO GENERATE_XPC_FAILURE( 7)
83 #define NS_ERROR_XPC_UNEXPECTED GENERATE_XPC_FAILURE( 8)
84 #define NS_ERROR_XPC_BAD_CONVERT_JS GENERATE_XPC_FAILURE( 9)
85 #define NS_ERROR_XPC_BAD_CONVERT_NATIVE GENERATE_XPC_FAILURE(10)
86 #define NS_ERROR_XPC_BAD_CONVERT_JS_NULL_REF GENERATE_XPC_FAILURE(11)
87 #define NS_ERROR_XPC_BAD_OP_ON_WN_PROTO GENERATE_XPC_FAILURE(12)
88 #define NS_ERROR_XPC_CANT_CONVERT_WN_TO_FUN GENERATE_XPC_FAILURE(13)
89 #define NS_ERROR_XPC_CANT_DEFINE_PROP_ON_WN GENERATE_XPC_FAILURE(14)
90 #define NS_ERROR_XPC_CANT_WATCH_WN_STATIC GENERATE_XPC_FAILURE(15)
91 #define NS_ERROR_XPC_CANT_EXPORT_WN_STATIC GENERATE_XPC_FAILURE(16)
92 #define NS_ERROR_XPC_SCRIPTABLE_CALL_FAILED GENERATE_XPC_FAILURE(17)
93 #define NS_ERROR_XPC_SCRIPTABLE_CTOR_FAILED GENERATE_XPC_FAILURE(18)
94 #define NS_ERROR_XPC_CANT_CALL_WO_SCRIPTABLE GENERATE_XPC_FAILURE(19)
95 #define NS_ERROR_XPC_CANT_CTOR_WO_SCRIPTABLE GENERATE_XPC_FAILURE(20)
96 #define NS_ERROR_XPC_CI_RETURNED_FAILURE GENERATE_XPC_FAILURE(21)
97 #define NS_ERROR_XPC_GS_RETURNED_FAILURE GENERATE_XPC_FAILURE(22)
98 #define NS_ERROR_XPC_BAD_CID GENERATE_XPC_FAILURE(23)
99 #define NS_ERROR_XPC_BAD_IID GENERATE_XPC_FAILURE(24)
100 #define NS_ERROR_XPC_CANT_CREATE_WN GENERATE_XPC_FAILURE(25)
101 #define NS_ERROR_XPC_JS_THREW_EXCEPTION GENERATE_XPC_FAILURE(26)
102 #define NS_ERROR_XPC_JS_THREW_NATIVE_OBJECT GENERATE_XPC_FAILURE(27)
103 #define NS_ERROR_XPC_JS_THREW_JS_OBJECT GENERATE_XPC_FAILURE(28)
104 #define NS_ERROR_XPC_JS_THREW_NULL GENERATE_XPC_FAILURE(29)
105 #define NS_ERROR_XPC_JS_THREW_STRING GENERATE_XPC_FAILURE(30)
106 #define NS_ERROR_XPC_JS_THREW_NUMBER GENERATE_XPC_FAILURE(31)
107 #define NS_ERROR_XPC_JAVASCRIPT_ERROR GENERATE_XPC_FAILURE(32)
108 #define NS_ERROR_XPC_JAVASCRIPT_ERROR_WITH_DETAILS GENERATE_XPC_FAILURE(33)
109 #define NS_ERROR_XPC_CANT_CONVERT_PRIMITIVE_TO_ARRAY GENERATE_XPC_FAILURE(34)
110 #define NS_ERROR_XPC_CANT_CONVERT_OBJECT_TO_ARRAY GENERATE_XPC_FAILURE(35)
111 #define NS_ERROR_XPC_NOT_ENOUGH_ELEMENTS_IN_ARRAY GENERATE_XPC_FAILURE(36)
112 #define NS_ERROR_XPC_CANT_GET_ARRAY_INFO GENERATE_XPC_FAILURE(37)
113 #define NS_ERROR_XPC_NOT_ENOUGH_CHARS_IN_STRING GENERATE_XPC_FAILURE(38)
114 #define NS_ERROR_XPC_SECURITY_MANAGER_VETO GENERATE_XPC_FAILURE(39)
115 #define NS_ERROR_XPC_INTERFACE_NOT_SCRIPTABLE GENERATE_XPC_FAILURE(40)
116 #define NS_ERROR_XPC_INTERFACE_NOT_FROM_NSISUPPORTS GENERATE_XPC_FAILURE(41)
117 #define NS_ERROR_XPC_CANT_GET_JSOBJECT_OF_DOM_OBJECT GENERATE_XPC_FAILURE(42)
118 #define NS_ERROR_XPC_CANT_SET_READ_ONLY_CONSTANT GENERATE_XPC_FAILURE(43)
119 #define NS_ERROR_XPC_CANT_SET_READ_ONLY_ATTRIBUTE GENERATE_XPC_FAILURE(44)
120 #define NS_ERROR_XPC_CANT_SET_READ_ONLY_METHOD GENERATE_XPC_FAILURE(45)
121 #define NS_ERROR_XPC_CANT_ADD_PROP_TO_WRAPPED_NATIVE GENERATE_XPC_FAILURE(46)
122 #define NS_ERROR_XPC_CALL_TO_SCRIPTABLE_FAILED GENERATE_XPC_FAILURE(47)
123 #define NS_ERROR_XPC_JSOBJECT_HAS_NO_FUNCTION_NAMED GENERATE_XPC_FAILURE(48)
124 #define NS_ERROR_XPC_BAD_ID_STRING GENERATE_XPC_FAILURE(49)
125 #define NS_ERROR_XPC_BAD_INITIALIZER_NAME GENERATE_XPC_FAILURE(50)
126 #define NS_ERROR_XPC_HAS_BEEN_SHUTDOWN GENERATE_XPC_FAILURE(51)
127 #define NS_ERROR_XPC_CANT_MODIFY_PROP_ON_WN GENERATE_XPC_FAILURE(52)
128 #define NS_ERROR_XPC_BAD_CONVERT_JS_ZERO_ISNOT_NULL GENERATE_XPC_FAILURE(53)
129
130 #ifdef XPC_IDISPATCH_SUPPORT
131 // IDispatch support related errors
132 #define NS_ERROR_XPC_COM_UNKNOWN GENERATE_XPC_FAILURE(54)
133 #define NS_ERROR_XPC_COM_ERROR GENERATE_XPC_FAILURE(55)
134 #define NS_ERROR_XPC_COM_INVALID_CLASS_ID GENERATE_XPC_FAILURE(56)
135 #define NS_ERROR_XPC_COM_CREATE_FAILED GENERATE_XPC_FAILURE(57)
136 #define NS_ERROR_XPC_IDISPATCH_NOT_ENABLED GENERATE_XPC_FAILURE(58)
137 #endif
138 // any new errors here should have an associated entry added in xpc.msg
139 /***************************************************************************/
140 %}
141
142 /***************************************************************************/
143
144 // forward declarations...
145 interface nsIXPCScriptable;
146 interface nsIXPConnect;
147 interface nsIXPConnectWrappedNative;
148 interface nsIInterfaceInfo;
149 interface nsIXPCSecurityManager;
150 interface nsIPrincipal;
151
152 /***************************************************************************/
153 [uuid(8916a320-d118-11d3-8f3a-0010a4e73d9a)]
154 interface nsIXPConnectJSObjectHolder : nsISupports
155 {
156 readonly attribute JSObjectPtr JSObject;
157 };
158
159 [uuid(215DBE02-94A7-11d2-BA58-00805F8A5DD7)]
160 interface nsIXPConnectWrappedNative : nsIXPConnectJSObjectHolder
161 {
162 /* attribute 'JSObject' inherited from nsIXPConnectJSObjectHolder */
163 readonly attribute nsISupports Native;
164 readonly attribute JSObjectPtr JSObjectPrototype;
165
166 /**
167 * These are here as an aid to nsIXPCScriptable implementors
168 */
169
170 readonly attribute nsIXPConnect XPConnect;
171 nsIInterfaceInfo FindInterfaceWithMember(in JSVal nameID);
172 nsIInterfaceInfo FindInterfaceWithName(in JSVal nameID);
173
174 void debugDump(in short depth);
175
176 void refreshPrototype();
177 /*
178 * This returns a pointer into the instance and care should be taken
179 * to make sure the pointer is not kept past the life time of the
180 * object it points into.
181 */
182 voidPtrPtr GetSecurityInfoAddress();
183
184 %{C++
185 /**
186 * Faster access to the native object from C++. Will never return null.
187 */
188 nsISupports* Native() const { return mIdentity; }
189
190 protected:
191 nsISupports *mIdentity;
192 public:
193 %}
194 };
195
196 %{C++
197 inline
198 const nsQueryInterface
199 do_QueryWrappedNative(nsIXPConnectWrappedNative *aWrappedNative)
200 {
201 return nsQueryInterface(aWrappedNative->Native());
202 }
203
204 inline
205 const nsQueryInterfaceWithError
206 do_QueryWrappedNative(nsIXPConnectWrappedNative *aWrappedNative,
207 nsresult *aError)
208
209 {
210 return nsQueryInterfaceWithError(aWrappedNative->Native(), aError);
211 }
212
213 %}
214
215 [uuid(BED52030-BCA6-11d2-BA79-00805F8A5DD7)]
216 interface nsIXPConnectWrappedJS : nsIXPConnectJSObjectHolder
217 {
218 /* attribute 'JSObject' inherited from nsIXPConnectJSObjectHolder */
219 readonly attribute nsIInterfaceInfo InterfaceInfo;
220 readonly attribute nsIIDPtr InterfaceIID;
221
222 void debugDump(in short depth);
223
224 void aggregatedQueryInterface(in nsIIDRef uuid,
225 [iid_is(uuid),retval] out nsQIResult result);
226 };
227
228 [uuid(0f1799d3-13d3-45f7-8361-0a6f211183f4)]
229 interface nsIXPConnectWrappedJS_MOZILLA_1_8_BRANCH : nsIXPConnectWrappedJS
230 {
231 /* This method has the same signature and the same semantics as the
232 * one method on nsISupportsWeakReference. However, it exists here
233 * so that callers who need to manage JS garbage collection for
234 * wrapped objects themselves can get a weak reference to the
235 * wrapped JS object: in other words, it's for callers who know
236 * that they're dealing with a wrapper, and want a weak reference to
237 * the wrapper rather than the wrapped object.
238 */
239 nsIWeakReference GetWeakReference();
240 };
241
242 /**
243 * This interface is a complete hack. It is used by the DOM code to
244 * call QueryReferent on a weak reference to a wrapped JS object without
245 * causing reference counting, which would add and remove GC roots
246 * (which can't be done in the middle of GC).
247 */
248 [uuid(3f32871c-d014-4f91-b358-3ece74cbebaa)]
249 interface nsWeakRefToIXPConnectWrappedJS : nsIXPConnectWrappedJS_MOZILLA_1_8_BRANCH
250 {
251 };
252
253 /***************************************************************************/
254
255 /**
256 * This is a somewhat special interface. It is available from the global
257 * nsIXPConnect object when native methods have been called. It is only relevant
258 * to the currently called native method on the given JSContext/thread. Holding
259 * a reference past that time (or while other native methods are being called)
260 * will not assure access to this data.
261 */
262
263 [uuid(0FA68A60-8289-11d3-BB1A-00805F8A5DD7)]
264 interface nsIXPCNativeCallContext : nsISupports
265 {
266
267 readonly attribute nsISupports Callee;
268 readonly attribute PRUint16 CalleeMethodIndex;
269 readonly attribute nsIXPConnectWrappedNative CalleeWrapper;
270 readonly attribute JSContextPtr JSContext;
271 readonly attribute PRUint32 Argc;
272 readonly attribute JSValPtr ArgvPtr;
273 /**
274 * This may be NULL if the JS caller is ignoring the result of the call.
275 */
276 readonly attribute JSValPtr RetValPtr;
277 /**
278 * Set this if JS_SetPendingException has been called. Return NS_OK or
279 * else this will be ignored and the native method's nsresult will be
280 * converted into an exception and thrown into JS as is the normal case.
281 */
282 attribute PRBool ExceptionWasThrown;
283
284 /**
285 * Set this to indicate that the callee has directly set the return value
286 * (using RetValPtr and the JSAPI). If set then xpconnect will not attempt
287 * to overwrite it with the converted retval from the C++ callee.
288 */
289 attribute PRBool ReturnValueWasSet;
290
291 // Methods added since mozilla 0.6....
292
293 readonly attribute nsIInterfaceInfo CalleeInterface;
294 readonly attribute nsIClassInfo CalleeClassInfo;
295 };
296
297 /***************************************************************************/
298
299 /**
300 * This is a sort of a placeholder interface. It is not intended to be
301 * implemented. It exists to give the nsIXPCSecurityManager an iid on
302 * which to gate a specific activity in XPConnect.
303 *
304 * That activity is...
305 *
306 * When JavaScript code uses a component that is itself implemeted in
307 * JavaScript then XPConnect will build a wrapper rather than directly
308 * expose the JSObject of the component. This allows components implemented
309 * in JavaScript to 'look' just like any other xpcom component (from the
310 * perspective of the JavaScript caller). This insulates the component from
311 * the caller and hides any properties or methods that are not part of the
312 * interface as declared in xpidl. Usually this is a good thing.
313 *
314 * However, in some cases it is useful to allow the JS caller access to the
315 * JS component's underlying implementation. In order to facilitate this
316 * XPConnect supports the 'wrappedJSObject' property. The caller code can do:
317 *
318 * // 'foo' is some xpcom component (that might be implemented in JS).
319 * try {
320 * var bar = foo.wrappedJSObject;
321 * if(bar) {
322 * // bar is the underlying JSObject. Do stuff with it here.
323 * }
324 * } catch(e) {
325 * // security exception?
326 * }
327 *
328 * Recall that 'foo' above is an XPConnect wrapper, not the underlying JS
329 * object. The property get "foo.wrappedJSObject" will only succeed if three
330 * conditions are met:
331 *
332 * 1) 'foo' really is an XPConnect wrapper around a JSObject.
333 * 2) The underlying JSObject actually implements a "wrappedJSObject"
334 * property that returns a JSObject. This is called by XPConnect. This
335 * restriction allows wrapped objects to only allow access to the underlying
336 * JSObject if they choose to do so. Ususally this just means that 'foo'
337 * would have a property tht looks like:
338 * this.wrappedJSObject = this.
339 * 3) The implemementation of nsIXPCSecurityManager (if installed) allows
340 * a property get on the interface below. Although the JSObject need not
341 * implement 'nsIXPCWrappedJSObjectGetter', XPConnect will ask the
342 * security manager if it is OK for the caller to access the only method
343 * in nsIXPCWrappedJSObjectGetter before allowing the activity. This fits
344 * in with the security manager paradigm and makes control over accessing
345 * the property on this interface the control factor for getting the
346 * underlying wrapped JSObject of a JS component from JS code.
347 *
348 * Notes:
349 *
350 * a) If 'foo' above were the underlying JSObject and not a wrapper at all,
351 * then this all just works and XPConnect is not part of the picture at all.
352 * b) One might ask why 'foo' should not just implement an interface through
353 * which callers might get at the underlying object. There are three reasons:
354 * i) XPConnect would still have to do magic since JSObject is not a
355 * scriptable type.
356 * ii) JS Components might use aggregation (like C++ objects) and have
357 * different JSObjects for different interfaces 'within' an aggregate
358 * object. But, using an additional interface only allows returning one
359 * underlying JSObject. However, this allows for the possibility that
360 * each of the aggregte JSObjects could return something different.
361 * Note that one might do: this.wrappedJSObject = someOtherObject;
362 * iii) Avoiding the explicit interface makes it easier for both the caller
363 * and the component.
364 *
365 * Anyway, some future implementation of nsIXPCSecurityManager might want
366 * do special processing on 'nsIXPCSecurityManager::CanGetProperty' when
367 * the interface id is that of nsIXPCWrappedJSObjectGetter.
368 */
369
370 [scriptable, uuid(254bb2e0-6439-11d4-8fe0-0010a4e73d9a)]
371 interface nsIXPCWrappedJSObjectGetter : nsISupports
372 {
373 readonly attribute nsISupports neverCalled;
374 };
375
376 /***************************************************************************/
377
378 /*
379 * This interface is implemented by outside code and registered with xpconnect
380 * via nsIXPConnect::setFunctionThisTranslator.
381 *
382 * The reason this exists is to support calls to JavaScript event callbacks
383 * needed by the DOM via xpconnect from C++ code.
384 *
385 * We've added support for wrapping JS function objects as xpcom interfaces
386 * by declaring the given interface as a [function] interface. However, to
387 * support the requirements of JS event callbacks we need to call the JS
388 * function with the 'this' set as the JSObject for which the event is being
389 * fired; e.g. a form node.
390 *
391 * We've decided that for all cases we care about the appropriate 'this' object
392 * can be derived from the first param in the call to the callback. In the
393 * event handler case the first param is an event object.
394 *
395 * Though we can't change all the JS code so that it would setup its own 'this',
396 * we can add plugin 'helper' support to xpconnect. And that is what we have
397 * here.
398 *
399 * The idea is that at startup time some code that cares about this issue
400 * (e.g. the DOM helper code) can register a nsIXPCFunctionThisTranslator
401 * object with xpconnect to handle calls to [function] interfaces of a given
402 * iid. When xpconnect goes to invoke a method on a wrapped JSObject for
403 * an interface marked as [function], xpconnect will check if the first param
404 * of the method is an xpcom object pointer and if so it will check to see if a
405 * nsIXPCFunctionThisTranslator has been registered for the given iid of the
406 * interface being called. If so it will call the translator and get an
407 * interface pointer to use as the 'this' for the call. If the translator
408 * returns a non-null interface pointer (which it should then have addref'd
409 * since it is being returned as an out param), xpconnect will attempt to build
410 * a wrapper around the pointer and get a JSObject from that wrapper to use
411 * as the 'this' for the call.
412 *
413 * If a null interface pointer is returned then xpconnect will use the default
414 * 'this' - the same JSObject as the function object it is calling.
415 *
416 * The translator can also return a non-null aIIDOfResult to tell xpconnect what
417 * type of wrapper to build. If that is null then xpconnect will assume the
418 * wrapper should be for nsISupports. For objects that support flattening -
419 * i.e. expose nsIClassInfo and that interface's getInterfaces method - then
420 * a flattened wrapper will be created and no iid was really necessary.
421 *
422 * XXX aHideFirstParamFromJS is intended to allow the trimming of that first
423 * param (used to indicate 'this') from the actual call to the JS code. The JS
424 * DOM does not require this functionality and it is **NOT YET IMPLEMENTED**
425 *
426 */
427
428 [uuid(039ef260-2a0d-11d5-90a7-0010a4e73d9a)]
429 interface nsIXPCFunctionThisTranslator : nsISupports
430 {
431 nsISupports TranslateThis(in nsISupports aInitialThis,
432 in nsIInterfaceInfo aInterfaceInfo,
433 in PRUint16 aMethodIndex,
434 out PRBool aHideFirstParamFromJS,
435 out nsIIDPtr aIIDOfResult);
436 };
437
438 /***************************************************************************/
439
440 %{ C++
441 // For use with the service manager
442 // {CB6593E0-F9B2-11d2-BDD6-000064657374}
443 #define NS_XPCONNECT_CID \
444 { 0xcb6593e0, 0xf9b2, 0x11d2, \
445 { 0xbd, 0xd6, 0x0, 0x0, 0x64, 0x65, 0x73, 0x74 } }
446 %}
447
448 [uuid(DEB1D48E-7469-4B01-B186-D9854C7D3F2D)]
449 interface nsIXPConnect : nsISupports
450 {
451 %{ C++
452 NS_DEFINE_STATIC_CID_ACCESSOR(NS_XPCONNECT_CID)
453 %}
454
455 void
456 initClasses(in JSContextPtr aJSContext,
457 in JSObjectPtr aGlobalJSObj);
458
459 nsIXPConnectJSObjectHolder
460 initClassesWithNewWrappedGlobal(
461 in JSContextPtr aJSContext,
462 in nsISupports aCOMObj,
463 in nsIIDRef aIID,
464 in PRUint32 aFlags);
465
466 const PRUint32 INIT_JS_STANDARD_CLASSES = 1 << 0;
467 const PRUint32 FLAG_SYSTEM_GLOBAL_OBJECT = 1 << 1;
468
469 /**
470 * wrapNative will create a new JSObject or return an existing one.
471 *
472 * The JSObject is returned inside a refcounted nsIXPConnectJSObjectHolder.
473 * As long as this holder is held the JSObject will be protected from
474 * collection by JavaScript's garbage collector. It is a good idea to
475 * transfer the JSObject to some equally protected place before releasing
476 * the holder (i.e. use JS_SetProperty to make this object a property of
477 * some other JSObject).
478 *
479 * This method now correctly deals with cases where the passed in xpcom
480 * object already has an associated JSObject for the cases:
481 * 1) The xpcom object has already been wrapped for use in the same scope
482 * as an nsIXPConnectWrappedNative.
483 * 2) The xpcom object is in fact a nsIXPConnectWrappedJS and thus already
484 * has an underlying JSObject.
485 * 3) The xpcom object implements nsIScriptObjectOwner; i.e. is an idlc
486 * style DOM object for which we can call GetScriptObject to get the
487 * JSObject it uses to represent itself into JavaScript.
488 *
489 * It *might* be possible to QueryInterface the nsIXPConnectJSObjectHolder
490 * returned by the method into a nsIXPConnectWrappedNative or a
491 * nsIXPConnectWrappedJS.
492 *
493 * This method will never wrap the JSObject involved in an
494 * XPCNativeWrapper before returning.
495 *
496 * Returns:
497 * success:
498 * NS_OK
499 * failure:
500 * NS_ERROR_XPC_BAD_CONVERT_NATIVE
501 * NS_ERROR_XPC_CANT_GET_JSOBJECT_OF_DOM_OBJECT
502 * NS_ERROR_FAILURE
503 */
504 nsIXPConnectJSObjectHolder
505 wrapNative(in JSContextPtr aJSContext,
506 in JSObjectPtr aScope,
507 in nsISupports aCOMObj,
508 in nsIIDRef aIID);
509
510 /**
511 * wrapJS will yield a new or previously existing xpcom interface pointer
512 * to represent the JSObject passed in.
513 *
514 * This method now correctly deals with cases where the passed in JSObject
515 * already has an associated xpcom interface for the cases:
516 * 1) The JSObject has already been wrapped as a nsIXPConnectWrappedJS.
517 * 2) The JSObject is in fact a nsIXPConnectWrappedNative and thus already
518 * has an underlying xpcom object.
519 * 3) The JSObject is of a jsclass which supports getting the nsISupports
520 * from the JSObject directly. This is used for idlc style objects
521 * (e.g. DOM objects).
522 *
523 * It *might* be possible to QueryInterface the resulting interface pointer
524 * to nsIXPConnectWrappedJS.
525 *
526 * Returns:
527 * success:
528 * NS_OK
529 * failure:
530 * NS_ERROR_XPC_BAD_CONVERT_JS
531 * NS_ERROR_FAILURE
532 */
533 void
534 wrapJS(in JSContextPtr aJSContext,
535 in JSObjectPtr aJSObj,
536 in nsIIDRef aIID,
537 [iid_is(aIID),retval] out nsQIResult result);
538
539 /**
540 * This only succeeds if the JSObject is a nsIXPConnectWrappedNative.
541 * A new wrapper is *never* constructed.
542 */
543 nsIXPConnectWrappedNative
544 getWrappedNativeOfJSObject(in JSContextPtr aJSContext,
545 in JSObjectPtr aJSObj);
546
547 void setSecurityManagerForJSContext(in JSContextPtr aJSContext,
548 in nsIXPCSecurityManager aManager,
549 in PRUint16 flags);
550
551 void getSecurityManagerForJSContext(in JSContextPtr aJSContext,
552 out nsIXPCSecurityManager aManager,
553 out PRUint16 flags);
554
555 /**
556 * The security manager to use when the current JSContext has no security
557 * manager.
558 */
559 void setDefaultSecurityManager(in nsIXPCSecurityManager aManager,
560 in PRUint16 flags);
561
562 void getDefaultSecurityManager(out nsIXPCSecurityManager aManager,
563 out PRUint16 flags);
564
565 nsIStackFrame
566 createStackFrameLocation(in PRUint32 aLanguage,
567 in string aFilename,
568 in string aFunctionName,
569 in PRInt32 aLineNumber,
570 in nsIStackFrame aCaller);
571
572 /**
573 * XPConnect builds internal objects that parallel, and are one-to-one with,
574 * the JSContexts in the JSRuntime. It builds these objects as needed.
575 * This method tells XPConnect to resynchronize its representations with the
576 * list of JSContexts currently 'alive' in the JSRuntime. This allows it
577 * to cleanup any representations of JSContexts that are no longer valid.
578 */
579 void syncJSContexts();
580
581 readonly attribute nsIStackFrame CurrentJSStack;
582 readonly attribute nsIXPCNativeCallContext CurrentNativeCallContext;
583 /* pass nsnull to clear pending exception */
584 attribute nsIException PendingException;
585
586 void debugDump(in short depth);
587 void debugDumpObject(in nsISupports aCOMObj, in short depth);
588 void debugDumpJSStack(in PRBool showArgs,
589 in PRBool showLocals,
590 in PRBool showThisProps);
591 void debugDumpEvalInJSStackFrame(in PRUint32 aFrameNumber,
592 in string aSourceText);
593
594 /**
595 * Set fallback JSContext to use when xpconnect can't find an appropriate
596 * context to use to execute JavaScript.
597 *
598 * NOTE: This method is DEPRECATED.
599 * Use nsIThreadJSContextStack::safeJSContext instead.
600 */
601 void setSafeJSContextForCurrentThread(in JSContextPtr cx);
602
603 /**
604 * wrapJSAggregatedToNative is just like wrapJS except it is used in cases
605 * where the JSObject is also aggregated to some native xpcom Object.
606 * At present XBL is the only system that might want to do this.
607 *
608 * XXX write more!
609 *
610 * Returns:
611 * success:
612 * NS_OK
613 * failure:
614 * NS_ERROR_XPC_BAD_CONVERT_JS
615 * NS_ERROR_FAILURE
616 */
617 void
618 wrapJSAggregatedToNative(in nsISupports aOuter,
619 in JSContextPtr aJSContext,
620 in JSObjectPtr aJSObj,
621 in nsIIDRef aIID,
622 [iid_is(aIID),retval] out nsQIResult result);
623
624 // Methods added since mozilla 0.6....
625
626 /**
627 * This only succeeds if the native object is already wrapped by xpconnect.
628 * A new wrapper is *never* constructed.
629 */
630 nsIXPConnectWrappedNative
631 getWrappedNativeOfNativeObject(in JSContextPtr aJSContext,
632 in JSObjectPtr aScope,
633 in nsISupports aCOMObj,
634 in nsIIDRef aIID);
635
636 nsIXPCFunctionThisTranslator
637 getFunctionThisTranslator(in nsIIDRef aIID);
638
639 nsIXPCFunctionThisTranslator
640 setFunctionThisTranslator(in nsIIDRef aIID,
641 in nsIXPCFunctionThisTranslator aTranslator);
642
643 nsIXPConnectJSObjectHolder
644 reparentWrappedNativeIfFound(in JSContextPtr aJSContext,
645 in JSObjectPtr aScope,
646 in JSObjectPtr aNewParent,
647 in nsISupports aCOMObj);
648
649 void clearAllWrappedNativeSecurityPolicies();
650
651 nsIXPConnectJSObjectHolder
652 getWrappedNativePrototype(in JSContextPtr aJSContext,
653 in JSObjectPtr aScope,
654 in nsIClassInfo aClassInfo);
655
656 attribute PRBool collectGarbageOnMainThreadOnly;
657 attribute PRBool deferReleasesUntilAfterGarbageCollection;
658
659 void releaseJSContext(in JSContextPtr aJSContext, in PRBool noGC);
660
661 JSVal variantToJS(in JSContextPtr ctx, in JSObjectPtr scope, in nsIVariant value);
662 nsIVariant JSToVariant(in JSContextPtr ctx, in JSVal value);
663
664 /**
665 * Preconfigure XPCNativeWrapper automation so that when a scripted
666 * caller whose filename starts with filenamePrefix accesses a wrapped
667 * native that is not flagged as "system", the wrapped native will be
668 * automatically wrapped with an XPCNativeWrapper.
669 *
670 * @param aFilenamePrefix the UTF-8 filename prefix to match, which
671 * should end with a slash (/) character
672 */
673 void flagSystemFilenamePrefix(in string aFilenamePrefix);
674
675 /**
676 * Restore an old prototype for wrapped natives of type
677 * aClassInfo. This should be used only when restoring an old
678 * scope into a state close to where it was prior to
679 * being reinitialized.
680 */
681 void restoreWrappedNativePrototype(in JSContextPtr aJSContext,
682 in JSObjectPtr aScope,
683 in nsIClassInfo aClassInfo,
684 in nsIXPConnectJSObjectHolder aPrototype);
685 };
686
687 [uuid(4b61f818-d260-45ab-ac4e-d27790b5be5e)]
688 interface nsIXPConnect_MOZILLA_1_8_BRANCH : nsIXPConnect
689 {
690 void
691 reparentScopeAwareWrappers(in JSContextPtr aJSContext,
692 in JSObjectPtr aOldScope,
693 in JSObjectPtr aNewScope);
694
695 /**
696 * Create a sandbox for evaluating code in isolation using
697 * evalInSandboxObject().
698 *
699 * @param cx A context to use when creating the sandbox object.
700 * @param principal The principal (or NULL to use the null principal)
701 * to use when evaluating code in this sandbox.
702 */
703 nsIXPConnectJSObjectHolder createSandbox(in JSContextPtr cx,
704 in nsIPrincipal principal);
705
706 /**
707 * Evaluate script in a sandbox, completely isolated from all
708 * other running scripts.
709 *
710 * @param source The source of the script to evaluate.
711 * @param cx The context to use when setting up the evaluation of
712 * the script. The actual evaluation will happen on a new
713 * temporary context.
714 * @param sandbox The sandbox object to evaluate the script in.
715 * @return The result of the evaluation as a jsval. If the caller
716 * intends to use the return value from this call the caller
717 * is responsible for rooting the jsval before making a call
718 * to this method.
719 */
720 JSVal evalInSandboxObject(in AString source, in JSContextPtr cx,
721 in nsIXPConnectJSObjectHolder sandbox);
722 };
723
724 [uuid(f4bec7f9-256b-4acd-b32c-2c3d37615190)]
725 interface nsIXPConnect_MOZILLA_1_8_BRANCH2 : nsIXPConnect_MOZILLA_1_8_BRANCH
726 {
727 /**
728 * Evaluate script in a sandbox, completely isolated from all
729 * other running scripts.
730 *
731 * @param source The source of the script to evaluate.
732 * @param cx The context to use when setting up the evaluation of
733 * the script. The actual evaluation will happen on a new
734 * temporary context.
735 * @param sandbox The sandbox object to evaluate the script in.
736 * @param returnStringOnly The only results to come out of the
737 * computation (including exceptions) will
738 * be coerced into strings created in the
739 * sandbox.
740 * @return The result of the evaluation as a jsval. If the caller
741 * intends to use the return value from this call the caller
742 * is responsible for rooting the jsval before making a call
743 * to this method.
744 */
745 JSVal evalInSandboxObject2(in AString source, in JSContextPtr cx,
746 in nsIXPConnectJSObjectHolder sandbox,
747 in PRBool returnStringOnly);
748 };
749