gecko-dev/js/src/xpconnect/idl/nsIXPConnect.idl

/* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is Mozilla Communicator client code, released
 * March 31, 1998.
 *
 * The Initial Developer of the Original Code is
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 1998
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *   John Bandhauer <jband@netscape.com> (original author)
 *   Nate Nielsen <nielsen@memberwebs.com> 
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either of the GNU General Public License Version 2 or later (the "GPL"),
 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

/* The core XPConnect public interfaces. */

#include "nsISupports.idl"
#include "nsIClassInfo.idl"
#include "xpccomponents.idl"
#include "xpcjsid.idl"
#include "xpcexception.idl"
#include "nsIInterfaceInfo.idl"
#include "nsIInterfaceInfoManager.idl"
#include "nsIExceptionService.idl"
#include "nsIVariant.idl"

%{ C++
#include "jspubtd.h"
#include "xptinfo.h"
%}

/***************************************************************************/

[ptr] native JSContextPtr(JSContext);
[ptr] native JSObjectPtr(JSObject);
[ptr] native JSValPtr(jsval);
      native JSVal(jsval);
[ptr] native JSClassConstPtr(const JSClass);
      native JSGetObjectOps(JSGetObjectOps);
      native JSID(jsid);
[ptr] native voidPtrPtr(void*);
[ptr] native nsScriptObjectTracerPtr(nsScriptObjectTracer);
[ref] native nsCCTraversalCallbackRef(nsCycleCollectionTraversalCallback);

/***************************************************************************/

