Interface nsIXPCComponents_UtilsType

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.

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.

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.

To be called from JS only.

Reset the internal max slice time value used for getMaxCCSliceTimeSinceClear().

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.

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.

Create a commandline object.

Returns

a new nsICommandLine instance.

Create a command params object.

Create a document encoder object.

Create an HTML copy encoder object.

Create a loadcontext object.

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).

Create a persistent property object.

Create a private loadcontext object.

Create a spellchecker object.

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.

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);

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.

To be called from JS only.

If any incremental CC is in progress, finish it. For testing.

To be called from JS only.

Force an immediate cycle collection cycle.

To be called from JS only.

Force an immediate garbage collection cycle.

To be called from JS only.

Force an immediate shrinking garbage collection cycle.

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.

Get a DOM classinfo for the given classname. Only some class names are supported.

Returns a name for the given function or object which is useful for debugging. It will be very similar to the name displayed in call stacks. Objects which contain a single enumerable property which is a function will generate a name based on that function. Any other non-function objects will return "nonfunction".

Returns an object containing filename and lineNumber properties describing the source location of the given function.

To be called from JS only.

Returns the global object with which the given object is associated.

Returns

the corresponding global.

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.

To be called from JS only.

Return the longest cycle collector slice time since the last time clearMaxCCTime() was called.

Gets the principal of a script object, after unwrapping any cross- compartment wrappers.

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.

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);

Get the sandbox for running JS-implemented UA widgets (video controls etc.), hosted inside UA-created Shadow DOM.

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

To be called from JS only.

Return a weak reference for the given JS object.

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.

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.

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.

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.

In an NS_FREE_PERMANENT_DATA build, intentionally leak a C++ object. This is needed to test leak checking.

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).

Returns true if the ESM is loaded into the system global previously via the ChromeUtils.importESModule method etc. Returns false otherwise.

Returns true if the JSM is loaded into the system global previously via the import method above. Returns false otherwise.

Returns true if the JSM is loaded into the system global previously via the import method above, or corresponding ESM is loaded. Returns false otherwise.

Returns

boolean, true if the js file has been loaded via import. false otherwise

Check whether the given object is an opaque wrapper (PermissiveXrayOpaque).

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.

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(); }

Check whether the given object is an XrayWrapper.

To be called from JS only.

Ensures that all functions come from vobj's scope (and aren't cross compartment wrappers).

Return a fractional number of milliseconds from process startup, measured with a monotonic clock.

Prints the provided message to stderr.

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.

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.

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.

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.

Schedule a garbage collection cycle for a point in the future when no JS is running. Call the provided function once this has occurred.

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.

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.

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.

In a debug build, unlink any ghost windows. This is only for debugging leaks, and can cause bad things to happen if called.

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.

Strip off Xray waivers on a given value. Identity op for primitives.

Waive Xray on a given value. Identity op for primitives.