/* -*- Mode: IDL; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- * * This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ /* The core XPConnect public interfaces. */ #include "nsISupports.idl" %{ C++ #include "jspubtd.h" #include "js/TypeDecls.h" #include "mozilla/Attributes.h" #include "nsCOMPtr.h" struct JSFreeOp; class nsWrapperCache; class nsAXPCNativeCallContext; %} /***************************************************************************/ // NB: jsval and jsid are declared in nsrootidl.idl [ptr] native JSContextPtr(JSContext); [ptr] native JSClassPtr(JSClass); [ptr] native JSFreeOpPtr(JSFreeOp); [ptr] native JSObjectPtr(JSObject); [ptr] native JSValConstPtr(const JS::Value); native JSEqualityOp(JSEqualityOp); [ptr] native JSScriptPtr(JSScript); [ptr] native voidPtrPtr(void*); [ptr] native nsAXPCNativeCallContextPtr(nsAXPCNativeCallContext); [ptr] native nsWrapperCachePtr(nsWrapperCache); [ref] native JSCompartmentOptions(JS::CompartmentOptions); [ref] native JSCallArgsRef(const JS::CallArgs); native JSHandleId(JS::Handle<jsid>); /***************************************************************************/ // forward declarations... interface nsIXPCScriptable; interface nsIXPConnect; interface nsIXPConnectWrappedNative; interface nsIInterfaceInfo; interface nsIXPCSecurityManager; interface nsIPrincipal; interface nsIClassInfo; interface nsIVariant; interface nsIStackFrame; interface nsIObjectInputStream; interface nsIObjectOutputStream; /***************************************************************************/ [uuid(73e6ff4a-ab99-4d99-ac00-ba39ccb8e4d7)] interface nsIXPConnectJSObjectHolder : nsISupports { [notxpcom, nostdcall] JSObjectPtr GetJSObject(); }; [uuid(e787be29-db5d-4a45-a3d6-1de1d6b85c30)] 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 */ nsIInterfaceInfo FindInterfaceWithMember(in JSHandleId nameID); nsIInterfaceInfo FindInterfaceWithName(in JSHandleId nameID); [notxpcom] bool HasNativeMember(in JSHandleId name); void debugDump(in short depth); /* * 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; } protected: nsCOMPtr<nsISupports> mIdentity; public: %} }; %{C++ 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(3a01b0d6-074b-49ed-bac3-08c76366cae4)] 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); }; // Special interface to unmark the internal JSObject. // QIing to nsIXPConnectWrappedJSUnmarkGray does *not* addref, it only unmarks, // and QIing to nsIXPConnectWrappedJSUnmarkGray is always supposed to fail. [builtinclass, uuid(c02a0ce6-275f-4ea1-9c23-08494898b070)] interface nsIXPConnectWrappedJSUnmarkGray : nsIXPConnectWrappedJS { }; /***************************************************************************/ /** * 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 implemented 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. */ [uuid(f5f84b70-92eb-41f1-a1dd-2eaac0ed564c)] interface nsIXPCFunctionThisTranslator : nsISupports { nsISupports TranslateThis(in nsISupports aInitialThis); }; /***************************************************************************/ %{ 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 } } %} [noscript, uuid(768507b5-b981-40c7-8276-f6a1da502a24)] interface nsIXPConnect : nsISupports { %{ C++ NS_DEFINE_STATIC_CID_ACCESSOR(NS_XPCONNECT_CID) %} /** * Creates a new global object using the given aCOMObj as the global * object. The object will be set up according to the flags (defined * below). If you do not pass INIT_JS_STANDARD_CLASSES, then aCOMObj * must implement nsIXPCScriptable so it can resolve the standard * classes when asked by the JS engine. * * @param aJSContext the context to use while creating the global object. * @param aCOMObj the native object that represents the global object. * @param aPrincipal the principal of the code that will run in this * compartment. Can be null if not on the main thread. * @param aFlags one of the flags below specifying what options this * global object wants. * @param aOptions JSAPI-specific options for the new compartment. */ nsIXPConnectJSObjectHolder initClassesWithNewWrappedGlobal( in JSContextPtr aJSContext, in nsISupports aCOMObj, in nsIPrincipal aPrincipal, in uint32_t aFlags, in JSCompartmentOptions aOptions); const uint32_t INIT_JS_STANDARD_CLASSES = 1 << 0; const uint32_t DONT_FIRE_ONNEWGLOBALHOOK = 1 << 1; const uint32_t OMIT_COMPONENTS_OBJECT = 1 << 2; /** * wrapNative will create a new JSObject or return an existing one. * * 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. * * 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 */ JSObjectPtr wrapNative(in JSContextPtr aJSContext, in JSObjectPtr aScope, in nsISupports aCOMObj, in nsIIDRef aIID); /** * Same as wrapNative, but it returns the JSObject in an nsIXPConnectJSObjectHolder. */ nsIXPConnectJSObjectHolder wrapNativeHolder(in JSContextPtr aJSContext, in JSObjectPtr aScope, in nsISupports aCOMObj, in nsIIDRef aIID); /** * Same as wrapNative, but it returns the JSObject in aVal. C++ callers * must ensure that aVal is rooted. * aIID may be null, it means the same as passing in * &NS_GET_IID(nsISupports) but when passing in null certain shortcuts * can be taken because we know without comparing IIDs that the caller is * asking for an nsISupports wrapper. * If aAllowWrapper, then the returned value will be wrapped in the proper * type of security wrapper on top of the XPCWrappedNative (if needed). * This method doesn't push aJSContext on the context stack, so the caller * is required to push it if the top of the context stack is not equal to * aJSContext. */ void wrapNativeToJSVal(in JSContextPtr aJSContext, in JSObjectPtr aScope, in nsISupports aCOMObj, in nsWrapperCachePtr aCache, in nsIIDPtr aIID, in boolean aAllowWrapper, out jsval aVal); /** * 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); /** * Wraps the given jsval in a nsIVariant and returns the new variant. */ nsIVariant jSValToVariant(in JSContextPtr cx, in jsval aJSVal); /** * This only succeeds if the JSObject is a nsIXPConnectWrappedNative. * A new wrapper is *never* constructed. */ nsIXPConnectWrappedNative getWrappedNativeOfJSObject(in JSContextPtr aJSContext, in JSObjectPtr aJSObj); // Will return null if there is no JS stack right now. readonly attribute nsIStackFrame CurrentJSStack; readonly attribute nsAXPCNativeCallContextPtr CurrentNativeCallContext; void debugDump(in short depth); void debugDumpObject(in nsISupports aCOMObj, in short depth); void debugDumpJSStack(in boolean showArgs, in boolean showLocals, in boolean showThisProps); /** * 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); void setFunctionThisTranslator(in nsIIDRef aIID, in nsIXPCFunctionThisTranslator aTranslator); JSObjectPtr getWrappedNativePrototype(in JSContextPtr aJSContext, in JSObjectPtr aScope, in nsIClassInfo aClassInfo); jsval variantToJS(in JSContextPtr ctx, in JSObjectPtr scope, in nsIVariant value); nsIVariant JSToVariant(in JSContextPtr ctx, in jsval value); /** * 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] JSObjectPtr 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 filename The filename of the script. May be null. * @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 version The JavaScript version to use for evaluating the script. * Should be a valid JSVersion from jspubtd.h. * @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 string filename, in JSContextPtr cx, in JSObjectPtr sandbox, in int32_t version); /** * Trigger a JS garbage collection. * Use a js::gcreason::Reason from jsfriendapi.h for the kind. */ void GarbageCollect(in uint32_t reason); /** * Signals a good place to do an incremental GC slice, because the * browser is drawing a frame. */ void NotifyDidPaint(); %{C++ /** * 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* GetPrincipal(JSObject* obj, bool allowShortCircuit) const = 0; virtual char* DebugPrintJSStack(bool showArgs, bool showLocals, bool showThisProps) = 0; %} [noscript] void writeScript(in nsIObjectOutputStream aStream, in JSContextPtr aJSContext, in JSScriptPtr aJSScript); [noscript] JSScriptPtr readScript(in nsIObjectInputStream aStream, in JSContextPtr aJSContext); [noscript] void writeFunction(in nsIObjectOutputStream aStream, in JSContextPtr aJSContext, in JSObjectPtr aJSObject); [noscript] JSObjectPtr readFunction(in nsIObjectInputStream aStream, in JSContextPtr aJSContext); };