%{ C++
/***************************************************************************/
#define GENERATE_XPC_FAILURE(x) \
            (NS_ERROR_GENERATE_FAILURE(NS_ERROR_MODULE_XPCONNECT,x))

#define NS_ERROR_XPC_NOT_ENOUGH_ARGS                   GENERATE_XPC_FAILURE( 1)
#define NS_ERROR_XPC_NEED_OUT_OBJECT                   GENERATE_XPC_FAILURE( 2)
#define NS_ERROR_XPC_CANT_SET_OUT_VAL                  GENERATE_XPC_FAILURE( 3)
#define NS_ERROR_XPC_NATIVE_RETURNED_FAILURE           GENERATE_XPC_FAILURE( 4)
#define NS_ERROR_XPC_CANT_GET_INTERFACE_INFO           GENERATE_XPC_FAILURE( 5)
#define NS_ERROR_XPC_CANT_GET_PARAM_IFACE_INFO         GENERATE_XPC_FAILURE( 6)
#define NS_ERROR_XPC_CANT_GET_METHOD_INFO              GENERATE_XPC_FAILURE( 7)
#define NS_ERROR_XPC_UNEXPECTED                        GENERATE_XPC_FAILURE( 8)
#define NS_ERROR_XPC_BAD_CONVERT_JS                    GENERATE_XPC_FAILURE( 9)
#define NS_ERROR_XPC_BAD_CONVERT_NATIVE                GENERATE_XPC_FAILURE(10)
#define NS_ERROR_XPC_BAD_CONVERT_JS_NULL_REF           GENERATE_XPC_FAILURE(11)
#define NS_ERROR_XPC_BAD_OP_ON_WN_PROTO                GENERATE_XPC_FAILURE(12)
#define NS_ERROR_XPC_CANT_CONVERT_WN_TO_FUN            GENERATE_XPC_FAILURE(13)
#define NS_ERROR_XPC_CANT_DEFINE_PROP_ON_WN            GENERATE_XPC_FAILURE(14)
#define NS_ERROR_XPC_CANT_WATCH_WN_STATIC              GENERATE_XPC_FAILURE(15)
#define NS_ERROR_XPC_CANT_EXPORT_WN_STATIC             GENERATE_XPC_FAILURE(16)
#define NS_ERROR_XPC_SCRIPTABLE_CALL_FAILED            GENERATE_XPC_FAILURE(17)
#define NS_ERROR_XPC_SCRIPTABLE_CTOR_FAILED            GENERATE_XPC_FAILURE(18)
#define NS_ERROR_XPC_CANT_CALL_WO_SCRIPTABLE           GENERATE_XPC_FAILURE(19)
#define NS_ERROR_XPC_CANT_CTOR_WO_SCRIPTABLE           GENERATE_XPC_FAILURE(20)
#define NS_ERROR_XPC_CI_RETURNED_FAILURE               GENERATE_XPC_FAILURE(21)
#define NS_ERROR_XPC_GS_RETURNED_FAILURE               GENERATE_XPC_FAILURE(22)
#define NS_ERROR_XPC_BAD_CID                           GENERATE_XPC_FAILURE(23)
#define NS_ERROR_XPC_BAD_IID                           GENERATE_XPC_FAILURE(24)
#define NS_ERROR_XPC_CANT_CREATE_WN                    GENERATE_XPC_FAILURE(25)
#define NS_ERROR_XPC_JS_THREW_EXCEPTION                GENERATE_XPC_FAILURE(26)
#define NS_ERROR_XPC_JS_THREW_NATIVE_OBJECT            GENERATE_XPC_FAILURE(27)
#define NS_ERROR_XPC_JS_THREW_JS_OBJECT                GENERATE_XPC_FAILURE(28)
#define NS_ERROR_XPC_JS_THREW_NULL                     GENERATE_XPC_FAILURE(29)
#define NS_ERROR_XPC_JS_THREW_STRING                   GENERATE_XPC_FAILURE(30)
#define NS_ERROR_XPC_JS_THREW_NUMBER                   GENERATE_XPC_FAILURE(31)
#define NS_ERROR_XPC_JAVASCRIPT_ERROR                  GENERATE_XPC_FAILURE(32)
#define NS_ERROR_XPC_JAVASCRIPT_ERROR_WITH_DETAILS     GENERATE_XPC_FAILURE(33)
#define NS_ERROR_XPC_CANT_CONVERT_PRIMITIVE_TO_ARRAY   GENERATE_XPC_FAILURE(34)
#define NS_ERROR_XPC_CANT_CONVERT_OBJECT_TO_ARRAY      GENERATE_XPC_FAILURE(35)
#define NS_ERROR_XPC_NOT_ENOUGH_ELEMENTS_IN_ARRAY      GENERATE_XPC_FAILURE(36)
#define NS_ERROR_XPC_CANT_GET_ARRAY_INFO               GENERATE_XPC_FAILURE(37)
#define NS_ERROR_XPC_NOT_ENOUGH_CHARS_IN_STRING        GENERATE_XPC_FAILURE(38)
#define NS_ERROR_XPC_SECURITY_MANAGER_VETO             GENERATE_XPC_FAILURE(39)
#define NS_ERROR_XPC_INTERFACE_NOT_SCRIPTABLE          GENERATE_XPC_FAILURE(40)
#define NS_ERROR_XPC_INTERFACE_NOT_FROM_NSISUPPORTS    GENERATE_XPC_FAILURE(41)
#define NS_ERROR_XPC_CANT_GET_JSOBJECT_OF_DOM_OBJECT   GENERATE_XPC_FAILURE(42)
#define NS_ERROR_XPC_CANT_SET_READ_ONLY_CONSTANT       GENERATE_XPC_FAILURE(43)
#define NS_ERROR_XPC_CANT_SET_READ_ONLY_ATTRIBUTE      GENERATE_XPC_FAILURE(44)
#define NS_ERROR_XPC_CANT_SET_READ_ONLY_METHOD         GENERATE_XPC_FAILURE(45)
#define NS_ERROR_XPC_CANT_ADD_PROP_TO_WRAPPED_NATIVE   GENERATE_XPC_FAILURE(46)
#define NS_ERROR_XPC_CALL_TO_SCRIPTABLE_FAILED         GENERATE_XPC_FAILURE(47)
#define NS_ERROR_XPC_JSOBJECT_HAS_NO_FUNCTION_NAMED    GENERATE_XPC_FAILURE(48)
#define NS_ERROR_XPC_BAD_ID_STRING                     GENERATE_XPC_FAILURE(49)
#define NS_ERROR_XPC_BAD_INITIALIZER_NAME              GENERATE_XPC_FAILURE(50)
#define NS_ERROR_XPC_HAS_BEEN_SHUTDOWN                 GENERATE_XPC_FAILURE(51)
#define NS_ERROR_XPC_CANT_MODIFY_PROP_ON_WN            GENERATE_XPC_FAILURE(52)
#define NS_ERROR_XPC_BAD_CONVERT_JS_ZERO_ISNOT_NULL    GENERATE_XPC_FAILURE(53)

#ifdef XPC_IDISPATCH_SUPPORT
// IDispatch support related errors
#define NS_ERROR_XPC_COM_UNKNOWN                       GENERATE_XPC_FAILURE(54)
#define NS_ERROR_XPC_COM_ERROR                         GENERATE_XPC_FAILURE(55)
#define NS_ERROR_XPC_COM_INVALID_CLASS_ID              GENERATE_XPC_FAILURE(56)
#define NS_ERROR_XPC_COM_CREATE_FAILED                 GENERATE_XPC_FAILURE(57)
#define NS_ERROR_XPC_IDISPATCH_NOT_ENABLED             GENERATE_XPC_FAILURE(58)
#endif
// any new errors here should have an associated entry added in xpc.msg
/***************************************************************************/
%}

