diff options
Diffstat (limited to 'js/xpconnect/idl')
| -rw-r--r-- | js/xpconnect/idl/moz.build | 16 | ||||
| -rw-r--r-- | js/xpconnect/idl/mozIJSSubScriptLoader.idl | 55 | ||||
| -rw-r--r-- | js/xpconnect/idl/nsIXPCScriptable.idl | 121 | ||||
| -rw-r--r-- | js/xpconnect/idl/nsIXPConnect.idl | 273 | ||||
| -rw-r--r-- | js/xpconnect/idl/xpcIJSGetFactory.idl | 18 | ||||
| -rw-r--r-- | js/xpconnect/idl/xpcIJSWeakReference.idl | 17 | ||||
| -rw-r--r-- | js/xpconnect/idl/xpccomponents.idl | 727 |
7 files changed, 1227 insertions, 0 deletions
diff --git a/js/xpconnect/idl/moz.build b/js/xpconnect/idl/moz.build new file mode 100644 index 0000000000..5e6feb4c24 --- /dev/null +++ b/js/xpconnect/idl/moz.build @@ -0,0 +1,16 @@ +# -*- 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", + "nsIXPConnect.idl", + "nsIXPCScriptable.idl", + "xpccomponents.idl", + "xpcIJSGetFactory.idl", + "xpcIJSWeakReference.idl", +] + +XPIDL_MODULE = "xpconnect" diff --git a/js/xpconnect/idl/mozIJSSubScriptLoader.idl b/js/xpconnect/idl/mozIJSSubScriptLoader.idl new file mode 100644 index 0000000000..aad85e5cd3 --- /dev/null +++ b/js/xpconnect/idl/mozIJSSubScriptLoader.idl @@ -0,0 +1,55 @@ +/* -*- 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; + +/** + * Interface for synchronous script loads from local file: or jar: sources. + * For asynchronous script loads, ChromeUtils.compileScript() should be used + * instead. + */ +[scriptable, builtinclass, 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 UTF-8-encoded sub-script, it MUST be either a + * file:, resource:, blob:, 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. + * @retval rv the value returned by the sub-script + */ + [implicit_jscontext] + jsval loadSubScript(in AString url, [optional] in jsval obj); + + /** + * This method should only be called from JS! + * In JS, the signature looks like: + * rv = loadSubScript (url, optionsObject) + * @param url the url of the UTF-8-encoded sub-script, which MUST be either + * a file:, resource:, blob:, or chrome: url, and MUST be local. + * @param optionsObject an object with parameters. Valid parameters are: + * - 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. + * - wantReturnValue: If true, the script will return + * the value of the last statement that it evaluated. + * This option disables most optimizations in the + * top-level scope, and should be avoided if at all + * possible. Defaults to false. + * @retval rv the value returned by the sub-script + */ + [implicit_jscontext] + jsval loadSubScriptWithOptions(in AString url, in jsval options); +}; diff --git a/js/xpconnect/idl/nsIXPCScriptable.idl b/js/xpconnect/idl/nsIXPCScriptable.idl new file mode 100644 index 0000000000..e4d5b089d4 --- /dev/null +++ b/js/xpconnect/idl/nsIXPCScriptable.idl @@ -0,0 +1,121 @@ +/* -*- 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" + +namespace JS { +class CallArgs; +} + +%} + +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); +[ptr] native JSClassPtr(const JSClass); + native JSMutableHandleIdVector(JS::MutableHandleIdVector); + +%{ C++ + // nsIXPCScriptable flags (only 32 bits available!). They are defined via + // #defines so they can be used in #ifndef guards in xpc_map_end.h. + + #define XPC_SCRIPTABLE_WANT_PRECREATE (1 << 0) + // (1 << 1) is unused + // (1 << 2) is unused + // (1 << 3) is unused + #define XPC_SCRIPTABLE_WANT_NEWENUMERATE (1 << 4) + #define XPC_SCRIPTABLE_WANT_RESOLVE (1 << 5) + #define XPC_SCRIPTABLE_WANT_FINALIZE (1 << 6) + #define XPC_SCRIPTABLE_WANT_CALL (1 << 7) + #define XPC_SCRIPTABLE_WANT_CONSTRUCT (1 << 8) + #define XPC_SCRIPTABLE_WANT_HASINSTANCE (1 << 9) + #define XPC_SCRIPTABLE_USE_JSSTUB_FOR_ADDPROPERTY (1 << 10) + #define XPC_SCRIPTABLE_USE_JSSTUB_FOR_DELPROPERTY (1 << 11) + // (1 << 12) is unused + #define XPC_SCRIPTABLE_DONT_ENUM_QUERY_INTERFACE (1 << 13) + // (1 << 14) is unused + // (1 << 15) is unused + #define XPC_SCRIPTABLE_ALLOW_PROP_MODS_DURING_RESOLVE (1 << 16) + // (1 << 17) is unused + #define XPC_SCRIPTABLE_IS_GLOBAL_OBJECT (1 << 18) + #define XPC_SCRIPTABLE_DONT_REFLECT_INTERFACE_NAMES (1 << 19) +%} + +/** + * 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. + */ +[builtinclass, uuid(19b70b26-7c3f-437f-a04a-2a8f9e28b617)] +interface nsIXPCScriptable : nsISupports +{ + readonly attribute AUTF8String className; + [notxpcom,nostdcall] uint32_t getScriptableFlags(); + [notxpcom,nostdcall] JSClassPtr getJSClass(); + + void preCreate(in nsISupports nativeObj, in JSContextPtr cx, + in JSObjectPtr globalObj, out JSObjectPtr parentObj); + + boolean newEnumerate(in nsIXPConnectWrappedNative wrapper, + in JSContextPtr cx, in JSObjectPtr obj, + in JSMutableHandleIdVector properties, + in boolean enumerableOnly); + + 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); + +%{ C++ + #define GET_IT(f_, c_) \ + bool f_() { \ + return 0 != (GetScriptableFlags() & XPC_SCRIPTABLE_##c_); \ + } + + GET_IT(WantPreCreate, WANT_PRECREATE) + GET_IT(WantNewEnumerate, WANT_NEWENUMERATE) + GET_IT(WantResolve, WANT_RESOLVE) + GET_IT(WantFinalize, WANT_FINALIZE) + GET_IT(WantCall, WANT_CALL) + GET_IT(WantConstruct, WANT_CONSTRUCT) + GET_IT(WantHasInstance, WANT_HASINSTANCE) + GET_IT(UseJSStubForAddProperty, USE_JSSTUB_FOR_ADDPROPERTY) + GET_IT(UseJSStubForDelProperty, USE_JSSTUB_FOR_DELPROPERTY) + GET_IT(DontEnumQueryInterface, DONT_ENUM_QUERY_INTERFACE) + GET_IT(AllowPropModsDuringResolve, ALLOW_PROP_MODS_DURING_RESOLVE) + GET_IT(IsGlobalObject, IS_GLOBAL_OBJECT) + GET_IT(DontReflectInterfaceNames, DONT_REFLECT_INTERFACE_NAMES) + + #undef GET_IT +%} +}; diff --git a/js/xpconnect/idl/nsIXPConnect.idl b/js/xpconnect/idl/nsIXPConnect.idl new file mode 100644 index 0000000000..7c5fe7a489 --- /dev/null +++ b/js/xpconnect/idl/nsIXPConnect.idl @@ -0,0 +1,273 @@ +/* -*- 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/CompileOptions.h" +#include "js/TypeDecls.h" +#include "mozilla/Attributes.h" +#include "xptinfo.h" +#include "nsCOMPtr.h" + +class nsWrapperCache; +%} + +/***************************************************************************/ + +// NB: jsval and jsid are declared in nsrootidl.idl + +[ptr] native JSContextPtr(JSContext); +[ptr] native JSObjectPtr(JSObject); +[ptr] native JSScriptPtr(JSScript); +[ptr] native nsWrapperCachePtr(nsWrapperCache); + native JSHandleId(JS::Handle<jsid>); +[ref] native const_JSReadOnlyCompileOptionsRef(const JS::ReadOnlyCompileOptions); + +/***************************************************************************/ + +// forward declarations... +interface nsIPrincipal; +interface nsIClassInfo; +interface nsIVariant; +interface nsIObjectInputStream; +interface nsIObjectOutputStream; + +/***************************************************************************/ +[builtinclass, uuid(73e6ff4a-ab99-4d99-ac00-ba39ccb8e4d7)] +interface nsIXPConnectJSObjectHolder : nsISupports +{ + [notxpcom, nostdcall] JSObjectPtr GetJSObject(); +}; + +[builtinclass, uuid(e787be29-db5d-4a45-a3d6-1de1d6b85c30)] +interface nsIXPConnectWrappedNative : nsIXPConnectJSObjectHolder +{ + /* attribute 'JSObject' inherited from nsIXPConnectJSObjectHolder */ + + void debugDump(in short depth); + +%{C++ + /** + * Faster access to the native object from C++. Will never return null. + */ + nsISupports* Native() const { return mIdentity; } + +protected: + nsCOMPtr<nsISupports> mIdentity; +public: +%} +}; + +[builtinclass, uuid(3a01b0d6-074b-49ed-bac3-08c76366cae4)] +interface nsIXPConnectWrappedJS : nsIXPConnectJSObjectHolder +{ + /* attribute 'JSObject' inherited from nsIXPConnectJSObjectHolder */ + readonly attribute nsIIDPtr InterfaceIID; + + // Returns the global object for our JS object. If this object is a + // cross-compartment wrapper, returns the compartment's first global. + // The global we return is guaranteed to be same-compartment with the + // object. + // Note: this matches the GetJSObject() signature. + [notxpcom, nostdcall] JSObjectPtr GetJSObjectGlobal(); + + 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 +{ +}; + +/***************************************************************************/ + + +[noscript, builtinclass, uuid(768507b5-b981-40c7-8276-f6a1da502a24)] +interface nsIXPConnect : nsISupports +{ +%{ C++ + // This gets a non-addref'd pointer. + static nsIXPConnect* XPConnect(); +%} + + /** + * 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 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); + + 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.... + + 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. + * @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); + + [noscript] void writeScript(in nsIObjectOutputStream aStream, + in JSContextPtr aJSContext, + in JSScriptPtr aJSScript); + + [noscript] JSScriptPtr readScript(in nsIObjectInputStream aStream, + in JSContextPtr aJSContext, + in const_JSReadOnlyCompileOptionsRef aOptions); + + [infallible] readonly attribute boolean isShuttingDown; +}; diff --git a/js/xpconnect/idl/xpcIJSGetFactory.idl b/js/xpconnect/idl/xpcIJSGetFactory.idl new file mode 100644 index 0000000000..a8ba5524d0 --- /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/xpcIJSWeakReference.idl b/js/xpconnect/idl/xpcIJSWeakReference.idl new file mode 100644 index 0000000000..a9d2cc7444 --- /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, builtinclass, 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 0000000000..43c1b52ebb --- /dev/null +++ b/js/xpconnect/idl/xpccomponents.idl @@ -0,0 +1,727 @@ +/* -*- 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 nsIClassInfo; +interface nsICommandParams; +interface nsIComponentManager; +interface nsICycleCollectorListener; +interface nsIDocumentEncoder; +interface nsIEditorSpellCheck; +interface nsIFile; +interface nsILoadContext; +interface nsIPersistentProperties; +interface nsIURI; +interface nsIPrincipal; +interface nsIStackFrame; +webidl Element; + +/** +* interface of Components.interfaces +* (interesting stuff only reflected into JavaScript) +*/ +[scriptable, builtinclass, uuid(b8c31bba-79db-4a1d-930d-4cdd68713f9e)] +interface nsIXPCComponents_Interfaces : nsISupports +{ +}; + +/** +* interface of Components.classes +* (interesting stuff only reflected into JavaScript) +*/ +[scriptable, builtinclass, uuid(978ff520-d26c-11d2-9842-006008962422)] +interface nsIXPCComponents_Classes : nsISupports +{ +}; + +/** +* interface of Components.results +* (interesting stuff only reflected into JavaScript) +*/ +[scriptable, builtinclass, uuid(2fc229a0-5860-11d3-9899-006008962422)] +interface nsIXPCComponents_Results : nsISupports +{ +}; + +/** +* interface of Components.ID +* (interesting stuff only reflected into JavaScript) +*/ +[scriptable, builtinclass, uuid(7994a6e0-e028-11d3-8f5d-0010a4e73d9a)] +interface nsIXPCComponents_ID : nsISupports +{ +}; + +/** +* interface of Components.Exception +* (interesting stuff only reflected into JavaScript) +*/ +[scriptable, builtinclass, uuid(5bf039c0-e028-11d3-8f5d-0010a4e73d9a)] +interface nsIXPCComponents_Exception : nsISupports +{ +}; + +/** +* interface of Components.Constructor +* (interesting stuff only reflected into JavaScript) +*/ +[scriptable, builtinclass, uuid(88655640-e028-11d3-8f5d-0010a4e73d9a)] +interface nsIXPCComponents_Constructor : nsISupports +{ +}; + +/** +* interface of object returned by Components.utils.Sandbox. +*/ +[scriptable, builtinclass, 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 nsIScheduledGCCallback : nsISupports +{ + void callback(); +}; + +/** +* interface of Components.utils +*/ +[scriptable, builtinclass, 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. + * + * If called with two parameters, and the first parameter is not an + * object, the second parameter is used as the stack for the error report. + */ + [implicit_jscontext] + void reportError(in jsval error, [optional] in jsval stack); + + readonly attribute nsIXPCComponents_utils_Sandbox Sandbox; + + [implicit_jscontext] + jsval createServicesCache(); + + /* + * 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, + [optional] in bool enforceFilenameRestrictions); + + /* + * Get the sandbox for running JS-implemented UA widgets (video controls etc.), + * hosted inside UA-created Shadow DOM. + */ + [implicit_jscontext] + jsval getUAWidgetScope(in nsIPrincipal principal); + + /* + * 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. + */ + [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. + */ + [implicit_jscontext] + 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. C++ callers should use the + * nsCycleCollector_createLogger() function instead. + * + * Create an instance of the built-in cycle collector logger object. + */ + nsICycleCollectorListener createCCLogger(); + + /* + * 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. + */ + [implicit_jscontext] + 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 nsIScheduledGCCallback 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 nsIScheduledGCCallback 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(); + + /* + * In an NS_FREE_PERMANENT_DATA build, intentionally leak a C++ object. This + * is needed to test leak checking. + */ + void intentionallyLeak(); + + [implicit_jscontext] + jsval getJSTestingFunctions(); + + /** + * Returns an object containing `filename` and `lineNumber` properties + * describing the source location of the given function. + */ + [implicit_jscontext] + jsval getFunctionSourceLocation(in jsval func); + + /* + * 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 value is a remote object proxy, such as + * RemoteWindowProxy or RemoteLocationProxy, for an out-of-process frame. + * + * Remote object proxies do not grant chrome callers the same exemptions + * to the same-origin-policy that in-process wrappers typically do, so + * this can be used to determine whether access to cross-origin proxies is + * safe: + * + * if (!Cu.isRemoteProxy(frame.contentWindow)) { + * frame.contentWindow.doCrossOriginThing(); + * } + */ + bool isRemoteProxy(in jsval val); + + /* + * 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. + * + * This must not be called on chrome (system-principal) scopes. + */ + [implicit_jscontext] + void setWantXrays(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); + + /* + * Bug 1621603 - Remove strict_mode. + * + * Do not use this API! Instead use "use strict"; at the top of your JS + * file. + */ + [implicit_jscontext] + attribute boolean strict_mode; + + // Returns true if we're running in automation and certain security + // restrictions can be eased. + readonly attribute boolean isInAutomation; + + // Called by automated tests to exit immediately after we are done getting + // test results. + void exitIfInAutomation(); + + void crashIfNotInAutomation(); + + [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 opaque wrapper (PermissiveXrayOpaque). + */ + bool isOpaqueWrapper(in jsval obj); + + /** + * 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 + * realm (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 getRealmLocation(in jsval obj); + + /* + * Return a fractional number of milliseconds from process + * startup, measured with a monotonic clock. + */ + double now(); + + /* + * Reads the given file and returns its contents. If called during early + * startup, the file will be pre-read on a background thread during profile + * startup so its contents will be available the next time they're read. + * + * The file must be a text file encoded in UTF-8. Otherwise the result is + * undefined. + */ + AUTF8String readUTF8File(in nsIFile file); + + /* + * Reads the given local file URL and returns its contents. This has the + * same semantics of readUTF8File. + * Only supports file URLs or URLs that point into one of the omnijars. + */ + AUTF8String readUTF8URI(in nsIURI url); + + /* Create a spellchecker object. */ + nsIEditorSpellCheck createSpellChecker(); + + /* Create a commandline object. */ + nsISupports createCommandLine([optional] in nsIFile aWorkingDir); + + /* Create a command params object. */ + nsICommandParams createCommandParams(); + + /* Create a loadcontext object. */ + nsILoadContext createLoadContext(); + + /* Create a private loadcontext object. */ + nsILoadContext createPrivateLoadContext(); + + /* Create a persistent property object. */ + nsIPersistentProperties createPersistentProperties(); + + /* Create a document encoder object. */ + nsIDocumentEncoder createDocumentEncoder(in string contentType); + + /* Create an HTML copy encoder object. */ + nsIDocumentEncoder createHTMLCopyEncoder(); + + // These attributes are for startup testing purposes. They are not expected + // to be used for production code. + readonly attribute Array<ACString> loadedModules; + readonly attribute Array<ACString> loadedComponents; + + // These 2 functions will only return useful values if the + // "browser.startup.record" preference was true at the time the JS file + // was loaded. + ACString getModuleImportStack(in AUTF8String aLocation); + ACString getComponentLoadStack(in AUTF8String aLocation); +}; + +/** +* Interface for the 'Components' object. +*/ + +[scriptable, builtinclass, uuid(aa28aaf6-70ce-4b03-9514-afe43c7dfda8)] +interface nsIXPCComponents : nsISupports +{ + readonly attribute nsIXPCComponents_Interfaces interfaces; + readonly attribute nsIXPCComponents_Results results; + + boolean isSuccessCode(in nsresult result); + + readonly attribute nsIXPCComponents_Classes classes; + // 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; +}; |