diff options
Diffstat (limited to 'js/xpconnect/idl')
| -rw-r--r-- | js/xpconnect/idl/moz.build | 22 | ||||
| -rw-r--r-- | js/xpconnect/idl/mozIJSSubScriptLoader.idl | 67 | ||||
| -rw-r--r-- | js/xpconnect/idl/nsIAddonInterposition.idl | 67 | ||||
| -rw-r--r-- | js/xpconnect/idl/nsIScriptError.idl | 122 | ||||
| -rw-r--r-- | js/xpconnect/idl/nsIXPCScriptable.idl | 157 | ||||
| -rw-r--r-- | js/xpconnect/idl/nsIXPConnect.idl | 542 | ||||
| -rw-r--r-- | js/xpconnect/idl/xpcIJSGetFactory.idl | 18 | ||||
| -rw-r--r-- | js/xpconnect/idl/xpcIJSModuleLoader.idl | 82 | ||||
| -rw-r--r-- | js/xpconnect/idl/xpcIJSWeakReference.idl | 17 | ||||
| -rw-r--r-- | js/xpconnect/idl/xpccomponents.idl | 732 | ||||
| -rw-r--r-- | js/xpconnect/idl/xpcexception.idl | 30 | ||||
| -rw-r--r-- | js/xpconnect/idl/xpcjsid.idl | 47 |
12 files changed, 1903 insertions, 0 deletions
diff --git a/js/xpconnect/idl/moz.build b/js/xpconnect/idl/moz.build new file mode 100644 index 000000000..2438b1a5a --- /dev/null +++ b/js/xpconnect/idl/moz.build @@ -0,0 +1,22 @@ +# -*- Mode: python; indent-tabs-mode: nil; tab-width: 40 -*- +# vim: set filetype=python: +# 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/. + +XPIDL_SOURCES += [ + 'mozIJSSubScriptLoader.idl', + 'nsIAddonInterposition.idl', + 'nsIScriptError.idl', + 'nsIXPConnect.idl', + 'nsIXPCScriptable.idl', + 'xpccomponents.idl', + 'xpcexception.idl', + 'xpcIJSGetFactory.idl', + 'xpcIJSModuleLoader.idl', + 'xpcIJSWeakReference.idl', + 'xpcjsid.idl', +] + +XPIDL_MODULE = 'xpconnect' + diff --git a/js/xpconnect/idl/mozIJSSubScriptLoader.idl b/js/xpconnect/idl/mozIJSSubScriptLoader.idl new file mode 100644 index 000000000..1b5ed901b --- /dev/null +++ b/js/xpconnect/idl/mozIJSSubScriptLoader.idl @@ -0,0 +1,67 @@ +/* -*- Mode: C++; tab-width: 4; 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/. */ + +#include "nsISupports.idl" + +interface nsIURI; +interface nsIPrincipal; +interface nsIObserver; + +[scriptable, uuid(19533e7b-f321-4ef1-bc59-6e812dc2a733)] +interface mozIJSSubScriptLoader : nsISupports +{ + /** + * This method should only be called from JS! + * In JS, the signature looks like: + * rv loadSubScript (url [, obj] [, charset]); + * @param url the url of the sub-script, it MUST be either a file:, + * resource:, or chrome: url, and MUST be local. + * @param obj an optional object to evaluate the script onto, it + * defaults to the global object of the caller. + * @param charset optionally specifies the character encoding of + * the file. If absent, the file is interpreted + * as ASCII. + * @retval rv the value returned by the sub-script + */ + [implicit_jscontext] + jsval loadSubScript(in AString url, [optional] in jsval obj, [optional] in AString charset); + + /** + * This method should only be called from JS! + * In JS, the signature looks like: + * rv = loadSubScript (url, optionsObject) + * @param url the url of the sub-script, it MUST be either a file:, + * resource:, or chrome: url, and MUST be local. + * @param optionsObject an object with parameters. Valid parameters are: + * - charset: specifying the character encoding of the file (default: ASCII) + * - target: an object to evaluate onto (default: global object of the caller) + * - ignoreCache: if set to true, will bypass the cache for reading the file. + * - async: if set to true, the script will be loaded + * asynchronously, and a Promise is returned which + * resolves to its result when execution is complete. + * @retval rv the value returned by the sub-script + */ + [implicit_jscontext] + jsval loadSubScriptWithOptions(in AString url, in jsval options); + + /* + * Compiles a JS script off the main thread and calls back the + * observer once it's done. + * The script will be cached in temporary or persistent storage depending + * on the principal used. + * We fire the notification callback in all cases - there is no fatal + * error there. + * @param uri the uri of the script to load. + * @param principal the principal from which we get the app id if any. + * @param observer this observer will be called once the script has + * been precompiled. The notification topic will be + * 'script-precompiled' and the subject the uri of the + * script as a nsIURI. + */ + void precompileScript(in nsIURI uri, + in nsIPrincipal principal, + in nsIObserver observer); +}; diff --git a/js/xpconnect/idl/nsIAddonInterposition.idl b/js/xpconnect/idl/nsIAddonInterposition.idl new file mode 100644 index 000000000..1d1166ef2 --- /dev/null +++ b/js/xpconnect/idl/nsIAddonInterposition.idl @@ -0,0 +1,67 @@ +/* -*- Mode: C; 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/. */ + +#include "nsISupports.idl" + +/** + * This interface allows Firefox to expose different implementations of its own + * classes to add-ons. Once an interposition is created, it must be assigned to + * an add-on using Cu.setAddonInterposition (JS) or xpc::SetAddonInterposition + * (C++). In both cases, the arguments should be the add-on ID and the + * interposition object (which must be an nsIAddonInterposition). This must + * happen before any compartments are created for the given add-on. + * + * Every time the add-on accesses a property on any object outside its own set + * of compartments, XPConnect will call the interposition's + * interpose method. If the interposition wants to replace the given + * property, it should return a replacement property descriptor for it. If not, + * it should return null. + */ +[scriptable,uuid(d05cc5fd-ad88-41a6-854c-36fd94d69ddb)] +interface nsIAddonInterposition : nsISupports +{ + /** + * Returns a replacement property descriptor for a browser object. + * + * @param addonId The ID of the add-on accessing the property. + * @param target The browser object being accessed. + * @param iface The IID of the interface the property is associated with. This + * parameter is only available for XPCWrappedNative targets. As + * such, it's only useful as an optimization to avoid + * instanceof checks on the target. + * @param prop The name of the property being accessed. + * @return A property descriptor or null. + */ + jsval interposeProperty(in jsval addonId, + in jsval target, + in nsIIDPtr iface, + in jsval prop); + /** + * We're intercepting calls from add-ons scopes into non-addon scopes. + * + * @param addonId The ID of the add-on accessing the property. + * @param originalFunc The function object being intercepted. + * @param originalThis The |this| value for the intercepted call. + * @param args The arguments of the original call in an array. + * @return The result of the call. NOTE: after the call interception, + * the original function will not be called automatically, so the + * implementer has to do that. + */ + jsval interposeCall(in jsval addonId, + in jsval originalFunc, + in jsval originalThis, + in jsval args); + + /** + * For the first time when the interposition is registered the engine + * calls getWhitelist and expects an array of strings. The strings are + * the name of properties the interposition wants interposeProperty + * to be called. It can be an empty array. + * Note: for CPOWs interposeProperty is always called regardless if + * the name of the property is on the whitelist or not. + */ + jsval getWhitelist(); +}; diff --git a/js/xpconnect/idl/nsIScriptError.idl b/js/xpconnect/idl/nsIScriptError.idl new file mode 100644 index 000000000..468ca682f --- /dev/null +++ b/js/xpconnect/idl/nsIScriptError.idl @@ -0,0 +1,122 @@ +/* -*- Mode: C++; tab-width: 4; 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/. */ + +/* + * nsIConsoleMessage subclass for representing JavaScript errors and warnings. + */ + + +#include "nsISupports.idl" +#include "nsIConsoleMessage.idl" + +%{C++ +#include "nsStringGlue.h" // for nsDependentCString +%} + +[scriptable, uuid(361be358-76f0-47aa-b37b-6ad833599e8d)] +interface nsIScriptError : nsIConsoleMessage +{ + /** pseudo-flag for default case */ + const unsigned long errorFlag = 0x0; + + /** message is warning */ + const unsigned long warningFlag = 0x1; + + /** exception was thrown for this case - exception-aware hosts can ignore */ + const unsigned long exceptionFlag = 0x2; + + // XXX check how strict is implemented these days. + /** error or warning is due to strict option */ + const unsigned long strictFlag = 0x4; + + /** just a log message */ + const unsigned long infoFlag = 0x8; + + /** + * The error message without any context/line number information. + * + * @note nsIConsoleMessage.message will return the error formatted + * with file/line information. + */ + readonly attribute AString errorMessage; + + readonly attribute AString sourceName; + readonly attribute AString sourceLine; + readonly attribute uint32_t lineNumber; + readonly attribute uint32_t columnNumber; + readonly attribute uint32_t flags; + + /** + * Categories I know about - + * XUL javascript + * content javascript (both of these from nsDocShell, currently) + * system javascript (errors in JS components and other system JS) + */ + readonly attribute string category; + + /* Get the window id this was initialized with. Zero will be + returned if init() was used instead of initWithWindowID(). */ + readonly attribute unsigned long long outerWindowID; + + /* Get the inner window id this was initialized with. Zero will be + returned if init() was used instead of initWithWindowID(). */ + readonly attribute unsigned long long innerWindowID; + + readonly attribute boolean isFromPrivateWindow; + + attribute jsval stack; + + /** + * The name of a template string, as found in js.msg, associated with the + * error message. + */ + attribute AString errorMessageName; + + + void init(in AString message, + in AString sourceName, + in AString sourceLine, + in uint32_t lineNumber, + in uint32_t columnNumber, + in uint32_t flags, + in string category); + + /* This should be called instead of nsIScriptError.init to + initialize with a window id. The window id should be for the + inner window associated with this error. */ + void initWithWindowID(in AString message, + in AString sourceName, + in AString sourceLine, + in uint32_t lineNumber, + in uint32_t columnNumber, + in uint32_t flags, + in ACString category, + in unsigned long long innerWindowID); +%{C++ + // This overload allows passing a literal string for category. + template<uint32_t N> + nsresult InitWithWindowID(const nsAString& message, + const nsAString& sourceName, + const nsAString& sourceLine, + uint32_t lineNumber, + uint32_t columnNumber, + uint32_t flags, + const char (&c)[N], + uint64_t aInnerWindowID) + { + nsDependentCString category(c, N - 1); + return InitWithWindowID(message, sourceName, sourceLine, lineNumber, + columnNumber, flags, category, aInnerWindowID); + } +%} + +}; + +%{ C++ +#define NS_SCRIPTERROR_CID \ +{ 0x1950539a, 0x90f0, 0x4d22, { 0xb5, 0xaf, 0x71, 0x32, 0x9c, 0x68, 0xfa, 0x35 }} + +#define NS_SCRIPTERROR_CONTRACTID "@mozilla.org/scripterror;1" +%} diff --git a/js/xpconnect/idl/nsIXPCScriptable.idl b/js/xpconnect/idl/nsIXPCScriptable.idl new file mode 100644 index 000000000..b7ba02b8a --- /dev/null +++ b/js/xpconnect/idl/nsIXPCScriptable.idl @@ -0,0 +1,157 @@ +/* -*- Mode: C; 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/. */ + +#include "nsISupports.idl" +#include "nsIClassInfo.idl" + +%{C++ +#ifdef XP_WIN +#undef GetClassName +#endif + +#include "js/TypeDecls.h" + +struct JSFreeOp; +namespace js { +struct Class; +} +%} + +interface nsIXPConnectWrappedNative; + +[ptr] native JSContextPtr(JSContext); +[ptr] native JSObjectPtr(JSObject); +[ptr] native JSValPtr(JS::Value); +[ptr] native JSFreeOpPtr(JSFreeOp); +[ref] native JSCallArgsRef(const JS::CallArgs); +[ref] native JSAutoIdVector(JS::AutoIdVector); +[ptr] native jsClassPtr(const js::Class); + +/** + * Note: This is not really an XPCOM interface. For example, callers must + * guarantee that they set the *_retval of the various methods that return a + * boolean to PR_TRUE before making the call. Implementations may skip writing + * to *_retval unless they want to return PR_FALSE. + */ +[uuid(19b70b26-7c3f-437f-a04a-2a8f9e28b617)] +interface nsIXPCScriptable : nsISupports +{ + /* bitflags used for 'flags' (only 32 bits available!) */ + + const uint32_t WANT_PRECREATE = 1 << 0; + // unused bit here + // unused bit here + const uint32_t WANT_ADDPROPERTY = 1 << 3; + // unused bit here + const uint32_t WANT_GETPROPERTY = 1 << 5; + const uint32_t WANT_SETPROPERTY = 1 << 6; + const uint32_t WANT_ENUMERATE = 1 << 7; + const uint32_t WANT_NEWENUMERATE = 1 << 8; + const uint32_t WANT_RESOLVE = 1 << 9; + // unused bit here + const uint32_t WANT_FINALIZE = 1 << 11; + // unused bit here! + const uint32_t WANT_CALL = 1 << 13; + const uint32_t WANT_CONSTRUCT = 1 << 14; + const uint32_t WANT_HASINSTANCE = 1 << 15; + // Unused bit here! + const uint32_t USE_JSSTUB_FOR_ADDPROPERTY = 1 << 17; + const uint32_t USE_JSSTUB_FOR_DELPROPERTY = 1 << 18; + const uint32_t USE_JSSTUB_FOR_SETPROPERTY = 1 << 19; + // Unused bit here! + const uint32_t DONT_ENUM_QUERY_INTERFACE = 1 << 21; + const uint32_t DONT_ASK_INSTANCE_FOR_SCRIPTABLE = 1 << 22; + const uint32_t CLASSINFO_INTERFACES_ONLY = 1 << 23; + const uint32_t ALLOW_PROP_MODS_DURING_RESOLVE = 1 << 24; + const uint32_t ALLOW_PROP_MODS_TO_PROTOTYPE = 1 << 25; + const uint32_t IS_GLOBAL_OBJECT = 1 << 26; + const uint32_t DONT_REFLECT_INTERFACE_NAMES = 1 << 27; + + // The high order bit is RESERVED for consumers of these flags. + // No implementor of this interface should ever return flags + // with this bit set. + const uint32_t RESERVED = 1 << 31; + + readonly attribute string className; + [notxpcom,nostdcall] uint32_t getScriptableFlags(); + [notxpcom,nostdcall] jsClassPtr getClass(); + + void preCreate(in nsISupports nativeObj, in JSContextPtr cx, + in JSObjectPtr globalObj, out JSObjectPtr parentObj); + + boolean addProperty(in nsIXPConnectWrappedNative wrapper, + in JSContextPtr cx, in JSObjectPtr obj, in jsid id, + in jsval val); + + boolean getProperty(in nsIXPConnectWrappedNative wrapper, + in JSContextPtr cx, in JSObjectPtr obj, in jsid id, + in JSValPtr vp); + + boolean setProperty(in nsIXPConnectWrappedNative wrapper, + in JSContextPtr cx, in JSObjectPtr obj, in jsid id, + in JSValPtr vp); + + boolean enumerate(in nsIXPConnectWrappedNative wrapper, + in JSContextPtr cx, in JSObjectPtr obj); + + boolean newEnumerate(in nsIXPConnectWrappedNative wrapper, + in JSContextPtr cx, in JSObjectPtr obj, + in JSAutoIdVector properties); + + boolean resolve(in nsIXPConnectWrappedNative wrapper, + in JSContextPtr cx, in JSObjectPtr obj, in jsid id, + out boolean resolvedp); + + void finalize(in nsIXPConnectWrappedNative wrapper, + in JSFreeOpPtr fop, in JSObjectPtr obj); + + boolean call(in nsIXPConnectWrappedNative wrapper, + in JSContextPtr cx, in JSObjectPtr obj, + in JSCallArgsRef args); + + boolean construct(in nsIXPConnectWrappedNative wrapper, + in JSContextPtr cx, in JSObjectPtr obj, + in JSCallArgsRef args); + + boolean hasInstance(in nsIXPConnectWrappedNative wrapper, + in JSContextPtr cx, in JSObjectPtr obj, + in jsval val, out boolean bp); + + void postCreatePrototype(in JSContextPtr cx, in JSObjectPtr proto); +}; + +%{ C++ + +#include "nsAutoPtr.h" + +#define NS_XPCCLASSINFO_IID \ +{ 0x43b67f01, 0xd4ce, 0x4b82, \ + { 0xb3, 0xf8, 0xeb, 0xf2, 0x13, 0x60, 0xfb, 0x7e } } + +class NS_NO_VTABLE nsXPCClassInfo : public nsIClassInfo, + public nsIXPCScriptable +{ +public: + NS_DECLARE_STATIC_IID_ACCESSOR(NS_XPCCLASSINFO_IID) + + NS_IMETHOD_(MozExternalRefCountType) AddRef() override = 0; + NS_IMETHOD_(MozExternalRefCountType) Release() override = 0; + + virtual void PreserveWrapper(nsISupports *aNative) = 0; +}; + +NS_DEFINE_STATIC_IID_ACCESSOR(nsXPCClassInfo, NS_XPCCLASSINFO_IID) + +inline +nsresult +CallQueryInterface(nsISupports* aSourcePtr, + RefPtrGetterAddRefs<nsXPCClassInfo> aDestPtr) +{ + return CallQueryInterface(aSourcePtr, + static_cast<nsXPCClassInfo**>(aDestPtr)); +} + +%} diff --git a/js/xpconnect/idl/nsIXPConnect.idl b/js/xpconnect/idl/nsIXPConnect.idl new file mode 100644 index 000000000..4bdc007fc --- /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); +}; diff --git a/js/xpconnect/idl/xpcIJSGetFactory.idl b/js/xpconnect/idl/xpcIJSGetFactory.idl new file mode 100644 index 000000000..a8ba5524d --- /dev/null +++ b/js/xpconnect/idl/xpcIJSGetFactory.idl @@ -0,0 +1,18 @@ +/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* 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/. */ + +#include "nsISupports.idl" + +interface nsIFactory; + +/** + * Every JS module exports a single NSGetFactory symbol which is converted into this + * functional interface type. + */ +[scriptable, function, uuid(3FE0C205-D75B-4CAC-9347-D2B855050143)] +interface xpcIJSGetFactory : nsISupports +{ + nsIFactory get(in nsCIDRef aCID); +}; diff --git a/js/xpconnect/idl/xpcIJSModuleLoader.idl b/js/xpconnect/idl/xpcIJSModuleLoader.idl new file mode 100644 index 000000000..5f66b105a --- /dev/null +++ b/js/xpconnect/idl/xpcIJSModuleLoader.idl @@ -0,0 +1,82 @@ +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* 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/. */ + +#include "nsISupports.idl" + +[ptr] native nsAXPCNativeCallContextPtr(nsAXPCNativeCallContext); + +%{C++ +#include "js/TypeDecls.h" + +class nsAXPCNativeCallContext; +%} + +[ptr] native JSObjectPtr(JSObject); + +[scriptable, uuid(4f94b21f-2920-4bd9-8251-5fb60fb054b2)] +interface xpcIJSModuleLoader : nsISupports +{ + /** + * To be called from JavaScript only. + * + * Synchronously loads and evaluates the js file located at + * aResourceURI with a new, fully privileged global object. + * + * If 'targetObj' is specified and equal to null, returns the + * module's global object. Otherwise (if 'targetObj' is not + * specified, or 'targetObj' is != null) looks for a property + * 'EXPORTED_SYMBOLS' on the new global object. 'EXPORTED_SYMBOLS' + * is expected to be an array of strings identifying properties on + * the global object. These properties will be installed as + * properties on 'targetObj', or, if 'targetObj' is not specified, + * on the caller's global object. If 'EXPORTED_SYMBOLS' is not + * found, an error is thrown. + * + * @param resourceURI A resource:// URI string to load the module from. + * @param targetObj the object to install the exported properties on. + * If this parameter is a primitive value, this method throws + * an exception. + * @returns the module code's global object. + * + * The implementation maintains a hash of registryLocation->global obj. + * Subsequent invocations of importModule with 'registryLocation' + * pointing to the same file will not cause the module to be re-evaluated, + * but the symbols in EXPORTED_SYMBOLS will be exported into the + * specified target object and the global object returned as above. + * + * (This comment is duplicated to nsIXPCComponents_Utils.) + */ + [implicit_jscontext,optional_argc] + jsval import(in AUTF8String aResourceURI, [optional] in jsval targetObj); + + /** + * Imports the JS module at aResourceURI to the JS object + * 'targetObj' (if != null) as described for importModule() and + * returns the module's global object. + */ + [noscript] JSObjectPtr importInto(in AUTF8String aResourceURI, + in JSObjectPtr targetObj, + in nsAXPCNativeCallContextPtr cc); + + /** + * Unloads the JS module at aResourceURI. Existing references to the module + * will continue to work but any subsequent import of the module will + * reload it and give new reference. If the JS module hasn't yet been imported + * then this method will do nothing. + */ + void unload(in AUTF8String aResourceURI); + + /** + * Returns true if the js file located at 'registryLocation' location has + * been loaded previously via the import method above. Returns false + * otherwise. + * + * @param resourceURI A resource:// URI string representing the location of + * the js file to be checked if it is already loaded or not. + * @returns boolean, true if the js file has been loaded via import. false + * otherwise + */ + boolean isModuleLoaded(in AUTF8String aResourceURI); +}; diff --git a/js/xpconnect/idl/xpcIJSWeakReference.idl b/js/xpconnect/idl/xpcIJSWeakReference.idl new file mode 100644 index 000000000..4c8b40b3d --- /dev/null +++ b/js/xpconnect/idl/xpcIJSWeakReference.idl @@ -0,0 +1,17 @@ +/* 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/. */ + +#include "nsISupports.idl" + +[scriptable, uuid(75767928-ecb1-4e6c-9f55-c118b297fcef)] +interface xpcIJSWeakReference : nsISupports +{ + /** + * To be called from JS only. + * + * Returns the referenced JS object or null if the JS object has + * been garbage collected. + */ + [implicit_jscontext] jsval get(); +}; diff --git a/js/xpconnect/idl/xpccomponents.idl b/js/xpconnect/idl/xpccomponents.idl new file mode 100644 index 000000000..711ea4c64 --- /dev/null +++ b/js/xpconnect/idl/xpccomponents.idl @@ -0,0 +1,732 @@ +/* -*- 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/. */ + +#include "nsISupports.idl" + +%{C++ +#include "jspubtd.h" +%} + +interface xpcIJSWeakReference; +interface nsIAddonInterposition; +interface nsIClassInfo; +interface nsIComponentManager; +interface nsICycleCollectorListener; +interface nsIJSCID; +interface nsIJSIID; +interface nsIPrincipal; +interface nsIStackFrame; + +/** +* interface of Components.interfacesByID +* (interesting stuff only reflected into JavaScript) +*/ +[scriptable, uuid(f235ef76-9919-478b-aa0f-282d994ddf76)] +interface nsIXPCComponents_InterfacesByID : nsISupports +{ +}; + +/** +* interface of Components.interfaces +* (interesting stuff only reflected into JavaScript) +*/ +[scriptable, uuid(b8c31bba-79db-4a1d-930d-4cdd68713f9e)] +interface nsIXPCComponents_Interfaces : nsISupports +{ +}; + +/** +* interface of Components.classes +* (interesting stuff only reflected into JavaScript) +*/ +[scriptable, uuid(978ff520-d26c-11d2-9842-006008962422)] +interface nsIXPCComponents_Classes : nsISupports +{ +}; + +/** +* interface of Components.classesByID +* (interesting stuff only reflected into JavaScript) +*/ +[scriptable, uuid(336a9590-4d19-11d3-9893-006008962422)] +interface nsIXPCComponents_ClassesByID : nsISupports +{ +}; + +/** +* interface of Components.results +* (interesting stuff only reflected into JavaScript) +*/ +[scriptable, uuid(2fc229a0-5860-11d3-9899-006008962422)] +interface nsIXPCComponents_Results : nsISupports +{ +}; + +/** +* interface of Components.ID +* (interesting stuff only reflected into JavaScript) +*/ +[scriptable, uuid(7994a6e0-e028-11d3-8f5d-0010a4e73d9a)] +interface nsIXPCComponents_ID : nsISupports +{ +}; + +/** +* interface of Components.Exception +* (interesting stuff only reflected into JavaScript) +*/ +[scriptable, uuid(5bf039c0-e028-11d3-8f5d-0010a4e73d9a)] +interface nsIXPCComponents_Exception : nsISupports +{ +}; + +/** +* interface of Components.Constructor +* (interesting stuff only reflected into JavaScript) +*/ +[scriptable, uuid(88655640-e028-11d3-8f5d-0010a4e73d9a)] +interface nsIXPCComponents_Constructor : nsISupports +{ +}; + +/** +* interface of object returned by Components.Constructor +* (additional interesting stuff only reflected into JavaScript) +*/ +[scriptable, uuid(c814ca20-e0dc-11d3-8f5f-0010a4e73d9a)] +interface nsIXPCConstructor : nsISupports +{ + readonly attribute nsIJSCID classID; + readonly attribute nsIJSIID interfaceID; + readonly attribute string initializer; +}; + +/** +* interface of object returned by Components.utils.Sandbox. +*/ +[scriptable, uuid(4f8ae0dc-d266-4a32-875b-6a9de71a8ce9)] +interface nsIXPCComponents_utils_Sandbox : nsISupports +{ +}; + +/** + * interface for callback to be passed to Cu.schedulePreciseGC + */ +[scriptable, function, uuid(71000535-b0fd-44d1-8ce0-909760e3953c)] +interface ScheduledGCCallback : nsISupports +{ + void callback(); +}; + +/** +* interface of Components.utils +*/ +[scriptable, uuid(86003fe3-ee9a-4620-91dc-eef8b1e58815)] +interface nsIXPCComponents_Utils : nsISupports +{ + + /* reportError is designed to be called from JavaScript only. + * + * It will report a JS Error object to the JS console, and return. It + * is meant for use in exception handler blocks which want to "eat" + * an exception, but still want to report it to the console. + * + * It must be called with one param, usually an object which was caught by + * an exception handler. If it is not a JS error object, the parameter + * is converted to a string and reported as a new error. + */ + [implicit_jscontext] void reportError(in jsval error); + + readonly attribute nsIXPCComponents_utils_Sandbox Sandbox; + + /* + * evalInSandbox is designed to be called from JavaScript only. + * + * evalInSandbox evaluates the provided source string in the given sandbox. + * It returns the result of the evaluation to the caller. + * + * var s = new C.u.Sandbox("http://www.mozilla.org"); + * var res = C.u.evalInSandbox("var five = 5; 2 + five", s); + * var outerFive = s.five; + * s.seven = res; + * var thirtyFive = C.u.evalInSandbox("five * seven", s); + */ + [implicit_jscontext,optional_argc] + jsval evalInSandbox(in AString source, in jsval sandbox, + [optional] in jsval version, + [optional] in AUTF8String filename, + [optional] in long lineNo); + + /* + * getSandboxAddonId is designed to be called from JavaScript only. + * + * getSandboxAddonId retrieves the add-on ID associated with + * a sandbox object. It will return undefined if there + * is no add-on ID attached to the sandbox. + * + * var s = C.u.Sandbox(..., { addonId: "123" }); + * var id = C.u.getSandboxAddonId(s); + */ + [implicit_jscontext] + jsval getSandboxAddonId(in jsval sandbox); + + /* + * getSandboxMetadata is designed to be called from JavaScript only. + * + * getSandboxMetadata retrieves the metadata associated with + * a sandbox object. It will return undefined if there + * is no metadata attached to the sandbox. + * + * var s = C.u.Sandbox(..., { metadata: "metadata" }); + * var metadata = C.u.getSandboxMetadata(s); + */ + [implicit_jscontext] + jsval getSandboxMetadata(in jsval sandbox); + + /* + * setSandboxMetadata is designed to be called from JavaScript only. + * + * setSandboxMetadata sets the metadata associated with + * a sandbox object. + * + * Note that the metadata object will be copied before being used. + * The copy will be performed using the structured clone algorithm. + * Note that this algorithm does not support reflectors and + * it will throw if it encounters them. + */ + [implicit_jscontext] + void setSandboxMetadata(in jsval sandbox, in jsval metadata); + + /* + * import is designed to be called from JavaScript only. + * + * Synchronously loads and evaluates the js file located at + * 'registryLocation' with a new, fully privileged global object. + * + * If 'targetObj' is specified and equal to null, returns the + * module's global object. Otherwise (if 'targetObj' is not + * specified, or 'targetObj' is != null) looks for a property + * 'EXPORTED_SYMBOLS' on the new global object. 'EXPORTED_SYMBOLS' + * is expected to be an array of strings identifying properties on + * the global object. These properties will be installed as + * properties on 'targetObj', or, if 'targetObj' is not specified, + * on the caller's global object. If 'EXPORTED_SYMBOLS' is not + * found, an error is thrown. + * + * @param resourceURI A resource:// URI string to load the module from. + * @param targetObj the object to install the exported properties on. + * If this parameter is a primitive value, this method throws + * an exception. + * @returns the module code's global object. + * + * The implementation maintains a hash of registryLocation->global obj. + * Subsequent invocations of importModule with 'registryLocation' + * pointing to the same file will not cause the module to be re-evaluated, + * but the symbols in EXPORTED_SYMBOLS will be exported into the + * specified target object and the global object returned as above. + * + * (This comment is duplicated from xpcIJSModuleLoader.) + */ + [implicit_jscontext,optional_argc] + jsval import(in AUTF8String aResourceURI, [optional] in jsval targetObj); + + /** + * Returns true if the js file located at 'registryLocation' location has + * been loaded previously via the import method above. Returns false + * otherwise. + * + * @param resourceURI A resource:// URI string representing the location of + * the js file to be checked if it is already loaded or not. + * @returns boolean, true if the js file has been loaded via import. false + * otherwise + */ + boolean isModuleLoaded(in AUTF8String aResourceURI); + + /* + * Unloads the JS module at 'registryLocation'. Existing references to the + * module will continue to work but any subsequent import of the module will + * reload it and give new reference. If the JS module hasn't yet been + * imported then this method will do nothing. + * + * @param resourceURI A resource:// URI string to unload the module from. + */ + void unload(in AUTF8String registryLocation); + + /* + * Imports global properties (like DOM constructors) into the scope, defining + * them on the caller's global. aPropertyList should be an array of property + * names. + * + * See xpc::GlobalProperties::Parse for the current list of supported + * properties. + */ + [implicit_jscontext] + void importGlobalProperties(in jsval aPropertyList); + + /* + * To be called from JS only. + * + * Return a weak reference for the given JS object. + */ + [implicit_jscontext] + xpcIJSWeakReference getWeakReference(in jsval obj); + + /* + * To be called from JS only. + * + * Force an immediate garbage collection cycle. + */ + void forceGC(); + + /* + * To be called from JS only. + * + * Force an immediate cycle collection cycle. + */ + void forceCC([optional] in nsICycleCollectorListener aListener); + + /* + * To be called from JS only. + * + * If any incremental CC is in progress, finish it. For testing. + */ + void finishCC(); + + /* + * To be called from JS only. + * + * Do some cycle collector work, with the given work budget. + * The cost of calling Traverse() on a single object is set as 1. + * For testing. + */ + void ccSlice(in long long budget); + + /* + * To be called from JS only. + * + * Return the longest cycle collector slice time since the last + * time clearMaxCCTime() was called. + */ + long getMaxCCSliceTimeSinceClear(); + + /* + * To be called from JS only. + * + * Reset the internal max slice time value used for + * getMaxCCSliceTimeSinceClear(). + */ + void clearMaxCCTime(); + + /* + * To be called from JS only. + * + * Force an immediate shrinking garbage collection cycle. + */ + void forceShrinkingGC(); + + /* + * Schedule a garbage collection cycle for a point in the future when no JS + * is running. Call the provided function once this has occurred. + */ + void schedulePreciseGC(in ScheduledGCCallback callback); + + /* + * Schedule a shrinking garbage collection cycle for a point in the future + * when no JS is running. Call the provided function once this has occured. + */ + void schedulePreciseShrinkingGC(in ScheduledGCCallback callback); + + /* + * In a debug build, unlink any ghost windows. This is only for debugging + * leaks, and can cause bad things to happen if called. + */ + void unlinkGhostWindows(); + + [implicit_jscontext] + jsval getJSTestingFunctions(); + + /* + * To be called from JS only. + * + * Call 'function', using the provided stack as the async stack responsible + * for the call, and propagate its return value or the exception it throws. + * The function is called with no arguments, and 'this' is 'undefined'. + * + * The code in the function will see the given stack frame as the + * asyncCaller of its own stack frame, instead of the current caller. + */ + [implicit_jscontext] + jsval callFunctionWithAsyncStack(in jsval function, in nsIStackFrame stack, + in AString asyncCause); + + /* + * To be called from JS only. + * + * Returns the global object with which the given object is associated. + * + * @param obj The JavaScript object whose global is to be gotten. + * @return the corresponding global. + */ + [implicit_jscontext] + jsval getGlobalForObject(in jsval obj); + + /* + * To be called from JS only. + * + * Returns the true if the object is a (scripted) proxy. + * NOTE: Security wrappers are unwrapped first before the check. + */ + [implicit_jscontext] + boolean isProxy(in jsval vobject); + + /* + * To be called from JS only. + * + * Instead of simply wrapping a function into another compartment, + * this helper function creates a native function in the target + * compartment and forwards the call to the original function. + * That call will be different than a regular JS function call in + * that, the |this| is left unbound, and all the non-native JS + * object arguments will be cloned using the structured clone + * algorithm. + * The return value is the new forwarder function, wrapped into + * the caller's compartment. + * The 3rd argument is an optional options object: + * - defineAs: the name of the property that will + * be set on the target scope, with + * the forwarder function as the value. + */ + [implicit_jscontext] + jsval exportFunction(in jsval vfunction, in jsval vscope, [optional] in jsval voptions); + + /* + * To be called from JS only. + * + * Returns an object created in |vobj|'s compartment. + * If defineAs property on the options object is a non-null ID, + * the new object will be added to vobj as a property. Also, the + * returned new object is always automatically waived (see waiveXrays). + */ + [implicit_jscontext] + jsval createObjectIn(in jsval vobj, [optional] in jsval voptions); + + /* + * To be called from JS only. + * + * Ensures that all functions come from vobj's scope (and aren't cross + * compartment wrappers). + */ + [implicit_jscontext] + void makeObjectPropsNormal(in jsval vobj); + + /** + * Determines whether this object is backed by a DeadObjectProxy. + * + * Dead-wrapper objects hold no other objects alive (they have no outgoing + * reference edges) and will throw if you touch them (e.g. by + * reading/writing a property). + */ + bool isDeadWrapper(in jsval obj); + + /** + * Determines whether this object is a cross-process wrapper. + */ + bool isCrossProcessWrapper(in jsval obj); + + /** + * CPOWs can have user data attached to them. This data originates + * in the local process via the + * nsIRemoteTagService.getRemoteObjectTag method. It's sent along + * with the CPOW to the remote process, where it can be fetched + * with this function, getCrossProcessWrapperTag. + */ + ACString getCrossProcessWrapperTag(in jsval obj); + + /** + * If CPOWs are disabled for browser code via the + * dom.ipc.cpows.forbid-unsafe-from-browser preferences, then only + * add-ons can use CPOWs. This function allows a non-addon scope + * to opt into CPOWs. It's necessary for the implementation of + * RemoteAddonsParent.jsm. + */ + void permitCPOWsInScope(in jsval obj); + + /* + * To be called from JS only. This is for Gecko internal use only, and may + * disappear at any moment. + * + * Forces a recomputation of all wrappers in and out of the compartment + * containing |vobj|. If |vobj| is not an object, all wrappers system-wide + * are recomputed. + */ + [implicit_jscontext] + void recomputeWrappers([optional] in jsval vobj); + + /* + * To be called from JS only. This is for Gecko internal use only, and may + * disappear at any moment. + * + * Enables Xray vision for same-compartment access for the compartment + * indicated by |vscope|. All outgoing wrappers are recomputed. + */ + [implicit_jscontext] + void setWantXrays(in jsval vscope); + + /* + * For gecko internal automation use only. Calling this in production code + * would result in security vulnerabilities, so it will crash if used outside + * of automation. + */ + [implicit_jscontext] + void forcePermissiveCOWs(); + + /* + * Forces the usage of a privileged |Components| object for a potentially- + * unprivileged scope. This will crash if used outside of automation. + */ + [implicit_jscontext] + void forcePrivilegedComponentsForScope(in jsval vscope); + + /* + * This seemingly-paradoxical API allows privileged code to explicitly give + * unprivileged code a reference to its own Components object (whereas it's + * normally hidden away on a scope chain visible only to XBL methods). See + * also SpecialPowers.getComponents. + */ + [implicit_jscontext] + jsval getComponentsForScope(in jsval vscope); + + /* + * Dispatches a runnable to the current/main thread. If |scope| is passed, + * the runnable will be dispatch in the compartment of |scope|, which + * affects which error reporter gets called. + */ + [implicit_jscontext] + void dispatch(in jsval runnable, [optional] in jsval scope); + + /* + * To be called from JS only. + * + * These are the set of JSContext options that privileged script + * is allowed to control for the purposes of testing. These + * options should be kept in sync with what's controllable in the + * jsshell and by setting prefs in nsJSEnvironment. + * + * NB: Assume that getting any of these attributes is relatively + * cheap, but setting any of them is relatively expensive. + */ + [implicit_jscontext] + attribute boolean strict; + + [implicit_jscontext] + attribute boolean werror; + + [implicit_jscontext] + attribute boolean strict_mode; + + [implicit_jscontext] + attribute boolean ion; + + [implicit_jscontext] + void setGCZeal(in long zeal); + + [implicit_jscontext] + void nukeSandbox(in jsval obj); + + /* + * API to dynamically block script for a given global. This takes effect + * immediately, unlike other APIs that only affect newly-created globals. + * + * The machinery here maintains a counter, and allows script only if each + * call to blockScriptForGlobal() has been matched with a call to + * unblockScriptForGlobal(). The caller _must_ make sure never to call + * unblock() more times than it calls block(), since that could potentially + * interfere with another consumer's script blocking. + */ + + [implicit_jscontext] + void blockScriptForGlobal(in jsval global); + + [implicit_jscontext] + void unblockScriptForGlobal(in jsval global); + + /** + * Check whether the given object is an XrayWrapper. + */ + bool isXrayWrapper(in jsval obj); + + /** + * Waive Xray on a given value. Identity op for primitives. + */ + [implicit_jscontext] + jsval waiveXrays(in jsval aVal); + + /** + * Strip off Xray waivers on a given value. Identity op for primitives. + */ + [implicit_jscontext] + jsval unwaiveXrays(in jsval aVal); + + /** + * Gets the name of the JSClass of the object. + * + * if |aUnwrap| is true, all wrappers are unwrapped first. Unless you're + * specifically trying to detect whether the object is a proxy, this is + * probably what you want. + */ + [implicit_jscontext] + string getClassName(in jsval aObj, in bool aUnwrap); + + /** + * Get a DOM classinfo for the given classname. Only some class + * names are supported. + */ + nsIClassInfo getDOMClassInfo(in AString aClassName); + + /** + * Gets the incument global for the execution of this function. For internal + * and testing use only. + * + * If |callback| is passed, it is invoked with the incumbent global as its + * sole argument. This allows the incumbent global to be measured in callback + * environments with no scripted frames on the stack. + */ + [implicit_jscontext] + jsval getIncumbentGlobal([optional] in jsval callback); + + /** + * Forces the generation of an XPCWrappedJS for a given object. For internal + * and testing use only. This is only useful to set up wrapper map conditions + * for a testcase. The return value is not an XPCWrappedJS itself, but an + * opaque nsISupports holder that keeps the underlying XPCWrappedJS alive. + * + * if |scope| is passed, the XPCWrappedJS is generated in the scope of that object. + */ + [implicit_jscontext] + nsISupports generateXPCWrappedJS(in jsval obj, [optional] in jsval scope); + + /** + * Retrieve the last time, in microseconds since epoch, that a given + * watchdog-related event occured. + * + * Valid categories: + * "ContextStateChange" - Context switching between active and inactive states + * "WatchdogWakeup" - Watchdog waking up from sleeping + * "WatchdogHibernateStart" - Watchdog begins hibernating + * "WatchdogHibernateStop" - Watchdog stops hibernating + */ + PRTime getWatchdogTimestamp(in AString aCategory); + + [implicit_jscontext] + jsval getJSEngineTelemetryValue(); + + /* + * Clone an object into a scope. + * The 3rd argument is an optional options object: + * - cloneFunctions: boolean. If true, functions in the value are + * wrapped in a function forwarder that appears to be a native function in + * the content scope. Defaults to false. + * - wrapReflectors: boolean. If true, DOM objects are passed through the + * clone directly with cross-compartment wrappers. Otherwise, the clone + * fails when such an object is encountered. Defaults to false. + */ + [implicit_jscontext] + jsval cloneInto(in jsval value, in jsval scope, [optional] in jsval options); + + /* + * When C++-Implemented code does security checks, it can generally query + * the subject principal (i.e. the principal of the most-recently-executed + * script) in order to determine the responsible party. However, when an API + * is implemented in JS, this doesn't work - the most-recently-executed + * script is always the System-Principaled API implementation. So we need + * another mechanism. + * + * Hence the notion of the "WebIDL Caller". If the current Entry Script on + * the Script Settings Stack represents the invocation of JS-implemented + * WebIDL, this API returns the principal of the caller at the time + * of invocation. Otherwise (i.e. outside of JS-implemented WebIDL), this + * function throws. If it throws, you probably shouldn't be using it. + */ + nsIPrincipal getWebIDLCallerPrincipal(); + + /* + * Gets the principal of a script object, after unwrapping any cross- + * compartment wrappers. + */ + [implicit_jscontext] + nsIPrincipal getObjectPrincipal(in jsval obj); + + /* + * Gets the URI or identifier string associated with an object's + * compartment (the same one used by the memory reporter machinery). + * + * Unwraps cross-compartment wrappers first. + * + * The string formats and values may change at any time. Do not depend on + * this from addon code. + */ + [implicit_jscontext] + ACString getCompartmentLocation(in jsval obj); + + [implicit_jscontext] + void setAddonInterposition(in ACString addonId, in nsIAddonInterposition interposition); + + /* + * Enables call interpositions from addon scopes to any functions in the scope of |target|. + */ + [implicit_jscontext] + void setAddonCallInterposition(in jsval target); + + [implicit_jscontext] + void allowCPOWsInAddon(in ACString addonId, in bool allow); + + /* + * Return a fractional number of milliseconds from process + * startup, measured with a monotonic clock. + */ + double now(); +}; + +/** +* Interface for the 'Components' object. +* +* The first interface contains things that are available to non-chrome XBL code +* that runs in a scope with an nsExpandedPrincipal. The second interface +* includes members that are only exposed to chrome. +*/ + +[scriptable, uuid(eeeada2f-86c0-4609-b2bf-4bf2351b1ce6)] +interface nsIXPCComponentsBase : nsISupports +{ + readonly attribute nsIXPCComponents_Interfaces interfaces; + readonly attribute nsIXPCComponents_InterfacesByID interfacesByID; + readonly attribute nsIXPCComponents_Results results; + + boolean isSuccessCode(in nsresult result); + +}; + +[scriptable, uuid(aa28aaf6-70ce-4b03-9514-afe43c7dfda8)] +interface nsIXPCComponents : nsIXPCComponentsBase +{ + readonly attribute nsIXPCComponents_Classes classes; + readonly attribute nsIXPCComponents_ClassesByID classesByID; + // Will return null if there is no JS stack right now. + readonly attribute nsIStackFrame stack; + readonly attribute nsIComponentManager manager; + readonly attribute nsIXPCComponents_Utils utils; + + readonly attribute nsIXPCComponents_ID ID; + readonly attribute nsIXPCComponents_Exception Exception; + readonly attribute nsIXPCComponents_Constructor Constructor; + + [implicit_jscontext] + // A javascript component can set |returnCode| to specify an nsresult to + // be returned without throwing an exception. + attribute jsval returnCode; + + /* @deprecated Use Components.utils.reportError instead. */ + [deprecated, implicit_jscontext] void reportError(in jsval error); +}; diff --git a/js/xpconnect/idl/xpcexception.idl b/js/xpconnect/idl/xpcexception.idl new file mode 100644 index 000000000..d9f4c92fd --- /dev/null +++ b/js/xpconnect/idl/xpcexception.idl @@ -0,0 +1,30 @@ + /* -*- Mode: C; 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/. */ + +#include "nsISupports.idl" +#include "nsIException.idl" + +[scriptable, builtinclass, uuid(875e6645-e762-4da6-9ec8-bf19ab0050df)] +interface nsIXPCException : nsIException +{ + // inherits methods from nsIException + + void initialize(in AUTF8String aMessage, + in nsresult aResult, + in AUTF8String aName, + in nsIStackFrame aLocation, + in nsISupports aData); +}; + +/* this goes into the C++ header verbatim. */ +%{ C++ +/********************************************************/ +// {5632BF70-51EC-11d3-9896-006008962422} +#define NS_XPCEXCEPTION_CID \ +{ 0x5632bf70, 0x51ec, 0x11d3, \ + { 0x98, 0x96, 0x0, 0x60, 0x8, 0x96, 0x24, 0x22 } } +%} + diff --git a/js/xpconnect/idl/xpcjsid.idl b/js/xpconnect/idl/xpcjsid.idl new file mode 100644 index 000000000..602d9b8e1 --- /dev/null +++ b/js/xpconnect/idl/xpcjsid.idl @@ -0,0 +1,47 @@ +/* -*- 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/. */ + +#include "nsISupports.idl" + +[ptr] native const_nsID_ptr(const nsID); + +[builtinclass, scriptable, uuid(62883d14-4146-4039-94f5-a5e1e1a51a15)] +interface nsIJSID : nsISupports +{ + readonly attribute string name; + readonly attribute string number; + readonly attribute boolean valid; + + boolean equals(in nsIJSID other); + string toString(); + + [noscript] void initialize(in string idString); + + // returns a pointer to the internal nsID. this pointer is only valid + // while the nsIJSID object remains alive! + [notxpcom] const_nsID_ptr getID(); +}; + +[builtinclass, scriptable, uuid(e76ec564-a080-4705-8609-384c755ec91e)] +interface nsIJSIID : nsIJSID +{ +}; + +[builtinclass, scriptable, uuid(bf5eb086-9eaa-4694-aec3-fe4aac6119bd)] +interface nsIJSCID : nsIJSID +{ + [implicit_jscontext,optional_argc] jsval createInstance([optional] in jsval iid); + [implicit_jscontext,optional_argc] jsval getService([optional] in jsval iid); +}; + +/* this goes into the C++ header verbatim. */ +%{ C++ +/********************************************************/ +// {F24A14F0-4FA1-11d3-9894-006008962422} +#define NS_JS_ID_CID \ +{ 0xf24a14f0, 0x4fa1, 0x11d3, \ + { 0x98, 0x94, 0x0, 0x60, 0x8, 0x96, 0x24, 0x22 } } +%} + |