/***************************************************************************/

// forward declarations...
interface nsIXPCScriptable;
interface nsIXPConnect;
interface nsIXPConnectWrappedNative;
interface nsIInterfaceInfo;
interface nsIXPCSecurityManager;
interface nsIPrincipal;

%{C++
class nsCycleCollectionTraversalCallback;
class nsScriptObjectTracer;
%}

/***************************************************************************/
[uuid(8916a320-d118-11d3-8f3a-0010a4e73d9a)]
interface nsIXPConnectJSObjectHolder : nsISupports
{
    readonly attribute JSObjectPtr      JSObject;
};

[uuid(7021D99D-6344-4CC0-96E7-943ED58792B8)]
interface nsIXPConnectWrappedNative : nsIXPConnectJSObjectHolder
{
    /* attribute 'JSObject' inherited from nsIXPConnectJSObjectHolder */
    readonly attribute nsISupports      Native;
    readonly attribute JSObjectPtr      JSObjectPrototype;

    /**
     * These are here as an aid to nsIXPCScriptable implementors
     */

    readonly attribute nsIXPConnect XPConnect;
    nsIInterfaceInfo FindInterfaceWithMember(in JSVal nameID);
    nsIInterfaceInfo FindInterfaceWithName(in JSVal nameID);

    void debugDump(in short depth);

    void refreshPrototype();
    /* 
     * This returns a pointer into the instance and care should be taken
     * to make sure the pointer is not kept past the life time of the
     * object it points into.
     */
    voidPtrPtr GetSecurityInfoAddress();

    /*
     * NOTE: Add new IDL methods _before_ the C++ block below if you
     * add them.  Otherwise the vtable won't be what xpidl thinks it
     * is, since GetObjectPrincipal() is virtual.
     */

%{C++
    /**
     * Faster access to the native object from C++.  Will never return null.
     */
    nsISupports* Native() const { return mIdentity; }

#ifndef XPCONNECT_STANDALONE
    /**
     * Get the object principal for this wrapper.  Note that this may well end
     * up being null; in that case one should seek principals elsewhere.  Null
     * here does NOT indicate system principal or no principals at all, just
     * that this wrapper doesn't have an intrinsic one.
     */
    virtual nsIPrincipal* GetObjectPrincipal() const = 0;
#endif
    
protected:
    nsISupports *mIdentity;
public:
%}
};

%{C++
#include "nsCOMPtr.h"

inline
const nsQueryInterface
do_QueryWrappedNative(nsIXPConnectWrappedNative *aWrappedNative)
{
    return nsQueryInterface(aWrappedNative->Native());
}

inline
const nsQueryInterfaceWithError
do_QueryWrappedNative(nsIXPConnectWrappedNative *aWrappedNative,
                      nsresult *aError)

{
    return nsQueryInterfaceWithError(aWrappedNative->Native(), aError);
}

%}

[uuid(BED52030-BCA6-11d2-BA79-00805F8A5DD7)]
interface nsIXPConnectWrappedJS : nsIXPConnectJSObjectHolder
{
    /* attribute 'JSObject' inherited from nsIXPConnectJSObjectHolder */
    readonly attribute nsIInterfaceInfo InterfaceInfo;
    readonly attribute nsIIDPtr         InterfaceIID;

    void debugDump(in short depth);

    void aggregatedQueryInterface(in nsIIDRef uuid,
                                  [iid_is(uuid),retval] out nsQIResult result);

};

/***************************************************************************/

/**
* This is a somewhat special interface. It is available from the global
* nsIXPConnect object when native methods have been called. It is only relevant
* to the currently called native method on the given JSContext/thread. Holding
* a reference past that time (or while other native methods are being called)
* will not assure access to this data.
*/

