js/xpconnect/idl/nsIXPConnect.idl@6474c204b198
js/xpconnect/idl/nsIXPConnect.idl
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
1 /* -*- Mode: IDL; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
2 *
3 * This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
7 /* The core XPConnect public interfaces. */
9 #include "nsISupports.idl"
11 %{ C++
12 #include "jspubtd.h"
13 #include "js/TypeDecls.h"
15 struct JSFreeOp;
17 class nsWrapperCache;
18 class nsAXPCNativeCallContext;
19 %}
21 /***************************************************************************/
23 // NB: jsval and jsid are declared in nsrootidl.idl
25 [ptr] native JSContextPtr(JSContext);
26 [ptr] native JSClassPtr(JSClass);
27 [ptr] native JSFreeOpPtr(JSFreeOp);
28 [ptr] native JSObjectPtr(JSObject);
29 [ptr] native JSValConstPtr(const JS::Value);
30 native JSPropertyOp(JSPropertyOp);
31 native JSEqualityOp(JSEqualityOp);
32 [ptr] native JSScriptPtr(JSScript);
33 [ptr] native voidPtrPtr(void*);
34 [ptr] native nsAXPCNativeCallContextPtr(nsAXPCNativeCallContext);
35 [ptr] native nsWrapperCachePtr(nsWrapperCache);
36 [ref] native JSCompartmentOptions(JS::CompartmentOptions);
37 [ref] native JSCallArgsRef(const JS::CallArgs);
38 native JSHandleId(JS::Handle<jsid>);
40 /***************************************************************************/
42 // forward declarations...
43 interface nsIXPCScriptable;
44 interface nsIXPConnect;
45 interface nsIXPConnectWrappedNative;
46 interface nsIInterfaceInfo;
47 interface nsIXPCSecurityManager;
48 interface nsIPrincipal;
49 interface nsIClassInfo;
50 interface nsIVariant;
51 interface nsIStackFrame;
52 interface nsIObjectInputStream;
53 interface nsIObjectOutputStream;
55 /***************************************************************************/
56 [uuid(909e8641-7c54-4dff-9b94-ba631f057b33)]
57 interface nsIXPConnectJSObjectHolder : nsISupports
58 {
59 [notxpcom, nostdcall] JSObjectPtr GetJSObject();
60 };
62 [uuid(675b01ba-397b-472a-9b80-5716376a2ec6)]
63 interface nsIXPConnectWrappedNative : nsIXPConnectJSObjectHolder
64 {
65 /* attribute 'JSObject' inherited from nsIXPConnectJSObjectHolder */
66 readonly attribute nsISupports Native;
67 readonly attribute JSObjectPtr JSObjectPrototype;
69 /**
70 * These are here as an aid to nsIXPCScriptable implementors
71 */
73 nsIInterfaceInfo FindInterfaceWithMember(in JSHandleId nameID);
74 nsIInterfaceInfo FindInterfaceWithName(in JSHandleId nameID);
75 [notxpcom] bool HasNativeMember(in JSHandleId name);
77 void debugDump(in short depth);
79 /*
80 * This finishes initializing a wrapped global, doing the parts that we
81 * couldn't do while the global and window were being simultaneously
82 * bootstrapped. This should be called exactly once, and only for wrapped
83 * globals.
84 */
85 void finishInitForWrappedGlobal();
87 /*
88 * NOTE: Add new IDL methods _before_ the C++ block below if you
89 * add them. Otherwise the vtable won't be what xpidl thinks it
90 * is, since GetObjectPrincipal() is virtual.
91 */
93 %{C++
94 /**
95 * Faster access to the native object from C++. Will never return null.
96 */
97 nsISupports* Native() const { return mIdentity; }
99 protected:
100 nsISupports *mIdentity;
101 public:
102 %}
103 };
105 %{C++
106 #include "nsCOMPtr.h"
108 inline
109 const nsQueryInterface
110 do_QueryWrappedNative(nsIXPConnectWrappedNative *aWrappedNative)
111 {
112 return nsQueryInterface(aWrappedNative->Native());
113 }
115 inline
116 const nsQueryInterfaceWithError
117 do_QueryWrappedNative(nsIXPConnectWrappedNative *aWrappedNative,
118 nsresult *aError)
120 {
121 return nsQueryInterfaceWithError(aWrappedNative->Native(), aError);
122 }
124 %}
126 [uuid(BED52030-BCA6-11d2-BA79-00805F8A5DD7)]
127 interface nsIXPConnectWrappedJS : nsIXPConnectJSObjectHolder
128 {
129 /* attribute 'JSObject' inherited from nsIXPConnectJSObjectHolder */
130 readonly attribute nsIInterfaceInfo InterfaceInfo;
131 readonly attribute nsIIDPtr InterfaceIID;
133 void debugDump(in short depth);
135 void aggregatedQueryInterface(in nsIIDRef uuid,
136 [iid_is(uuid),retval] out nsQIResult result);
138 };
140 /***************************************************************************/
142 /**
143 * This is a sort of a placeholder interface. It is not intended to be
144 * implemented. It exists to give the nsIXPCSecurityManager an iid on
145 * which to gate a specific activity in XPConnect.
146 *
147 * That activity is...
148 *
149 * When JavaScript code uses a component that is itself implemented in
150 * JavaScript then XPConnect will build a wrapper rather than directly
151 * expose the JSObject of the component. This allows components implemented
152 * in JavaScript to 'look' just like any other xpcom component (from the
153 * perspective of the JavaScript caller). This insulates the component from
154 * the caller and hides any properties or methods that are not part of the
155 * interface as declared in xpidl. Usually this is a good thing.
156 *
157 * However, in some cases it is useful to allow the JS caller access to the
158 * JS component's underlying implementation. In order to facilitate this
159 * XPConnect supports the 'wrappedJSObject' property. The caller code can do:
160 *
161 * // 'foo' is some xpcom component (that might be implemented in JS).
162 * try {
163 * var bar = foo.wrappedJSObject;
164 * if(bar) {
165 * // bar is the underlying JSObject. Do stuff with it here.
166 * }
167 * } catch(e) {
168 * // security exception?
169 * }
170 *
171 * Recall that 'foo' above is an XPConnect wrapper, not the underlying JS
172 * object. The property get "foo.wrappedJSObject" will only succeed if three
173 * conditions are met:
174 *
175 * 1) 'foo' really is an XPConnect wrapper around a JSObject.
176 * 2) The underlying JSObject actually implements a "wrappedJSObject"
177 * property that returns a JSObject. This is called by XPConnect. This
178 * restriction allows wrapped objects to only allow access to the underlying
179 * JSObject if they choose to do so. Ususally this just means that 'foo'
180 * would have a property tht looks like:
181 * this.wrappedJSObject = this.
182 * 3) The implemementation of nsIXPCSecurityManager (if installed) allows
183 * a property get on the interface below. Although the JSObject need not
184 * implement 'nsIXPCWrappedJSObjectGetter', XPConnect will ask the
185 * security manager if it is OK for the caller to access the only method
186 * in nsIXPCWrappedJSObjectGetter before allowing the activity. This fits
187 * in with the security manager paradigm and makes control over accessing
188 * the property on this interface the control factor for getting the
189 * underlying wrapped JSObject of a JS component from JS code.
190 *
191 * Notes:
192 *
193 * a) If 'foo' above were the underlying JSObject and not a wrapper at all,
194 * then this all just works and XPConnect is not part of the picture at all.
195 * b) One might ask why 'foo' should not just implement an interface through
196 * which callers might get at the underlying object. There are three reasons:
197 * i) XPConnect would still have to do magic since JSObject is not a
198 * scriptable type.
199 * ii) JS Components might use aggregation (like C++ objects) and have
200 * different JSObjects for different interfaces 'within' an aggregate
201 * object. But, using an additional interface only allows returning one
202 * underlying JSObject. However, this allows for the possibility that
203 * each of the aggregte JSObjects could return something different.
204 * Note that one might do: this.wrappedJSObject = someOtherObject;
205 * iii) Avoiding the explicit interface makes it easier for both the caller
206 * and the component.
207 *
208 * Anyway, some future implementation of nsIXPCSecurityManager might want
209 * do special processing on 'nsIXPCSecurityManager::CanGetProperty' when
210 * the interface id is that of nsIXPCWrappedJSObjectGetter.
211 */
213 [scriptable, uuid(254bb2e0-6439-11d4-8fe0-0010a4e73d9a)]
214 interface nsIXPCWrappedJSObjectGetter : nsISupports
215 {
216 readonly attribute nsISupports neverCalled;
217 };
219 /***************************************************************************/
221 /*
222 * This interface is implemented by outside code and registered with xpconnect
223 * via nsIXPConnect::setFunctionThisTranslator.
224 *
225 * The reason this exists is to support calls to JavaScript event callbacks
226 * needed by the DOM via xpconnect from C++ code.
227 *
228 * We've added support for wrapping JS function objects as xpcom interfaces
229 * by declaring the given interface as a [function] interface. However, to
230 * support the requirements of JS event callbacks we need to call the JS
231 * function with the 'this' set as the JSObject for which the event is being
232 * fired; e.g. a form node.
233 *
234 * We've decided that for all cases we care about the appropriate 'this' object
235 * can be derived from the first param in the call to the callback. In the
236 * event handler case the first param is an event object.
237 *
238 * Though we can't change all the JS code so that it would setup its own 'this',
239 * we can add plugin 'helper' support to xpconnect. And that is what we have
240 * here.
241 *
242 * The idea is that at startup time some code that cares about this issue
243 * (e.g. the DOM helper code) can register a nsIXPCFunctionThisTranslator
244 * object with xpconnect to handle calls to [function] interfaces of a given
245 * iid. When xpconnect goes to invoke a method on a wrapped JSObject for
246 * an interface marked as [function], xpconnect will check if the first param
247 * of the method is an xpcom object pointer and if so it will check to see if a
248 * nsIXPCFunctionThisTranslator has been registered for the given iid of the
249 * interface being called. If so it will call the translator and get an
250 * interface pointer to use as the 'this' for the call. If the translator
251 * returns a non-null interface pointer (which it should then have addref'd
252 * since it is being returned as an out param), xpconnect will attempt to build
253 * a wrapper around the pointer and get a JSObject from that wrapper to use
254 * as the 'this' for the call.
255 *
256 * If a null interface pointer is returned then xpconnect will use the default
257 * 'this' - the same JSObject as the function object it is calling.
258 */
260 [uuid(f5f84b70-92eb-41f1-a1dd-2eaac0ed564c)]
261 interface nsIXPCFunctionThisTranslator : nsISupports
262 {
263 nsISupports TranslateThis(in nsISupports aInitialThis);
264 };
266 /***************************************************************************/
269 %{ C++
270 // For use with the service manager
271 // {CB6593E0-F9B2-11d2-BDD6-000064657374}
272 #define NS_XPCONNECT_CID \
273 { 0xcb6593e0, 0xf9b2, 0x11d2, \
274 { 0xbd, 0xd6, 0x0, 0x0, 0x64, 0x65, 0x73, 0x74 } }
275 %}
277 [noscript, uuid(3d5a6320-8764-11e3-baa7-0800200c9a66)]
278 interface nsIXPConnect : nsISupports
279 {
280 %{ C++
281 NS_DEFINE_STATIC_CID_ACCESSOR(NS_XPCONNECT_CID)
282 %}
284 /**
285 * Initializes classes on a global object that has already been created.
286 */
287 void
288 initClasses(in JSContextPtr aJSContext,
289 in JSObjectPtr aGlobalJSObj);
291 /**
292 * Creates a new global object using the given aCOMObj as the global
293 * object. The object will be set up according to the flags (defined
294 * below). If you do not pass INIT_JS_STANDARD_CLASSES, then aCOMObj
295 * must implement nsIXPCScriptable so it can resolve the standard
296 * classes when asked by the JS engine.
297 *
298 * @param aJSContext the context to use while creating the global object.
299 * @param aCOMObj the native object that represents the global object.
300 * @param aPrincipal the principal of the code that will run in this
301 * compartment. Can be null if not on the main thread.
302 * @param aFlags one of the flags below specifying what options this
303 * global object wants.
304 * @param aOptions JSAPI-specific options for the new compartment.
305 */
306 nsIXPConnectJSObjectHolder
307 initClassesWithNewWrappedGlobal(
308 in JSContextPtr aJSContext,
309 in nsISupports aCOMObj,
310 in nsIPrincipal aPrincipal,
311 in uint32_t aFlags,
312 in JSCompartmentOptions aOptions);
314 const uint32_t INIT_JS_STANDARD_CLASSES = 1 << 0;
315 const uint32_t DONT_FIRE_ONNEWGLOBALHOOK = 1 << 1;
316 const uint32_t OMIT_COMPONENTS_OBJECT = 1 << 2;
318 /**
319 * wrapNative will create a new JSObject or return an existing one.
320 *
321 * The JSObject is returned inside a refcounted nsIXPConnectJSObjectHolder.
322 * As long as this holder is held the JSObject will be protected from
323 * collection by JavaScript's garbage collector. It is a good idea to
324 * transfer the JSObject to some equally protected place before releasing
325 * the holder (i.e. use JS_SetProperty to make this object a property of
326 * some other JSObject).
327 *
328 * This method now correctly deals with cases where the passed in xpcom
329 * object already has an associated JSObject for the cases:
330 * 1) The xpcom object has already been wrapped for use in the same scope
331 * as an nsIXPConnectWrappedNative.
332 * 2) The xpcom object is in fact a nsIXPConnectWrappedJS and thus already
333 * has an underlying JSObject.
334 *
335 * It *might* be possible to QueryInterface the nsIXPConnectJSObjectHolder
336 * returned by the method into a nsIXPConnectWrappedNative or a
337 * nsIXPConnectWrappedJS.
338 *
339 * This method will never wrap the JSObject involved in an
340 * XPCNativeWrapper before returning.
341 *
342 * Returns:
343 * success:
344 * NS_OK
345 * failure:
346 * NS_ERROR_XPC_BAD_CONVERT_NATIVE
347 * NS_ERROR_XPC_CANT_GET_JSOBJECT_OF_DOM_OBJECT
348 * NS_ERROR_FAILURE
349 */
350 nsIXPConnectJSObjectHolder
351 wrapNative(in JSContextPtr aJSContext,
352 in JSObjectPtr aScope,
353 in nsISupports aCOMObj,
354 in nsIIDRef aIID);
356 /**
357 * Same as wrapNative, but it returns the JSObject in aVal. C++ callers
358 * must ensure that aVal is rooted.
359 * aIID may be null, it means the same as passing in
360 * &NS_GET_IID(nsISupports) but when passing in null certain shortcuts
361 * can be taken because we know without comparing IIDs that the caller is
362 * asking for an nsISupports wrapper.
363 * If aAllowWrapper, then the returned value will be wrapped in the proper
364 * type of security wrapper on top of the XPCWrappedNative (if needed).
365 * This method doesn't push aJSContext on the context stack, so the caller
366 * is required to push it if the top of the context stack is not equal to
367 * aJSContext.
368 */
369 void
370 wrapNativeToJSVal(in JSContextPtr aJSContext,
371 in JSObjectPtr aScope,
372 in nsISupports aCOMObj,
373 in nsWrapperCachePtr aCache,
374 in nsIIDPtr aIID,
375 in boolean aAllowWrapper,
376 out jsval aVal);
378 /**
379 * wrapJS will yield a new or previously existing xpcom interface pointer
380 * to represent the JSObject passed in.
381 *
382 * This method now correctly deals with cases where the passed in JSObject
383 * already has an associated xpcom interface for the cases:
384 * 1) The JSObject has already been wrapped as a nsIXPConnectWrappedJS.
385 * 2) The JSObject is in fact a nsIXPConnectWrappedNative and thus already
386 * has an underlying xpcom object.
387 * 3) The JSObject is of a jsclass which supports getting the nsISupports
388 * from the JSObject directly. This is used for idlc style objects
389 * (e.g. DOM objects).
390 *
391 * It *might* be possible to QueryInterface the resulting interface pointer
392 * to nsIXPConnectWrappedJS.
393 *
394 * Returns:
395 * success:
396 * NS_OK
397 * failure:
398 * NS_ERROR_XPC_BAD_CONVERT_JS
399 * NS_ERROR_FAILURE
400 */
401 void
402 wrapJS(in JSContextPtr aJSContext,
403 in JSObjectPtr aJSObj,
404 in nsIIDRef aIID,
405 [iid_is(aIID),retval] out nsQIResult result);
407 /**
408 * Wraps the given jsval in a nsIVariant and returns the new variant.
409 */
410 nsIVariant
411 jSValToVariant(in JSContextPtr cx, in jsval aJSVal);
413 /**
414 * This only succeeds if the JSObject is a nsIXPConnectWrappedNative.
415 * A new wrapper is *never* constructed.
416 */
417 nsIXPConnectWrappedNative
418 getWrappedNativeOfJSObject(in JSContextPtr aJSContext,
419 in JSObjectPtr aJSObj);
421 [noscript, notxpcom] nsISupports
422 getNativeOfWrapper(in JSContextPtr aJSContext,
423 in JSObjectPtr aJSObj);
425 /**
426 * The security manager to use when the current JSContext has no security
427 * manager.
428 */
429 void setDefaultSecurityManager(in nsIXPCSecurityManager aManager);
431 nsIStackFrame
432 createStackFrameLocation(in uint32_t aLanguage,
433 in string aFilename,
434 in string aFunctionName,
435 in int32_t aLineNumber,
436 in nsIStackFrame aCaller);
439 [noscript,notxpcom,nostdcall] JSContextPtr getCurrentJSContext();
440 [noscript,notxpcom,nostdcall] JSContextPtr initSafeJSContext();
441 [noscript,notxpcom,nostdcall] JSContextPtr getSafeJSContext();
443 readonly attribute nsIStackFrame CurrentJSStack;
444 readonly attribute nsAXPCNativeCallContextPtr CurrentNativeCallContext;
446 void debugDump(in short depth);
447 void debugDumpObject(in nsISupports aCOMObj, in short depth);
448 void debugDumpJSStack(in boolean showArgs,
449 in boolean showLocals,
450 in boolean showThisProps);
451 void debugDumpEvalInJSStackFrame(in uint32_t aFrameNumber,
452 in string aSourceText);
454 /**
455 * wrapJSAggregatedToNative is just like wrapJS except it is used in cases
456 * where the JSObject is also aggregated to some native xpcom Object.
457 * At present XBL is the only system that might want to do this.
458 *
459 * XXX write more!
460 *
461 * Returns:
462 * success:
463 * NS_OK
464 * failure:
465 * NS_ERROR_XPC_BAD_CONVERT_JS
466 * NS_ERROR_FAILURE
467 */
468 void
469 wrapJSAggregatedToNative(in nsISupports aOuter,
470 in JSContextPtr aJSContext,
471 in JSObjectPtr aJSObj,
472 in nsIIDRef aIID,
473 [iid_is(aIID),retval] out nsQIResult result);
475 // Methods added since mozilla 0.6....
477 /**
478 * This only succeeds if the native object is already wrapped by xpconnect.
479 * A new wrapper is *never* constructed.
480 */
481 nsIXPConnectWrappedNative
482 getWrappedNativeOfNativeObject(in JSContextPtr aJSContext,
483 in JSObjectPtr aScope,
484 in nsISupports aCOMObj,
485 in nsIIDRef aIID);
487 void
488 setFunctionThisTranslator(in nsIIDRef aIID,
489 in nsIXPCFunctionThisTranslator aTranslator);
491 void
492 reparentWrappedNativeIfFound(in JSContextPtr aJSContext,
493 in JSObjectPtr aScope,
494 in JSObjectPtr aNewParent,
495 in nsISupports aCOMObj);
496 void
497 rescueOrphansInScope(in JSContextPtr aJSContext, in JSObjectPtr aScope);
499 nsIXPConnectJSObjectHolder
500 getWrappedNativePrototype(in JSContextPtr aJSContext,
501 in JSObjectPtr aScope,
502 in nsIClassInfo aClassInfo);
504 jsval variantToJS(in JSContextPtr ctx, in JSObjectPtr scope, in nsIVariant value);
505 nsIVariant JSToVariant(in JSContextPtr ctx, in jsval value);
507 /**
508 * Create a sandbox for evaluating code in isolation using
509 * evalInSandboxObject().
510 *
511 * @param cx A context to use when creating the sandbox object.
512 * @param principal The principal (or NULL to use the null principal)
513 * to use when evaluating code in this sandbox.
514 */
515 [noscript] nsIXPConnectJSObjectHolder createSandbox(in JSContextPtr cx,
516 in nsIPrincipal principal);
518 /**
519 * Evaluate script in a sandbox, completely isolated from all
520 * other running scripts.
521 *
522 * @param source The source of the script to evaluate.
523 * @param filename The filename of the script. May be null.
524 * @param cx The context to use when setting up the evaluation of
525 * the script. The actual evaluation will happen on a new
526 * temporary context.
527 * @param sandbox The sandbox object to evaluate the script in.
528 * @param returnStringOnly The only results to come out of the
529 * computation (including exceptions) will
530 * be coerced into strings created in the
531 * sandbox.
532 * @return The result of the evaluation as a jsval. If the caller
533 * intends to use the return value from this call the caller
534 * is responsible for rooting the jsval before making a call
535 * to this method.
536 */
537 [noscript] jsval evalInSandboxObject(in AString source, in string filename,
538 in JSContextPtr cx,
539 in JSObjectPtr sandbox,
540 in boolean returnStringOnly);
542 /**
543 * Whether or not XPConnect should report all JS exceptions when returning
544 * from JS into C++. False by default, although any value set in the
545 * MOZ_REPORT_ALL_JS_EXCEPTIONS environment variable will override the value
546 * passed here.
547 */
548 void setReportAllJSExceptions(in boolean reportAllJSExceptions);
550 /**
551 * Trigger a JS garbage collection.
552 * Use a js::gcreason::Reason from jsfriendapi.h for the kind.
553 */
554 void GarbageCollect(in uint32_t reason);
556 /**
557 * Signals a good place to do an incremental GC slice, because the
558 * browser is drawing a frame.
559 */
560 void NotifyDidPaint();
562 %{C++
563 /**
564 * Get the object principal for this wrapper. Note that this may well end
565 * up being null; in that case one should seek principals elsewhere. Null
566 * here does NOT indicate system principal or no principals at all, just
567 * that this wrapper doesn't have an intrinsic one.
568 */
569 virtual nsIPrincipal* GetPrincipal(JSObject* obj,
570 bool allowShortCircuit) const = 0;
571 virtual char* DebugPrintJSStack(bool showArgs,
572 bool showLocals,
573 bool showThisProps) = 0;
574 %}
576 /**
577 * Creates a JS object holder around aObject that will hold the object
578 * alive for as long as the holder stays alive.
579 */
580 nsIXPConnectJSObjectHolder holdObject(in JSContextPtr aJSContext,
581 in JSObjectPtr aObject);
583 /**
584 * When we place the browser in JS debug mode, there can't be any
585 * JS on the stack. This is because we currently activate debugMode
586 * on all scripts in the JSRuntime when the debugger is activated.
587 * This method will turn debug mode on or off when the context
588 * stack reaches zero length.
589 */
590 [noscript] void setDebugModeWhenPossible(in boolean mode,
591 in boolean allowSyncDisable);
593 [noscript] void writeScript(in nsIObjectOutputStream aStream,
594 in JSContextPtr aJSContext,
595 in JSScriptPtr aJSScript);
597 [noscript] JSScriptPtr readScript(in nsIObjectInputStream aStream,
598 in JSContextPtr aJSContext);
600 [noscript] void writeFunction(in nsIObjectOutputStream aStream,
601 in JSContextPtr aJSContext,
602 in JSObjectPtr aJSObject);
604 [noscript] JSObjectPtr readFunction(in nsIObjectInputStream aStream,
605 in JSContextPtr aJSContext);
607 /**
608 * This function should be called in JavaScript error reporters
609 * to signal that they are ignoring the error. In this case,
610 * XPConnect can print a warning to the console.
611 */
612 [noscript] void markErrorUnreported(in JSContextPtr aJSContext);
613 };
