gecko/js/xpconnect/idl/xpccomponents.idl
Bobby Holley a9060fc081 Bug 870043 - Add a script-accessible statistics for various watchdog events. r=mrbkap
We need this even for testing wakeups, because we can't be certain that any
given operation callback was necessarily triggered from the watchdog thread
(since it's triggered from within the JS engine in various cases as well).
2013-07-24 15:33:31 -07:00

477 lines
15 KiB
Plaintext

/* -*- 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"
#include "xpcexception.idl"
#include "xpcjsid.idl"
#include "nsIComponentManager.idl"
%{C++
#include "jspubtd.h"
%}
interface xpcIJSWeakReference;
interface nsIClassInfo;
/**
* 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(35d5b0e5-9b29-48de-9f79-d2534b497435)]
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);
/* lookupMethod is designed to be called from JavaScript only.
*
* It returns a method looking only at the idl interfaces and
* ignores any overrides or resolvers that might be in place for
* a given scriptable wrapped native.
* It must be called with two params: an object and a method name.
* It returns a function object or throws an exception on error.
* This method exists only to solve mozilla browser problems
* when chrome attempts to lookup and call methods in content
* and *must* not get confused by method properties that have been
* replaced in the content JS code. This method is not recommended for
* any other use.
*/
[implicit_jscontext]
jsval lookupMethod(in jsval obj, in jsval name);
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 jsval filename,
[optional] in long lineNo);
/*
* 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);
/*
* 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);
/**
* 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 an object created in |vobj|'s compartment.
*/
[implicit_jscontext]
jsval createObjectIn(in jsval vobj);
/*
* To be called from JS only.
*
* Returns an array created in |vobj|'s compartment.
*/
[implicit_jscontext]
jsval createArrayIn(in jsval vobj);
/*
* To be called from JS only.
*
* Returns a date given timestamp |msec| created in |vobj|'s compartment.
*/
[implicit_jscontext]
jsval createDateIn(in jsval vobj, in long long msec);
/*
* 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);
/*
* 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);
/**
* 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);
/**
* 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);
};
/**
* interface of JavaScript's 'Components' object
*/
[scriptable, uuid(8406dedb-23cc-42db-9f69-1f18785091b5)]
interface nsIXPCComponents : nsISupports
{
readonly attribute nsIXPCComponents_Interfaces interfaces;
readonly attribute nsIXPCComponents_InterfacesByID interfacesByID;
readonly attribute nsIXPCComponents_Classes classes;
readonly attribute nsIXPCComponents_ClassesByID classesByID;
readonly attribute nsIStackFrame stack;
readonly attribute nsIXPCComponents_Results results;
readonly attribute nsIComponentManager manager;
readonly attribute nsIXPCComponents_Utils utils;
readonly attribute nsIXPCComponents_ID ID;
readonly attribute nsIXPCComponents_Exception Exception;
readonly attribute nsIXPCComponents_Constructor Constructor;
boolean isSuccessCode(in nsresult result);
/* @deprecated Use Components.utils.lookupMethod instead.
* (But are you sure you really want this method any more?
* See http://developer-test.mozilla.org/en/docs/XPCNativeWrapper )
*/
[deprecated,implicit_jscontext]
jsval lookupMethod(in jsval obj, in jsval name);
/* @deprecated Use Components.utils.reportError instead. */
[deprecated, implicit_jscontext] void reportError(in jsval error);
/* 'lastResult' is accessible via JavaScript only */
/* 'returnCode' is accessible via JavaScript only */
};