[uuid(0FA68A60-8289-11d3-BB1A-00805F8A5DD7)]
interface nsIXPCNativeCallContext : nsISupports
{

    readonly attribute nsISupports                  Callee;
    readonly attribute PRUint16                     CalleeMethodIndex;
    readonly attribute nsIXPConnectWrappedNative    CalleeWrapper;
    readonly attribute JSContextPtr                 JSContext;
    readonly attribute PRUint32                     Argc;
    readonly attribute JSValPtr                     ArgvPtr;
    /**
    * This may be NULL if the JS caller is ignoring the result of the call.
    */
    readonly attribute JSValPtr                     RetValPtr;
    /**
    * Set this if JS_SetPendingException has been called. Return NS_OK or
    * else this will be ignored and the native method's nsresult will be
    * converted into an exception and thrown into JS as is the normal case.
    */
    attribute PRBool                                ExceptionWasThrown;

    /**
    * Set this to indicate that the callee has directly set the return value
    * (using RetValPtr and the JSAPI). If set then xpconnect will not attempt
    * to overwrite it with the converted retval from the C++ callee.
    */
    attribute PRBool                                ReturnValueWasSet;

    // Methods added since mozilla 0.6....

    readonly attribute nsIInterfaceInfo             CalleeInterface;
    readonly attribute nsIClassInfo                 CalleeClassInfo;
};

/***************************************************************************/

/**
 * This is a sort of a placeholder interface. It is not intended to be
 * implemented. It exists to give the nsIXPCSecurityManager an iid on
 * which to gate a specific activity in XPConnect.
 *
 * That activity is...
 *
 * When JavaScript code uses a component that is itself implemeted in
 * JavaScript then XPConnect will build a wrapper rather than directly
 * expose the JSObject of the component. This allows components implemented
 * in JavaScript to 'look' just like any other xpcom component (from the
 * perspective of the JavaScript caller). This insulates the component from
 * the caller and hides any properties or methods that are not part of the
 * interface as declared in xpidl. Usually this is a good thing.
 *
 * However, in some cases it is useful to allow the JS caller access to the
 * JS component's underlying implementation. In order to facilitate this
 * XPConnect supports the 'wrappedJSObject' property. The caller code can do:
 *
 * // 'foo' is some xpcom component (that might be implemented in JS).
 * try {
 *   var bar = foo.wrappedJSObject;
 *   if(bar) {
 *      // bar is the underlying JSObject. Do stuff with it here.
 *   }
 * } catch(e) {
 *   // security exception?
 * }
 *
 * Recall that 'foo' above is an XPConnect wrapper, not the underlying JS
 * object. The property get "foo.wrappedJSObject" will only succeed if three
 * conditions are met:
 *
 * 1) 'foo' really is an XPConnect wrapper around a JSObject.
 * 2) The underlying JSObject actually implements a "wrappedJSObject"
 *    property that returns a JSObject. This is called by XPConnect. This
 *    restriction allows wrapped objects to only allow access to the underlying
 *    JSObject if they choose to do so. Ususally this just means that 'foo'
 *    would have a property tht looks like:
 *       this.wrappedJSObject = this.
 * 3) The implemementation of nsIXPCSecurityManager (if installed) allows
 *    a property get on the interface below. Although the JSObject need not
 *    implement 'nsIXPCWrappedJSObjectGetter', XPConnect will ask the
 *    security manager if it is OK for the caller to access the only method
 *    in nsIXPCWrappedJSObjectGetter before allowing the activity. This fits
 *    in with the security manager paradigm and makes control over accessing
 *    the property on this interface the control factor for getting the
 *    underlying wrapped JSObject of a JS component from JS code.
 *
 * Notes:
 *
 * a) If 'foo' above were the underlying JSObject and not a wrapper at all,
 *    then this all just works and XPConnect is not part of the picture at all.
 * b) One might ask why 'foo' should not just implement an interface through
 *    which callers might get at the underlying object. There are three reasons:
 *   i)   XPConnect would still have to do magic since JSObject is not a
 *        scriptable type.
 *   ii)  JS Components might use aggregation (like C++ objects) and have
 *        different JSObjects for different interfaces 'within' an aggregate
 *        object. But, using an additional interface only allows returning one
 *        underlying JSObject. However, this allows for the possibility that
 *        each of the aggregte JSObjects could return something different.
 *        Note that one might do: this.wrappedJSObject = someOtherObject;
 *   iii) Avoiding the explicit interface makes it easier for both the caller
 *        and the component.
 *
 *  Anyway, some future implementation of nsIXPCSecurityManager might want
 *  do special processing on 'nsIXPCSecurityManager::CanGetProperty' when
 *  the interface id is that of nsIXPCWrappedJSObjectGetter.
 */

