diff options
Diffstat (limited to 'js/xpconnect/idl/nsIXPConnect.idl')
| -rw-r--r-- | js/xpconnect/idl/nsIXPConnect.idl | 542 |
1 files changed, 542 insertions, 0 deletions
diff --git a/js/xpconnect/idl/nsIXPConnect.idl b/js/xpconnect/idl/nsIXPConnect.idl new file mode 100644 index 0000000000..4bdc007fc1 --- /dev/null +++ b/js/xpconnect/idl/nsIXPConnect.idl @@ -0,0 +1,542 @@ +/* -*- 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); +}; |