michael@0: /* -*- Mode: IDL; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
michael@0:  *
michael@0:  * This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: /* The core XPConnect public interfaces. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: %{ C++
michael@0: #include "jspubtd.h"
michael@0: #include "js/TypeDecls.h"
michael@0: 
michael@0: struct JSFreeOp;
michael@0: 
michael@0: class nsWrapperCache;
michael@0: class nsAXPCNativeCallContext;
michael@0: %}
michael@0: 
michael@0: /***************************************************************************/
michael@0: 
michael@0: // NB: jsval and jsid are declared in nsrootidl.idl
michael@0: 
michael@0: [ptr] native JSContextPtr(JSContext);
michael@0: [ptr] native JSClassPtr(JSClass);
michael@0: [ptr] native JSFreeOpPtr(JSFreeOp);
michael@0: [ptr] native JSObjectPtr(JSObject);
michael@0: [ptr] native JSValConstPtr(const JS::Value);
michael@0:       native JSPropertyOp(JSPropertyOp);
michael@0:       native JSEqualityOp(JSEqualityOp);
michael@0: [ptr] native JSScriptPtr(JSScript);
michael@0: [ptr] native voidPtrPtr(void*);
michael@0: [ptr] native nsAXPCNativeCallContextPtr(nsAXPCNativeCallContext);
michael@0: [ptr] native nsWrapperCachePtr(nsWrapperCache);
michael@0: [ref] native JSCompartmentOptions(JS::CompartmentOptions);
michael@0: [ref] native JSCallArgsRef(const JS::CallArgs);
michael@0:       native JSHandleId(JS::Handle<jsid>);
michael@0: 
michael@0: /***************************************************************************/
michael@0: 
michael@0: // forward declarations...
michael@0: interface nsIXPCScriptable;
michael@0: interface nsIXPConnect;
michael@0: interface nsIXPConnectWrappedNative;
michael@0: interface nsIInterfaceInfo;
michael@0: interface nsIXPCSecurityManager;
michael@0: interface nsIPrincipal;
michael@0: interface nsIClassInfo;
michael@0: interface nsIVariant;
michael@0: interface nsIStackFrame;
michael@0: interface nsIObjectInputStream;
michael@0: interface nsIObjectOutputStream;
michael@0: 
michael@0: /***************************************************************************/
michael@0: [uuid(909e8641-7c54-4dff-9b94-ba631f057b33)]
michael@0: interface nsIXPConnectJSObjectHolder : nsISupports
michael@0: {
michael@0:     [notxpcom, nostdcall] JSObjectPtr GetJSObject();
michael@0: };
michael@0: 
michael@0: [uuid(675b01ba-397b-472a-9b80-5716376a2ec6)]
michael@0: interface nsIXPConnectWrappedNative : nsIXPConnectJSObjectHolder
michael@0: {
michael@0:     /* attribute 'JSObject' inherited from nsIXPConnectJSObjectHolder */
michael@0:     readonly attribute nsISupports      Native;
michael@0:     readonly attribute JSObjectPtr      JSObjectPrototype;
michael@0: 
michael@0:     /**
michael@0:      * These are here as an aid to nsIXPCScriptable implementors
michael@0:      */
michael@0: 
michael@0:     nsIInterfaceInfo FindInterfaceWithMember(in JSHandleId nameID);
michael@0:     nsIInterfaceInfo FindInterfaceWithName(in JSHandleId nameID);
michael@0:     [notxpcom] bool HasNativeMember(in JSHandleId name);
michael@0: 
michael@0:     void debugDump(in short depth);
michael@0: 
michael@0:     /*
michael@0:      * This finishes initializing a wrapped global, doing the parts that we
michael@0:      * couldn't do while the global and window were being simultaneously
michael@0:      * bootstrapped. This should be called exactly once, and only for wrapped
michael@0:      * globals.
michael@0:      */
michael@0:     void finishInitForWrappedGlobal();
michael@0: 
michael@0:     /*
michael@0:      * NOTE: Add new IDL methods _before_ the C++ block below if you
michael@0:      * add them.  Otherwise the vtable won't be what xpidl thinks it
michael@0:      * is, since GetObjectPrincipal() is virtual.
michael@0:      */
michael@0: 
michael@0: %{C++
michael@0:     /**
michael@0:      * Faster access to the native object from C++.  Will never return null.
michael@0:      */
michael@0:     nsISupports* Native() const { return mIdentity; }
michael@0: 
michael@0: protected:
michael@0:     nsISupports *mIdentity;
michael@0: public:
michael@0: %}
michael@0: };
michael@0: 
michael@0: %{C++
michael@0: #include "nsCOMPtr.h"
michael@0: 
michael@0: inline
michael@0: const nsQueryInterface
michael@0: do_QueryWrappedNative(nsIXPConnectWrappedNative *aWrappedNative)
michael@0: {
michael@0:     return nsQueryInterface(aWrappedNative->Native());
michael@0: }
michael@0: 
michael@0: inline
michael@0: const nsQueryInterfaceWithError
michael@0: do_QueryWrappedNative(nsIXPConnectWrappedNative *aWrappedNative,
michael@0:                       nsresult *aError)
michael@0: 
michael@0: {
michael@0:     return nsQueryInterfaceWithError(aWrappedNative->Native(), aError);
michael@0: }
michael@0: 
michael@0: %}
michael@0: 
michael@0: [uuid(BED52030-BCA6-11d2-BA79-00805F8A5DD7)]
michael@0: interface nsIXPConnectWrappedJS : nsIXPConnectJSObjectHolder
michael@0: {
michael@0:     /* attribute 'JSObject' inherited from nsIXPConnectJSObjectHolder */
michael@0:     readonly attribute nsIInterfaceInfo InterfaceInfo;
michael@0:     readonly attribute nsIIDPtr         InterfaceIID;
michael@0: 
michael@0:     void debugDump(in short depth);
michael@0: 
michael@0:     void aggregatedQueryInterface(in nsIIDRef uuid,
michael@0:                                   [iid_is(uuid),retval] out nsQIResult result);
michael@0: 
michael@0: };
michael@0: 
michael@0: /***************************************************************************/
michael@0: 
michael@0: /**
michael@0:  * This is a sort of a placeholder interface. It is not intended to be
michael@0:  * implemented. It exists to give the nsIXPCSecurityManager an iid on
michael@0:  * which to gate a specific activity in XPConnect.
michael@0:  *
michael@0:  * That activity is...
michael@0:  *
michael@0:  * When JavaScript code uses a component that is itself implemented in
michael@0:  * JavaScript then XPConnect will build a wrapper rather than directly
michael@0:  * expose the JSObject of the component. This allows components implemented
michael@0:  * in JavaScript to 'look' just like any other xpcom component (from the
michael@0:  * perspective of the JavaScript caller). This insulates the component from
michael@0:  * the caller and hides any properties or methods that are not part of the
michael@0:  * interface as declared in xpidl. Usually this is a good thing.
michael@0:  *
michael@0:  * However, in some cases it is useful to allow the JS caller access to the
michael@0:  * JS component's underlying implementation. In order to facilitate this
michael@0:  * XPConnect supports the 'wrappedJSObject' property. The caller code can do:
michael@0:  *
michael@0:  * // 'foo' is some xpcom component (that might be implemented in JS).
michael@0:  * try {
michael@0:  *   var bar = foo.wrappedJSObject;
michael@0:  *   if(bar) {
michael@0:  *      // bar is the underlying JSObject. Do stuff with it here.
michael@0:  *   }
michael@0:  * } catch(e) {
michael@0:  *   // security exception?
michael@0:  * }
michael@0:  *
michael@0:  * Recall that 'foo' above is an XPConnect wrapper, not the underlying JS
michael@0:  * object. The property get "foo.wrappedJSObject" will only succeed if three
michael@0:  * conditions are met:
michael@0:  *
michael@0:  * 1) 'foo' really is an XPConnect wrapper around a JSObject.
michael@0:  * 2) The underlying JSObject actually implements a "wrappedJSObject"
michael@0:  *    property that returns a JSObject. This is called by XPConnect. This
michael@0:  *    restriction allows wrapped objects to only allow access to the underlying
michael@0:  *    JSObject if they choose to do so. Ususally this just means that 'foo'
michael@0:  *    would have a property tht looks like:
michael@0:  *       this.wrappedJSObject = this.
michael@0:  * 3) The implemementation of nsIXPCSecurityManager (if installed) allows
michael@0:  *    a property get on the interface below. Although the JSObject need not
michael@0:  *    implement 'nsIXPCWrappedJSObjectGetter', XPConnect will ask the
michael@0:  *    security manager if it is OK for the caller to access the only method
michael@0:  *    in nsIXPCWrappedJSObjectGetter before allowing the activity. This fits
michael@0:  *    in with the security manager paradigm and makes control over accessing
michael@0:  *    the property on this interface the control factor for getting the
michael@0:  *    underlying wrapped JSObject of a JS component from JS code.
michael@0:  *
michael@0:  * Notes:
michael@0:  *
michael@0:  * a) If 'foo' above were the underlying JSObject and not a wrapper at all,
michael@0:  *    then this all just works and XPConnect is not part of the picture at all.
michael@0:  * b) One might ask why 'foo' should not just implement an interface through
michael@0:  *    which callers might get at the underlying object. There are three reasons:
michael@0:  *   i)   XPConnect would still have to do magic since JSObject is not a
michael@0:  *        scriptable type.
michael@0:  *   ii)  JS Components might use aggregation (like C++ objects) and have
michael@0:  *        different JSObjects for different interfaces 'within' an aggregate
michael@0:  *        object. But, using an additional interface only allows returning one
michael@0:  *        underlying JSObject. However, this allows for the possibility that
michael@0:  *        each of the aggregte JSObjects could return something different.
michael@0:  *        Note that one might do: this.wrappedJSObject = someOtherObject;
michael@0:  *   iii) Avoiding the explicit interface makes it easier for both the caller
michael@0:  *        and the component.
michael@0:  *
michael@0:  *  Anyway, some future implementation of nsIXPCSecurityManager might want
michael@0:  *  do special processing on 'nsIXPCSecurityManager::CanGetProperty' when
michael@0:  *  the interface id is that of nsIXPCWrappedJSObjectGetter.
michael@0:  */
michael@0: 
michael@0: [scriptable, uuid(254bb2e0-6439-11d4-8fe0-0010a4e73d9a)]
michael@0: interface nsIXPCWrappedJSObjectGetter : nsISupports
michael@0: {
michael@0:     readonly attribute nsISupports neverCalled;
michael@0: };
michael@0: 
michael@0: /***************************************************************************/
michael@0: 
michael@0: /*
michael@0:  * This interface is implemented by outside code and registered with xpconnect
michael@0:  * via nsIXPConnect::setFunctionThisTranslator.
michael@0:  *
michael@0:  * The reason this exists is to support calls to JavaScript event callbacks
michael@0:  * needed by the DOM via xpconnect from C++ code.
michael@0:  *
michael@0:  * We've added support for wrapping JS function objects as xpcom interfaces
michael@0:  * by declaring the given interface as a [function] interface. However, to
michael@0:  * support the requirements of JS event callbacks we need to call the JS
michael@0:  * function with the 'this' set as the JSObject for which the event is being
michael@0:  * fired; e.g. a form node.
michael@0:  *
michael@0:  * We've decided that for all cases we care about the appropriate 'this' object
michael@0:  * can be derived from the first param in the call to the callback. In the
michael@0:  * event handler case the first param is an event object.
michael@0:  *
michael@0:  * Though we can't change all the JS code so that it would setup its own 'this',
michael@0:  * we can add plugin 'helper' support to xpconnect. And that is what we have
michael@0:  * here.
michael@0:  *
michael@0:  * The idea is that at startup time some code that cares about this issue
michael@0:  * (e.g. the DOM helper code) can register a nsIXPCFunctionThisTranslator
michael@0:  * object with xpconnect to handle calls to [function] interfaces of a given
michael@0:  * iid. When xpconnect goes to invoke a method on a wrapped JSObject for
michael@0:  * an interface marked as [function], xpconnect will check if the first param
michael@0:  * of the method is an xpcom object pointer and if so it will check to see if a
michael@0:  * nsIXPCFunctionThisTranslator has been registered for the given iid of the
michael@0:  * interface being called. If so it will call the translator and get an
michael@0:  * interface pointer to use as the 'this' for the call. If the translator
michael@0:  * returns a non-null interface pointer (which it should then have addref'd
michael@0:  * since it is being returned as an out param), xpconnect will attempt to build
michael@0:  * a wrapper around the pointer and get a JSObject from that wrapper to use
michael@0:  * as the 'this' for the call.
michael@0:  *
michael@0:  * If a null interface pointer is returned then xpconnect will use the default
michael@0:  * 'this' - the same JSObject as the function object it is calling.
michael@0:  */
michael@0: 
michael@0: [uuid(f5f84b70-92eb-41f1-a1dd-2eaac0ed564c)]
michael@0: interface nsIXPCFunctionThisTranslator : nsISupports
michael@0: {
michael@0:     nsISupports TranslateThis(in nsISupports aInitialThis);
michael@0: };
michael@0: 
michael@0: /***************************************************************************/
michael@0: 
michael@0: 
michael@0: %{ C++
michael@0: // For use with the service manager
michael@0: // {CB6593E0-F9B2-11d2-BDD6-000064657374}
michael@0: #define NS_XPCONNECT_CID \
michael@0: { 0xcb6593e0, 0xf9b2, 0x11d2, \
michael@0:     { 0xbd, 0xd6, 0x0, 0x0, 0x64, 0x65, 0x73, 0x74 } }
michael@0: %}
michael@0: 
michael@0: [noscript, uuid(3d5a6320-8764-11e3-baa7-0800200c9a66)]
michael@0: interface nsIXPConnect : nsISupports
michael@0: {
michael@0: %{ C++
michael@0:   NS_DEFINE_STATIC_CID_ACCESSOR(NS_XPCONNECT_CID)
michael@0: %}
michael@0: 
michael@0:     /**
michael@0:      * Initializes classes on a global object that has already been created.
michael@0:      */
michael@0:     void
michael@0:     initClasses(in JSContextPtr aJSContext,
michael@0:                 in JSObjectPtr  aGlobalJSObj);
michael@0: 
michael@0:     /**
michael@0:      * Creates a new global object using the given aCOMObj as the global
michael@0:      * object. The object will be set up according to the flags (defined
michael@0:      * below). If you do not pass INIT_JS_STANDARD_CLASSES, then aCOMObj
michael@0:      * must implement nsIXPCScriptable so it can resolve the standard
michael@0:      * classes when asked by the JS engine.
michael@0:      *
michael@0:      * @param aJSContext the context to use while creating the global object.
michael@0:      * @param aCOMObj the native object that represents the global object.
michael@0:      * @param aPrincipal the principal of the code that will run in this
michael@0:      *                   compartment. Can be null if not on the main thread.
michael@0:      * @param aFlags one of the flags below specifying what options this
michael@0:      *               global object wants.
michael@0:      * @param aOptions JSAPI-specific options for the new compartment.
michael@0:      */
michael@0:     nsIXPConnectJSObjectHolder
michael@0:     initClassesWithNewWrappedGlobal(
michael@0:                   in JSContextPtr         aJSContext,
michael@0:                   in nsISupports          aCOMObj,
michael@0:                   in nsIPrincipal         aPrincipal,
michael@0:                   in uint32_t             aFlags,
michael@0:                   in JSCompartmentOptions aOptions);
michael@0: 
michael@0:     const uint32_t INIT_JS_STANDARD_CLASSES  = 1 << 0;
michael@0:     const uint32_t DONT_FIRE_ONNEWGLOBALHOOK = 1 << 1;
michael@0:     const uint32_t OMIT_COMPONENTS_OBJECT    = 1 << 2;
michael@0: 
michael@0:     /**
michael@0:     * wrapNative will create a new JSObject or return an existing one.
michael@0:     *
michael@0:     * The JSObject is returned inside a refcounted nsIXPConnectJSObjectHolder.
michael@0:     * As long as this holder is held the JSObject will be protected from
michael@0:     * collection by JavaScript's garbage collector. It is a good idea to
michael@0:     * transfer the JSObject to some equally protected place before releasing
michael@0:     * the holder (i.e. use JS_SetProperty to make this object a property of
michael@0:     * some other JSObject).
michael@0:     *
michael@0:     * This method now correctly deals with cases where the passed in xpcom
michael@0:     * object already has an associated JSObject for the cases:
michael@0:     *  1) The xpcom object has already been wrapped for use in the same scope
michael@0:     *     as an nsIXPConnectWrappedNative.
michael@0:     *  2) The xpcom object is in fact a nsIXPConnectWrappedJS and thus already
michael@0:     *     has an underlying JSObject.
michael@0:     *
michael@0:     * It *might* be possible to QueryInterface the nsIXPConnectJSObjectHolder
michael@0:     * returned by the method into a nsIXPConnectWrappedNative or a
michael@0:     * nsIXPConnectWrappedJS.
michael@0:     *
michael@0:     * This method will never wrap the JSObject involved in an
michael@0:     * XPCNativeWrapper before returning.
michael@0:     *
michael@0:     * Returns:
michael@0:     *    success:
michael@0:     *       NS_OK
michael@0:     *    failure:
michael@0:     *       NS_ERROR_XPC_BAD_CONVERT_NATIVE
michael@0:     *       NS_ERROR_XPC_CANT_GET_JSOBJECT_OF_DOM_OBJECT
michael@0:     *       NS_ERROR_FAILURE
michael@0:     */
michael@0:     nsIXPConnectJSObjectHolder
michael@0:     wrapNative(in JSContextPtr aJSContext,
michael@0:                in JSObjectPtr  aScope,
michael@0:                in nsISupports  aCOMObj,
michael@0:                in nsIIDRef     aIID);
michael@0: 
michael@0:     /**
michael@0:      * Same as wrapNative, but it returns the JSObject in aVal. C++ callers
michael@0:      * must ensure that aVal is rooted.
michael@0:      * aIID may be null, it means the same as passing in
michael@0:      * &NS_GET_IID(nsISupports) but when passing in null certain shortcuts
michael@0:      * can be taken because we know without comparing IIDs that the caller is
michael@0:      * asking for an nsISupports wrapper.
michael@0:      * If aAllowWrapper, then the returned value will be wrapped in the proper
michael@0:      * type of security wrapper on top of the XPCWrappedNative (if needed).
michael@0:      * This method doesn't push aJSContext on the context stack, so the caller
michael@0:      * is required to push it if the top of the context stack is not equal to
michael@0:      * aJSContext.
michael@0:      */
michael@0:     void
michael@0:     wrapNativeToJSVal(in JSContextPtr aJSContext,
michael@0:                       in JSObjectPtr  aScope,
michael@0:                       in nsISupports  aCOMObj,
michael@0:                       in nsWrapperCachePtr aCache,
michael@0:                       in nsIIDPtr     aIID,
michael@0:                       in boolean      aAllowWrapper,
michael@0:                       out jsval       aVal);
michael@0: 
michael@0:     /**
michael@0:     * wrapJS will yield a new or previously existing xpcom interface pointer
michael@0:     * to represent the JSObject passed in.
michael@0:     *
michael@0:     * This method now correctly deals with cases where the passed in JSObject
michael@0:     * already has an associated xpcom interface for the cases:
michael@0:     *  1) The JSObject has already been wrapped as a nsIXPConnectWrappedJS.
michael@0:     *  2) The JSObject is in fact a nsIXPConnectWrappedNative and thus already
michael@0:     *     has an underlying xpcom object.
michael@0:     *  3) The JSObject is of a jsclass which supports getting the nsISupports
michael@0:     *     from the JSObject directly. This is used for idlc style objects
michael@0:     *     (e.g. DOM objects).
michael@0:     *
michael@0:     * It *might* be possible to QueryInterface the resulting interface pointer
michael@0:     * to nsIXPConnectWrappedJS.
michael@0:     *
michael@0:     * Returns:
michael@0:     *   success:
michael@0:     *     NS_OK
michael@0:     *    failure:
michael@0:     *       NS_ERROR_XPC_BAD_CONVERT_JS
michael@0:     *       NS_ERROR_FAILURE
michael@0:     */
michael@0:     void
michael@0:     wrapJS(in JSContextPtr aJSContext,
michael@0:            in JSObjectPtr  aJSObj,
michael@0:            in nsIIDRef     aIID,
michael@0:            [iid_is(aIID),retval] out nsQIResult result);
michael@0: 
michael@0:     /**
michael@0:      * Wraps the given jsval in a nsIVariant and returns the new variant.
michael@0:      */
michael@0:     nsIVariant
michael@0:     jSValToVariant(in JSContextPtr cx, in jsval aJSVal);
michael@0: 
michael@0:     /**
michael@0:     * This only succeeds if the JSObject is a nsIXPConnectWrappedNative.
michael@0:     * A new wrapper is *never* constructed.
michael@0:     */
michael@0:     nsIXPConnectWrappedNative
michael@0:     getWrappedNativeOfJSObject(in JSContextPtr aJSContext,
michael@0:                                in JSObjectPtr  aJSObj);
michael@0: 
michael@0:     [noscript, notxpcom] nsISupports
michael@0:     getNativeOfWrapper(in JSContextPtr aJSContext,
michael@0:                        in JSObjectPtr  aJSObj);
michael@0: 
michael@0:     /**
michael@0:     * The security manager to use when the current JSContext has no security
michael@0:     * manager.
michael@0:     */
michael@0:     void setDefaultSecurityManager(in nsIXPCSecurityManager aManager);
michael@0: 
michael@0:     nsIStackFrame
michael@0:     createStackFrameLocation(in uint32_t       aLanguage,
michael@0:                              in string         aFilename,
michael@0:                              in string         aFunctionName,
michael@0:                              in int32_t        aLineNumber,
michael@0:                              in nsIStackFrame  aCaller);
michael@0: 
michael@0: 
michael@0:     [noscript,notxpcom,nostdcall] JSContextPtr getCurrentJSContext();
michael@0:     [noscript,notxpcom,nostdcall] JSContextPtr initSafeJSContext();
michael@0:     [noscript,notxpcom,nostdcall] JSContextPtr getSafeJSContext();
michael@0: 
michael@0:     readonly attribute nsIStackFrame                CurrentJSStack;
michael@0:     readonly attribute nsAXPCNativeCallContextPtr   CurrentNativeCallContext;
michael@0: 
michael@0:     void debugDump(in short depth);
michael@0:     void debugDumpObject(in nsISupports aCOMObj, in short depth);
michael@0:     void debugDumpJSStack(in boolean showArgs,
michael@0:                           in boolean showLocals,
michael@0:                           in boolean showThisProps);
michael@0:     void debugDumpEvalInJSStackFrame(in uint32_t aFrameNumber,
michael@0:                                      in string aSourceText);
michael@0: 
michael@0:     /**
michael@0:     * wrapJSAggregatedToNative is just like wrapJS except it is used in cases
michael@0:     * where the JSObject is also aggregated to some native xpcom Object.
michael@0:     * At present XBL is the only system that might want to do this.
michael@0:     *
michael@0:     * XXX write more!
michael@0:     *
michael@0:     * Returns:
michael@0:     *   success:
michael@0:     *     NS_OK
michael@0:     *    failure:
michael@0:     *       NS_ERROR_XPC_BAD_CONVERT_JS
michael@0:     *       NS_ERROR_FAILURE
michael@0:     */
michael@0:     void
michael@0:     wrapJSAggregatedToNative(in nsISupports  aOuter,
michael@0:                              in JSContextPtr aJSContext,
michael@0:                              in JSObjectPtr  aJSObj,
michael@0:                              in nsIIDRef     aIID,
michael@0:                              [iid_is(aIID),retval] out nsQIResult result);
michael@0: 
michael@0:     // Methods added since mozilla 0.6....
michael@0: 
michael@0:     /**
michael@0:     * This only succeeds if the native object is already wrapped by xpconnect.
michael@0:     * A new wrapper is *never* constructed.
michael@0:     */
michael@0:     nsIXPConnectWrappedNative
michael@0:     getWrappedNativeOfNativeObject(in JSContextPtr aJSContext,
michael@0:                                    in JSObjectPtr  aScope,
michael@0:                                    in nsISupports  aCOMObj,
michael@0:                                    in nsIIDRef     aIID);
michael@0: 
michael@0:     void
michael@0:     setFunctionThisTranslator(in nsIIDRef aIID,
michael@0:                               in nsIXPCFunctionThisTranslator aTranslator);
michael@0: 
michael@0:     void
michael@0:     reparentWrappedNativeIfFound(in JSContextPtr aJSContext,
michael@0:                                  in JSObjectPtr  aScope,
michael@0:                                  in JSObjectPtr  aNewParent,
michael@0:                                  in nsISupports  aCOMObj);
michael@0:     void
michael@0:     rescueOrphansInScope(in JSContextPtr aJSContext, in JSObjectPtr  aScope);
michael@0: 
michael@0:     nsIXPConnectJSObjectHolder
michael@0:     getWrappedNativePrototype(in JSContextPtr aJSContext,
michael@0:                               in JSObjectPtr  aScope,
michael@0:                               in nsIClassInfo aClassInfo);
michael@0: 
michael@0:     jsval variantToJS(in JSContextPtr ctx, in JSObjectPtr scope, in nsIVariant value);
michael@0:     nsIVariant JSToVariant(in JSContextPtr ctx, in jsval value);
michael@0: 
michael@0:     /**
michael@0:      * Create a sandbox for evaluating code in isolation using
michael@0:      * evalInSandboxObject().
michael@0:      *
michael@0:      * @param cx A context to use when creating the sandbox object.
michael@0:      * @param principal The principal (or NULL to use the null principal)
michael@0:      *                  to use when evaluating code in this sandbox.
michael@0:      */
michael@0:     [noscript] nsIXPConnectJSObjectHolder createSandbox(in JSContextPtr cx,
michael@0:                                                         in nsIPrincipal principal);
michael@0: 
michael@0:     /**
michael@0:      * Evaluate script in a sandbox, completely isolated from all
michael@0:      * other running scripts.
michael@0:      *
michael@0:      * @param source The source of the script to evaluate.
michael@0:      * @param filename The filename of the script. May be null.
michael@0:      * @param cx The context to use when setting up the evaluation of
michael@0:      *           the script. The actual evaluation will happen on a new
michael@0:      *           temporary context.
michael@0:      * @param sandbox The sandbox object to evaluate the script in.
michael@0:      * @param returnStringOnly The only results to come out of the
michael@0:      *                         computation (including exceptions) will
michael@0:      *                         be coerced into strings created in the
michael@0:      *                         sandbox.
michael@0:      * @return The result of the evaluation as a jsval. If the caller
michael@0:      *         intends to use the return value from this call the caller
michael@0:      *         is responsible for rooting the jsval before making a call
michael@0:      *         to this method.
michael@0:      */
michael@0:     [noscript] jsval evalInSandboxObject(in AString source, in string filename,
michael@0:                                          in JSContextPtr cx,
michael@0:                                          in JSObjectPtr sandbox,
michael@0:                                          in boolean returnStringOnly);
michael@0: 
michael@0:     /**
michael@0:      * Whether or not XPConnect should report all JS exceptions when returning
michael@0:      * from JS into C++. False by default, although any value set in the
michael@0:      * MOZ_REPORT_ALL_JS_EXCEPTIONS environment variable will override the value
michael@0:      * passed here.
michael@0:      */
michael@0:     void setReportAllJSExceptions(in boolean reportAllJSExceptions);
michael@0: 
michael@0:     /**
michael@0:      * Trigger a JS garbage collection.
michael@0:      * Use a js::gcreason::Reason from jsfriendapi.h for the kind.
michael@0:      */
michael@0:     void GarbageCollect(in uint32_t reason);
michael@0: 
michael@0:     /**
michael@0:      * Signals a good place to do an incremental GC slice, because the
michael@0:      * browser is drawing a frame.
michael@0:      */
michael@0:     void NotifyDidPaint();
michael@0: 
michael@0: %{C++
michael@0:     /**
michael@0:      * Get the object principal for this wrapper.  Note that this may well end
michael@0:      * up being null; in that case one should seek principals elsewhere.  Null
michael@0:      * here does NOT indicate system principal or no principals at all, just
michael@0:      * that this wrapper doesn't have an intrinsic one.
michael@0:      */
michael@0:     virtual nsIPrincipal* GetPrincipal(JSObject* obj,
michael@0:                                        bool allowShortCircuit) const = 0;
michael@0:     virtual char* DebugPrintJSStack(bool showArgs,
michael@0:                                     bool showLocals,
michael@0:                                     bool showThisProps) = 0;
michael@0: %}
michael@0: 
michael@0:     /**
michael@0:      * Creates a JS object holder around aObject that will hold the object
michael@0:      * alive for as long as the holder stays alive.
michael@0:      */
michael@0:     nsIXPConnectJSObjectHolder holdObject(in JSContextPtr aJSContext,
michael@0:                                           in JSObjectPtr aObject);
michael@0: 
michael@0:     /**
michael@0:      * When we place the browser in JS debug mode, there can't be any
michael@0:      * JS on the stack. This is because we currently activate debugMode 
michael@0:      * on all scripts in the JSRuntime when the debugger is activated.
michael@0:      * This method will turn debug mode on or off when the context 
michael@0:      * stack reaches zero length.
michael@0:      */
michael@0:     [noscript] void setDebugModeWhenPossible(in boolean mode,
michael@0:                                              in boolean allowSyncDisable);
michael@0: 
michael@0:     [noscript] void writeScript(in nsIObjectOutputStream aStream,
michael@0:                                 in JSContextPtr aJSContext,
michael@0:                                 in JSScriptPtr aJSScript);
michael@0: 
michael@0:     [noscript] JSScriptPtr readScript(in nsIObjectInputStream aStream,
michael@0:                                       in JSContextPtr aJSContext);
michael@0: 
michael@0:     [noscript] void writeFunction(in nsIObjectOutputStream aStream,
michael@0:                                   in JSContextPtr aJSContext,
michael@0:                                   in JSObjectPtr aJSObject);
michael@0: 
michael@0:     [noscript] JSObjectPtr readFunction(in nsIObjectInputStream aStream,
michael@0:                                         in JSContextPtr aJSContext);
michael@0: 
michael@0:     /**
michael@0:      * This function should be called in JavaScript error reporters
michael@0:      * to signal that they are ignoring the error. In this case,
michael@0:      * XPConnect can print a warning to the console.
michael@0:      */
michael@0:     [noscript] void markErrorUnreported(in JSContextPtr aJSContext);
michael@0: };