[scriptable, uuid(254bb2e0-6439-11d4-8fe0-0010a4e73d9a)]
interface nsIXPCWrappedJSObjectGetter : nsISupports
{
    readonly attribute nsISupports neverCalled;
};

/***************************************************************************/

/*
 * This interface is implemented by outside code and registered with xpconnect
 * via nsIXPConnect::setFunctionThisTranslator.
 *
 * The reason this exists is to support calls to JavaScript event callbacks
 * needed by the DOM via xpconnect from C++ code.
 *
 * We've added support for wrapping JS function objects as xpcom interfaces
 * by declaring the given interface as a [function] interface. However, to
 * support the requirements of JS event callbacks we need to call the JS
 * function with the 'this' set as the JSObject for which the event is being
 * fired; e.g. a form node.
 *
 * We've decided that for all cases we care about the appropriate 'this' object
 * can be derived from the first param in the call to the callback. In the
 * event handler case the first param is an event object.
 *
 * Though we can't change all the JS code so that it would setup its own 'this',
 * we can add plugin 'helper' support to xpconnect. And that is what we have
 * here.
 *
 * The idea is that at startup time some code that cares about this issue
 * (e.g. the DOM helper code) can register a nsIXPCFunctionThisTranslator
 * object with xpconnect to handle calls to [function] interfaces of a given
 * iid. When xpconnect goes to invoke a method on a wrapped JSObject for
 * an interface marked as [function], xpconnect will check if the first param
 * of the method is an xpcom object pointer and if so it will check to see if a
 * nsIXPCFunctionThisTranslator has been registered for the given iid of the
 * interface being called. If so it will call the translator and get an
 * interface pointer to use as the 'this' for the call. If the translator
 * returns a non-null interface pointer (which it should then have addref'd
 * since it is being returned as an out param), xpconnect will attempt to build
 * a wrapper around the pointer and get a JSObject from that wrapper to use
 * as the 'this' for the call.
 *
 * If a null interface pointer is returned then xpconnect will use the default
 * 'this' - the same JSObject as the function object it is calling.
 *
 * The translator can also return a non-null aIIDOfResult to tell xpconnect what
 * type of wrapper to build. If that is null then xpconnect will assume the
 * wrapper should be for nsISupports. For objects that support flattening -
 * i.e. expose nsIClassInfo and that interface's getInterfaces method - then
 * a flattened wrapper will be created and no iid was really necessary.
 *
 * XXX aHideFirstParamFromJS is intended to allow the trimming of that first
 * param (used to indicate 'this') from the actual call to the JS code. The JS
 * DOM does not require this functionality and it is **NOT YET IMPLEMENTED**
 *
 */

[uuid(039ef260-2a0d-11d5-90a7-0010a4e73d9a)]
interface nsIXPCFunctionThisTranslator : nsISupports
{
    nsISupports TranslateThis(in nsISupports        aInitialThis,
                              in nsIInterfaceInfo   aInterfaceInfo,
                              in PRUint16           aMethodIndex,
                              out PRBool            aHideFirstParamFromJS,
                              out nsIIDPtr          aIIDOfResult);
};

/***************************************************************************/

%{ C++
// For use with the service manager
// {CB6593E0-F9B2-11d2-BDD6-000064657374}
#define NS_XPCONNECT_CID \
{ 0xcb6593e0, 0xf9b2, 0x11d2, \
    { 0xbd, 0xd6, 0x0, 0x0, 0x64, 0x65, 0x73, 0x74 } }
%}

[uuid(20df9082-5b83-416d-ba80-0422af516d57)]
interface nsIXPConnect : nsISupports
{
%{ C++
  NS_DEFINE_STATIC_CID_ACCESSOR(NS_XPCONNECT_CID)
%}

