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