The Tor Browser: js/xpconnect/idl/xpccomponents.idl@6474c204b198 (annotated)

js/xpconnect/idl/xpccomponents.idl@6474c204b198 (annotated)

js/xpconnect/idl/xpccomponents.idl

Wed, 31 Dec 2014 06:09:35 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Wed, 31 Dec 2014 06:09:35 +0100
changeset 0: 6474c204b198
permissions: -rw-r--r--

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

 /* -*- 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 nsIComponentManager;
 interface nsIJSCID;
 interface nsIJSIID;
 interface nsIPrincipal;
 interface nsIStackFrame;
 /**
 * interface of Components.interfacesByID
 * (interesting stuff only reflected into JavaScript)
 */
 [scriptable, uuid(c99cffac-5aed-4267-ad2f-f4a4c9d4a081)]
 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(45b80e00-fb0d-439e-b7bf-54f24af0c4a6)]
 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);
     /*
      * 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);
     /*
      * 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();
     /*
      * 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();
     /**
      * Return the keys in a weak map.  This operation is
      * non-deterministic because it is affected by the scheduling of the
      * garbage collector and the cycle collector.
      *
      * This should only be used to write tests of the interaction of
      * the GC and CC with weak maps.
      *
      * @param aMap weak map or other JavaScript value
      * @returns If aMap is a weak map object, return the keys of the weak
                 map as an array.  Otherwise, return undefined.
      */
     [implicit_jscontext]
     jsval nondeterministicGetWeakMapKeys(in jsval aMap);
     [implicit_jscontext]
     jsval getJSTestingFunctions();
     /*
      * 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);
     /*
      * Similar to evalInSandbox except this one is used to eval a script in the
      * scope of a window. Also note, that the return value and the possible exceptions
      * in the script are structured cloned, unless they are natives (then they are just
      * wrapped).
      * Principal of the caller must subsume the target's.
      */
     [implicit_jscontext]
     jsval evalInWindow(in AString source, in jsval window);
     /*
      * 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);
     /*
      * 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);
     /*
      * 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:
       *   "RuntimeStateChange"      - Runtime 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:
      * - cloneFunction: boolean. If true, any function in the value is are
      *   wrapped in a function forwarder that appears to be a native function in
      *   the content scope.
      */
     [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);
 };
 /**
 * 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;
     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]
     readonly attribute jsval                            lastResult;
     [implicit_jscontext]
     attribute jsval                                     returnCode;
     /* @deprecated Use Components.utils.reportError instead. */
     [deprecated, implicit_jscontext] void reportError(in jsval error);
 };

The Tor Browser / annotate

js/xpconnect/idl/xpccomponents.idl@6474c204b198 (annotated)

js/xpconnect/idl/xpccomponents.idl