    void
    initClasses(in JSContextPtr aJSContext,
                in JSObjectPtr  aGlobalJSObj);

    nsIXPConnectJSObjectHolder
    initClassesWithNewWrappedGlobal(
                  in JSContextPtr aJSContext,
                  in nsISupports  aCOMObj,
                  in nsIIDRef     aIID,
                  in PRUint32     aFlags);

    const PRUint32 INIT_JS_STANDARD_CLASSES  = 1 << 0;
    const PRUint32 FLAG_SYSTEM_GLOBAL_OBJECT = 1 << 1;

    /**
    * wrapNative will create a new JSObject or return an existing one.
    *
    * The JSObject is returned inside a refcounted nsIXPConnectJSObjectHolder.
    * As long as this holder is held the JSObject will be protected from
    * collection by JavaScript's garbage collector. It is a good idea to
    * transfer the JSObject to some equally protected place before releasing
    * the holder (i.e. use JS_SetProperty to make this object a property of
    * some other JSObject).
    *
    * This method now correctly deals with cases where the passed in xpcom
    * object already has an associated JSObject for the cases:
    *  1) The xpcom object has already been wrapped for use in the same scope
    *     as an nsIXPConnectWrappedNative.
    *  2) The xpcom object is in fact a nsIXPConnectWrappedJS and thus already
    *     has an underlying JSObject.
    *  3) The xpcom object implements nsIScriptObjectOwner; i.e. is an idlc
    *     style DOM object for which we can call GetScriptObject to get the
    *     JSObject it uses to represent itself into JavaScript.
    *
    * It *might* be possible to QueryInterface the nsIXPConnectJSObjectHolder
    * returned by the method into a nsIXPConnectWrappedNative or a
    * nsIXPConnectWrappedJS.
    *
    * This method will never wrap the JSObject involved in an
    * XPCNativeWrapper before returning.
    *
    * Returns:
    *    success:
    *       NS_OK
    *    failure:
    *       NS_ERROR_XPC_BAD_CONVERT_NATIVE
    *       NS_ERROR_XPC_CANT_GET_JSOBJECT_OF_DOM_OBJECT
    *       NS_ERROR_FAILURE
    */
    nsIXPConnectJSObjectHolder
    wrapNative(in JSContextPtr aJSContext,
               in JSObjectPtr  aScope,
               in nsISupports  aCOMObj,
               in nsIIDRef     aIID);

    /**
    * wrapJS will yield a new or previously existing xpcom interface pointer
    * to represent the JSObject passed in.
    *
    * This method now correctly deals with cases where the passed in JSObject
    * already has an associated xpcom interface for the cases:
    *  1) The JSObject has already been wrapped as a nsIXPConnectWrappedJS.
    *  2) The JSObject is in fact a nsIXPConnectWrappedNative and thus already
    *     has an underlying xpcom object.
    *  3) The JSObject is of a jsclass which supports getting the nsISupports
    *     from the JSObject directly. This is used for idlc style objects
    *     (e.g. DOM objects).
    *
    * It *might* be possible to QueryInterface the resulting interface pointer
    * to nsIXPConnectWrappedJS.
    *
    * Returns:
    *   success:
    *     NS_OK
    *    failure:
    *       NS_ERROR_XPC_BAD_CONVERT_JS
    *       NS_ERROR_FAILURE
    */
    void
    wrapJS(in JSContextPtr aJSContext,
           in JSObjectPtr  aJSObj,
           in nsIIDRef     aIID,
           [iid_is(aIID),retval] out nsQIResult result);

    /**
    * This only succeeds if the JSObject is a nsIXPConnectWrappedNative.
    * A new wrapper is *never* constructed.
    */
    nsIXPConnectWrappedNative
    getWrappedNativeOfJSObject(in JSContextPtr aJSContext,
                               in JSObjectPtr  aJSObj);

    void setSecurityManagerForJSContext(in JSContextPtr aJSContext,
                                        in nsIXPCSecurityManager aManager,
                                        in PRUint16 flags);

    void getSecurityManagerForJSContext(in JSContextPtr aJSContext,
                                        out nsIXPCSecurityManager aManager,
                                        out PRUint16 flags);

    /**
    * The security manager to use when the current JSContext has no security
    * manager.
    */
    void setDefaultSecurityManager(in nsIXPCSecurityManager aManager,
                                   in PRUint16 flags);

    void getDefaultSecurityManager(out nsIXPCSecurityManager aManager,
                                   out PRUint16 flags);

    nsIStackFrame
    createStackFrameLocation(in PRUint32       aLanguage,
                             in string         aFilename,
                             in string         aFunctionName,
                             in PRInt32        aLineNumber,
                             in nsIStackFrame  aCaller);

    /**
    * XPConnect builds internal objects that parallel, and are one-to-one with,
    * the JSContexts in the JSRuntime. It builds these objects as needed.
    * This method tells XPConnect to resynchronize its representations with the
    * list of JSContexts currently 'alive' in the JSRuntime. This allows it
    * to cleanup any representations of JSContexts that are no longer valid.
    */
    void syncJSContexts();

    readonly attribute nsIStackFrame                CurrentJSStack;
    readonly attribute nsIXPCNativeCallContext      CurrentNativeCallContext;
    /* pass nsnull to clear pending exception */
             attribute nsIException                 PendingException;

    void debugDump(in short depth);
    void debugDumpObject(in nsISupports aCOMObj, in short depth);
    void debugDumpJSStack(in PRBool showArgs,
                          in PRBool showLocals,
                          in PRBool showThisProps);
    void debugDumpEvalInJSStackFrame(in PRUint32 aFrameNumber,
                                     in string aSourceText);

    /**
    * Set fallback JSContext to use when xpconnect can't find an appropriate
    * context to use to execute JavaScript.
    *
    * NOTE: This method is DEPRECATED. 
    *       Use nsIThreadJSContextStack::safeJSContext instead.
    */
    void setSafeJSContextForCurrentThread(in JSContextPtr cx);

    /**
    * wrapJSAggregatedToNative is just like wrapJS except it is used in cases
    * where the JSObject is also aggregated to some native xpcom Object.
    * At present XBL is the only system that might want to do this.
    *
    * XXX write more!
    *
    * Returns:
    *   success:
    *     NS_OK
    *    failure:
    *       NS_ERROR_XPC_BAD_CONVERT_JS
    *       NS_ERROR_FAILURE
    */
    void
    wrapJSAggregatedToNative(in nsISupports  aOuter,
                             in JSContextPtr aJSContext,
                             in JSObjectPtr  aJSObj,
                             in nsIIDRef     aIID,
                             [iid_is(aIID),retval] out nsQIResult result);

    // Methods added since mozilla 0.6....

    /**
    * This only succeeds if the native object is already wrapped by xpconnect.
    * A new wrapper is *never* constructed.
    */
    nsIXPConnectWrappedNative
    getWrappedNativeOfNativeObject(in JSContextPtr aJSContext,
                                   in JSObjectPtr  aScope,
                                   in nsISupports  aCOMObj,
                                   in nsIIDRef     aIID);

    nsIXPCFunctionThisTranslator
    getFunctionThisTranslator(in nsIIDRef aIID);

    nsIXPCFunctionThisTranslator
    setFunctionThisTranslator(in nsIIDRef aIID,
                              in nsIXPCFunctionThisTranslator aTranslator);

    nsIXPConnectJSObjectHolder
    reparentWrappedNativeIfFound(in JSContextPtr aJSContext,
                                 in JSObjectPtr  aScope,
                                 in JSObjectPtr  aNewParent,
                                 in nsISupports  aCOMObj);
    void
    reparentScopeAwareWrappers(in JSContextPtr aJSContext,
                               in JSObjectPtr  aOldScope,
                               in JSObjectPtr  aNewScope);

    void clearAllWrappedNativeSecurityPolicies();

    nsIXPConnectJSObjectHolder
    getWrappedNativePrototype(in JSContextPtr aJSContext,
                              in JSObjectPtr  aScope,
                              in nsIClassInfo aClassInfo);

    void releaseJSContext(in JSContextPtr aJSContext, in PRBool noGC);

    JSVal variantToJS(in JSContextPtr ctx, in JSObjectPtr scope, in nsIVariant value);
    nsIVariant JSToVariant(in JSContextPtr ctx, in JSVal value);

    /**
     * Preconfigure XPCNativeWrapper automation so that when a scripted
     * caller whose filename starts with filenamePrefix accesses a wrapped
     * native that is not flagged as "system", the wrapped native will be
     * automatically wrapped with an XPCNativeWrapper.
     *
     * @param aFilenamePrefix the UTF-8 filename prefix to match, which
     *                        should end with a slash (/) character
     * @param aWantNativeWrappers whether XPConnect should produce native
     *                            wrappers for scripts whose paths begin
     *                            with this prefix
     */
    void flagSystemFilenamePrefix(in string aFilenamePrefix,
                                  in PRBool aWantNativeWrappers);

    /**
     * Restore an old prototype for wrapped natives of type
     * aClassInfo. This should be used only when restoring an old
     * scope into a state close to where it was prior to
     * being reinitialized.
     */
    void restoreWrappedNativePrototype(in JSContextPtr aJSContext,
                                       in JSObjectPtr  aScope,
                                       in nsIClassInfo aClassInfo,
                                       in nsIXPConnectJSObjectHolder aPrototype);

    /**
     * Create a sandbox for evaluating code in isolation using
     * evalInSandboxObject().
     *
     * @param cx A context to use when creating the sandbox object.
     * @param principal The principal (or NULL to use the null principal)
     *                  to use when evaluating code in this sandbox.
     */
    [noscript] nsIXPConnectJSObjectHolder createSandbox(in JSContextPtr cx,
                                                        in nsIPrincipal principal);

    /**
     * Evaluate script in a sandbox, completely isolated from all
     * other running scripts.
     *
     * @param source The source of the script to evaluate.
     * @param cx The context to use when setting up the evaluation of
     *           the script. The actual evaluation will happen on a new
     *           temporary context.
     * @param sandbox The sandbox object to evaluate the script in.
     * @param returnStringOnly The only results to come out of the
     *                         computation (including exceptions) will
     *                         be coerced into strings created in the
     *                         sandbox.
     * @return The result of the evaluation as a jsval. If the caller
     *         intends to use the return value from this call the caller
     *         is responsible for rooting the jsval before making a call
     *         to this method.
     */
    [noscript] JSVal evalInSandboxObject(in AString source, in JSContextPtr cx,
                                         in nsIXPConnectJSObjectHolder sandbox,
                                         in PRBool returnStringOnly);

    /**
     * Wrap a jsval in a cross origin wrapper.
     * @param aJSContext A context to use to create objects.
     * @param aParent The parent to create the wrapper with.
     * @param aWrappedObj The object to wrap.
     */
    [noscript] JSVal getXOWForObject(in JSContextPtr aJSContext,
                                     in JSObjectPtr aParent,
                                     in JSObjectPtr aWrappedObj);

    /**
     * Tells updateXOWs to clear the scope of all of the XOWs it finds.
     */
    const PRUint32 XPC_XOW_CLEARSCOPE = 1;

    /**
     * Performs an operation over all of |object|'s XOWs such as clearing
     * their scopes or updating their concept of the current principal.
     *
     * @param aJSContext A context to use to perform JS operations.
     * @param aObject Which XPCWrappedNative we should find the XOWs for.
     * @param aWay What operation to perform.
     */
    [noscript] void updateXOWs(in JSContextPtr aJSContext,
                               in nsIXPConnectWrappedNative aObject,
                               in PRUint32 aWay);

    /**
     * Root JS objects held by aHolder.
     * @param aHolder The object that hold the JS objects that should be rooted.
     * @param aTrace The tracer for aHolder.
     */
    [noscript] void addJSHolder(in voidPtr aHolder,
                                in nsScriptObjectTracerPtr aTracer);

    /**
     * Stop rooting the JS objects held by aHolder.
     * @param aHolder The object that hold the rooted JS objects.
     */
    [noscript] void removeJSHolder(in voidPtr aHolder);

    /**
     * Note aJSContext as a child to the cycle collector.
     * @param aJSContext The JSContext to note.
     * @param aCb The cycle collection traversal callback.
     */
    [noscript,notxpcom] void noteJSContext(in JSContextPtr aJSContext,
                                           in nsCCTraversalCallbackRef aCb);

    /**
     * Get the JSClass and JSGetObjectOps pointers to use for
     * identifying JSObjects that hold nsIXPConnectWrappedNative
     * pointers in their private date. See IS_WRAPPER_CLASS in
     * xpcprivate.h for details.
     */
    void GetXPCWrappedNativeJSClassInfo(out JSClassConstPtr clazz,
                                        out JSGetObjectOps ops1,
                                        out JSGetObjectOps ops2);
};