The Tor Browser: js/jsd/idl/jsdIDebuggerService.idl@a63d609f5ebe (annotated)

js/jsd/idl/jsdIDebuggerService.idl@a63d609f5ebe (annotated)

js/jsd/idl/jsdIDebuggerService.idl

Thu, 15 Jan 2015 15:55:04 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Thu, 15 Jan 2015 15:55:04 +0100
branch: TOR_BUG_9701
changeset 9: a63d609f5ebe
permissions: -rw-r--r--

Back out 97036ab72558 which inappropriately compared turds to third parties.

 /* -*- Mode: IDL; 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"
 %{ C++
 #include "jsdebug.h"
 #include "nsAString.h"
 %}
 [ptr] native JSDContext(JSDContext);
 [ptr] native JSDObject(JSDObject);
 [ptr] native JSDProperty(JSDProperty);
 [ptr] native JSDScript(JSDScript);
 [ptr] native JSDStackFrameInfo(JSDStackFrameInfo);
 [ptr] native JSDThreadState(JSDThreadState);
 [ptr] native JSDValue(JSDValue);
 [ptr] native JSRuntime(JSRuntime);
 [ptr] native JSContext(JSContext);
 [ptr] native JSCompartment(JSCompartment);
 /* interfaces we declare in this file */
 interface jsdIDebuggerService;
 interface jsdIFilter;
 interface jsdINestCallback;
 interface jsdIFilterEnumerator;
 interface jsdIContextEnumerator;
 interface jsdIScriptEnumerator;
 interface jsdIScriptHook;
 interface jsdIErrorHook;
 interface jsdIExecutionHook;
 interface jsdICallHook;
 interface jsdIEphemeral;
 interface jsdIContext;
 interface jsdIStackFrame;
 interface jsdIScript;
 interface jsdIValue;
 interface jsdIObject;
 interface jsdIProperty;
 interface jsdIActivationCallback;
 /**
  * Debugger service. It is not a good idea to have more than one active client
  * of the debugger service.
  *
  * Note that all the APIs in this file are deprecated. All consumers of
  * these interfaces should switch to using the new Debugger API, documented
  * here: https://wiki.mozilla.org/Debugger
  */
 [scriptable, uuid(39609752-2d73-4019-a324-a374dee16d3c)]
 interface jsdIDebuggerService : nsISupports
 {
     /** Internal use only. */
     [noscript] readonly attribute JSDContext        JSDContext;
     /**
      * Called when an error or warning occurs.
      */
     attribute jsdIErrorHook     errorHook;
     /**
      * Called when a jsdIScript is created or destroyed.
      */
     attribute jsdIScriptHook    scriptHook;
     /**
      * Called when the engine encounters a breakpoint.
      */
     attribute jsdIExecutionHook breakpointHook;
     /**
      * Called when the engine encounters the debugger keyword.
      */
     attribute jsdIExecutionHook debuggerHook;
     /**
      * Called when the errorHook returns false.
      */
     attribute jsdIExecutionHook debugHook;
     /**
      * Called before the next PC is executed.
      */
     attribute jsdIExecutionHook interruptHook;
     /**
      * Called when an exception is thrown (even if it will be caught.)
      */
     attribute jsdIExecutionHook throwHook;
     /**
      * Called before and after a toplevel script is evaluated.
      */
     attribute jsdICallHook      topLevelHook;
     /**
      * Called before and after a function is called.
      */
     attribute jsdICallHook      functionHook;
     /**
      * Link native frames in call stacks.
      */
     const unsigned long ENABLE_NATIVE_FRAMES     = 0x01;
     /**
      * Normally, if a script has a 0 in JSD_SCRIPT_PROFILE_BIT it is included in
      * profile data, otherwise it is not profiled. Setting the
      * PROFILE_WHEN_SET flag reverses this convention.
      */
     const unsigned long PROFILE_WHEN_SET         = 0x02;
     /**
      * Normally, when the script in the top frame of a thread state has a 1 in
      * JSD_SCRIPT_DEBUG_BIT, the execution hook is ignored. Setting the
      * DEBUG_WHEN_SET flag reverses this convention.
      */
     const unsigned long DEBUG_WHEN_SET           = 0x04;
     /**
      * When this flag is set the internal call hook will collect profile data.
      */
     const unsigned long COLLECT_PROFILE_DATA     = 0x08;
     /**
      * When this flag is set, stack frames that are disabled for debugging
      * will not appear in the call stack chain.
      */
     const unsigned long HIDE_DISABLED_FRAMES     = 0x10;
     /**
      * When this flag is set, the debugger will only check the
      * JSD_SCRIPT_DEBUG_BIT on the top (most recent) stack frame. This
      * makes it possible to stop in an enabled frame which was called from
      * a stack that contains a disabled frame.
      *
      * When this flag is *not* set, any stack that contains a disabled frame
      * will not be debugged (the execution hook will not be invoked.)
      *
      * This only applies when the reason for calling the hook would have
      * been TYPE_INTERRUPTED or TYPE_THROW. TYPE_BREAKPOINT,
      * TYPE_DEBUG_REQUESTED, and TYPE_DEBUGGER_KEYWORD always stop, regardless
      * of this setting, as long as the top frame is not disabled.
      *
      * If HIDE_DISABLED_FRAMES is set, this is effectively set as well.
      */
     const unsigned long MASK_TOP_FRAME_ONLY     = 0x20;
     /**
      * This flag has been retired, do not re-use. It previously provided a hook
      * for object allocation.
      */
     const unsigned long DISABLE_OBJECT_TRACE_RETIRED = 0x40;
     /**
      * Debugger service flags.
      */
     attribute unsigned long flags;
     /**
      * Major version number of implementation.
      */
     readonly attribute unsigned long implementationMajor;
     /**
      * Minor version number of implementation.
      */
     readonly attribute unsigned long implementationMinor;
     /**
      * Free form AUTF8String identifier for implementation.
      */
     readonly attribute AUTF8String implementationString;
     /**
      * |true| if the debugger service has been turned on. This does not
      * necessarily mean another app is actively using the service, as the
      * autostart pref may have turned the service on.
      */
     readonly attribute boolean isOn;
     /**
      * Synchronous activation of the debugger is no longer supported,
      * and will throw an exception.
      */
     void on();
     /**
      * Turn on the debugger. This function should only be called from
      * JavaScript code. The debugger will be enabled on the runtime the call is
      * made on, as determined by nsIXPCNativeCallContext.
      *
      * The debugger will be activated asynchronously, because there can be no
      * JS on the stack when code is to be re-compiled for debug mode.
      */
     void asyncOn(in jsdIActivationCallback callback);
     /**
      * Called by nsIXPConnect after it's had a chance to recompile for
      * debug mode.
      */
     [noscript] void activateDebugger(in JSRuntime rt);
     /**
      * Called by nsIXPConnect to deactivate debugger on setup failure.
      */
     [noscript] void deactivateDebugger();
     /**
      * Recompile all active scripts in the runtime for debugMode.
      */
     [noscript] void recompileForDebugMode(in JSContext cx, in JSCompartment comp, in boolean mode);
     /**
      * Turn the debugger off. This will invalidate all of your jsdIEphemeral
      * derived objects, and clear all of your breakpoints.
      */
     void off ();
     /**
      * Peek at the current pause depth of the debugger.
      *
      * @return depth Number of pause() calls still waiting to be unPause()d.
      */
     readonly attribute unsigned long pauseDepth;
     /**
      * Temporarily disable the debugger. Hooks will not be called while the
      * debugger is paused. Multiple calls to pause will increase the "pause
      * depth", and equal number of unPause calles must be made to resume
      * normal debugging.
      *
      * @return depth Number of times pause has been called since the debugger
      *               has been unpaused.
      */
     unsigned long pause();
     /**
      * Undo a pause.  Once this is called, the debugger won't start
      * getting execution callbacks until the stack is fully unwound so
      * that no JS scripts are live.  There is no way to query whether
      * there are such scripts left to unwind at a given point in time.
      *
      * @return depth The number of remaining pending pause calls.
      */
     unsigned long unPause();
     /**
      * Force the engine to perform garbage collection.
      */
     void GC();
     /**
      * Clear profile data for all scripts.
      */
     void clearProfileData();
     /**
      * Adds an execution hook filter. These filters are consulted each time one
      * of the jsdIExecutionHooks is about to be called. Filters are matched in
      * a first in, first compared fashion. The first filter to match determines
      * whether or not the hook is called. Use swapFilter to reorder existing
      * filters, and removeFilter to remove them.
      *
      * If |filter| is already present this method throws NS_ERROR_INVALID_ARG.
      *
      * @param filter Object representing the filter to add.
      * @param after  Insert |filter| after this one. Pass null to insert at
      *               the beginning.
      */
     void insertFilter(in jsdIFilter filter, in jsdIFilter after);
     /**
      * Same as insertFilter, except always add to the end of the list.
      */
     void appendFilter(in jsdIFilter filter);
     /**
      * Remove a filter.
      *
      * If |filter| is not present this method throws NS_ERROR_INVALID_ARG.
      *
      * @param filter Object representing the filter to remove. Must be the exact
      * object passed to addFilter, not just a new object with the same
      * properties.
      */
     void removeFilter(in jsdIFilter filter);
     /**
      * Swap position of two filters.
      *
      * If |filter_a| is not present, this method throws NS_ERROR_INVALID_ARG.
      * If |filter_b| is not present, filter_a is replaced by filter_b.
      * If |filter_a| == |filter_b|, then filter is refreshed.
      */
     void swapFilters(in jsdIFilter filter_a, in jsdIFilter filter_b);
     /**
      * Enumerate registered filters. This routine refreshes each filter before
      * passing them on to the enumeration function. Calling this with a null
      * |enumerator| is equivalent to jsdIService::refreshFilters.
      *
      * @param enumerator jsdIFilterEnumerator instance to be called back for the
      *                   enumeration.
      */
     void enumerateFilters(in jsdIFilterEnumerator enumerator);
     /**
      * Force the debugger to resync its internal filter cache with the
      * actual values in the jsdIFilter objects. To refresh a single filter
      * use jsdIService::swapFilters. This method is equivalent to
      * jsdIService::enumerateFilters with a null enumerator.
      */
     void refreshFilters();
     /**
      * Clear the list of filters.
      */
     void clearFilters();
     /**
      * Enumerate all known contexts.
      */
     void enumerateContexts(in jsdIContextEnumerator enumerator);
     /**
      * Enumerate all scripts the debugger knows about. Any scripts created
      * before you turned the debugger on, or after turning the debugger off
      * will not be available unless the autostart perf is set.
      *
      * @param enumerator jsdIScriptEnumerator instance to be called back for
      *                   the enumeration.
      */
     void enumerateScripts(in jsdIScriptEnumerator enumerator);
     /**
      * Clear all breakpoints in all scripts.
      */
     void clearAllBreakpoints();
     /**
      * When called from JavaScript, this method returns the jsdIValue wrapper
      * for the given value. If a wrapper does not exist one will be created.
      * When called from another language this method returns an xpconnect
      * defined error code.
      */
     jsdIValue wrapValue(in jsval value);
     /* XXX these two routines are candidates for refactoring. The only problem
      * is that it is not clear where and how they should land.
      */
     /**
      * Push a new network queue, and enter a new UI event loop.
      * @param callback jsdINestCallback instance to be called back after the
      *                 network queue has been pushed, but before the
      *                 UI loop starts.
      * @return depth returns the current number of times the event loop has been
      *               nested. your code can use it for sanity checks.
      */
     unsigned long enterNestedEventLoop(in jsdINestCallback callback);
     /**
      * Exit the current nested event loop after the current iteration completes,
      * and pop the network event queue.
      *
      * @return depth returns the current number of times the event loop has been
      *               nested. your code can use it for sanity checks.
      */
     unsigned long exitNestedEventLoop();
     /**
      * Output dump of JS heap.
      *
      * @param fileName Filename to dump the heap into.
      */
     void dumpHeap(in AUTF8String fileName);
     /**
      * Suppress console warnings about using JSD, which is a deprecated API.
      *
      * This applies only to the next call to asyncOn; any subsequent calls
      * will elicit the warning, unless you call 'acknowledgeDeprecation'
      * before each of them, too. This arrangement ensures that one add-on's
      * acknowledgement doesn't suppress warnings for other add-ons.
      */
     void acknowledgeDeprecation();
 };
 /* callback interfaces */
 /**
  * Object representing a pattern of global object and/or url the debugger should
  * ignore. The debugger service itself will not modify properties of these
  * objects.
  */
 [scriptable, uuid(9ae587cd-b78c-47f0-a612-4b3a211a6a71)]
 interface jsdIFilter : nsISupports
 {
     /**
      * These two bytes of the flags attribute are reserved for interpretation
      * by the jsdService implementation. You can do what you like with the
      * remaining flags.
      */
     const unsigned long FLAG_RESERVED_MASK = 0xFF;
     /**
      * Filters without this flag set are ignored.
      */
     const unsigned long FLAG_ENABLED       = 0x01;
     /**
      * Filters with this flag set are "pass" filters, they allow matching hooks
      * to continue. Filters without this flag block matching hooks.
      */
     const unsigned long FLAG_PASS          = 0x02;
     /**
      * FLAG_* values from above, OR'd together.
      */
     attribute unsigned long flags;
     /**
      * String representing the url pattern to be filtered. Supports limited
      * glob matching, at the beginning and end of the pattern only. For example,
      * "chrome://venkman*" filters all urls that start with chrome/venkman,
      * "*.cgi" filters all cgi's, and "http://myserver/utils.js" filters only
      * the utils.js file on "myserver". A null urlPattern matches all urls.
      *
      * The jsdIService caches this value internally, to if it changes you must
      * swap the filter with itself using jsdIService::swapFilters.
      */
     attribute AUTF8String urlPattern;
     /**
      * Line number for the start of this filter. Line numbers are one based.
      * Assigning a 0 to this attribute will tell the debugger to ignore the
      * entire file.
      */
     attribute unsigned long startLine;
     /**
      * Line number for the end of this filter. Line numbers are one based.
      * Assigning a 0 to this attribute will tell the debugger to ignore from
      * |startLine| to the end of the file.
      */
     attribute unsigned long endLine;
 };
 /**
  * Notify client code that debugMode has been activated.
  */
 [scriptable, function, uuid(6da7f5fb-3a84-4abe-9e23-8b2045960732)]
 interface jsdIActivationCallback : nsISupports
 {
     void onDebuggerActivated();
 };
 /**
  * Pass an instance of one of these to jsdIDebuggerService::enterNestedEventLoop.
  */
 [scriptable, function, uuid(88bea60f-9b5d-4b39-b08b-1c3a278782c6)]
 interface jsdINestCallback : nsISupports
 {
     /**
      * This method will be called after pre-nesting work has completed, such
      * as pushing the js context and network event queue, but before the new
      * event loop starts.
      */
     void onNest();
 };
 /**
  * Pass an instance of one of these to jsdIDebuggerService::enumerateFilters.
  */
 [scriptable, function, uuid(e391ba85-9379-4762-b387-558e38db730f)]
 interface jsdIFilterEnumerator : nsISupports
 {
     /**
      * The enumerateFilter method will be called once for every filter the
      * debugger knows about.
      */
     void enumerateFilter(in jsdIFilter filter);
 };
 /**
  * Pass an instance of one of these to jsdIDebuggerService::enumerateScripts.
  */
 [scriptable, function, uuid(4eef60c2-9bbc-48fa-b196-646a832c6c81)]
 interface jsdIScriptEnumerator : nsISupports
 {
     /**
      * The enumerateScript method will be called once for every script the
      * debugger knows about.
      */
     void enumerateScript(in jsdIScript script);
 };
 /**
  * Pass an instance of one of these to jsdIDebuggerService::enumerateContexts.
  */
 [scriptable, function, uuid(57d18286-550c-4ca9-ac33-56f12ebba91e)]
 interface jsdIContextEnumerator : nsISupports
 {
     /**
      * The enumerateContext method will be called once for every context
      * currently in use.
      */
     void enumerateContext(in jsdIContext executionContext);
 };
 /**
  * Set jsdIDebuggerService::scriptHook to an instance of one of these.
  */
 [scriptable, uuid(d030d1a2-a58a-4f19-b9e3-96da4e2cdd09)]
 interface jsdIScriptHook : nsISupports
 {
     /**
      * Called when scripts are created.
      */
     void onScriptCreated(in jsdIScript script);
     /**
      * Called when the JavaScript engine destroys a script. The jsdIScript
      * object passed in will already be invalidated.
      */
     void onScriptDestroyed(in jsdIScript script);
 };
 /**
  * Hook instances of this interface up to the
  * jsdIDebuggerService::functionHook and toplevelHook properties.
  */
 [scriptable, function, uuid(3eff1314-7ae3-4cf8-833b-c33c24a55633)]
 interface jsdICallHook : nsISupports
 {
     /**
      * TYPE_* values must be kept in sync with the JSD_HOOK_* #defines
      * in jsdebug.h.
      */
     /**
      * Toplevel script is starting.
      */
     const unsigned long TYPE_TOPLEVEL_START  = 0;
     /**
      * Toplevel script has completed.
      */
     const unsigned long TYPE_TOPLEVEL_END    = 1;
     /**
      * Function is being called.
      */
     const unsigned long TYPE_FUNCTION_CALL   = 2;
     /**
      * Function is returning.
      */
     const unsigned long TYPE_FUNCTION_RETURN = 3;
     /**
      * Called before the JavaScript engine executes a top level script or calls
      * a function.
      */
     void onCall(in jsdIStackFrame frame, in unsigned long type);
 };
 [scriptable, function, uuid(e6b45eee-d974-4d85-9d9e-f5a67218deb4)]
 interface jsdIErrorHook : nsISupports
 {
     /**
      * REPORT_* values must be kept in sync with JSREPORT_* #defines in
      * jsapi.h
      */
     /**
      * Report is an error.
      */
     const unsigned long REPORT_ERROR     = 0x00;
     /**
      * Report is only a warning.
      */
     const unsigned long REPORT_WARNING   = 0x01;
     /**
      * Report represents an uncaught exception.
      */
     const unsigned long REPORT_EXCEPTION = 0x02;
     /**
      * Report is due to strict mode.
      */
     const unsigned long REPORT_STRICT    = 0x04;
     /**
      * Called when the JavaScript engine encounters an error. Return |true|
      * to pass the error along, |false| to invoke the debugHook.
      */
     boolean onError(in AUTF8String message, in AUTF8String fileName,
                     in unsigned long line, in unsigned long pos,
                     in unsigned long flags, in unsigned long errnum,
                     in jsdIValue exc);
 };
 /**
  * Hook instances of this interface up to the
  * jsdIDebuggerService::breakpointHook, debuggerHook, errorHook, interruptHook,
  * and throwHook properties.
  */
 [scriptable, function, uuid(3a722496-9d78-4f0a-a797-293d9e8cb8d2)]
 interface jsdIExecutionHook : nsISupports
 {
     /**
      * TYPE_* values must be kept in sync with JSD_HOOK_* #defines in jsdebug.h.
      */
     /**
      * Execution stopped because we're in single step mode.
      */
     const unsigned long TYPE_INTERRUPTED      = 0;
     /**
      * Execution stopped by a trap instruction (i.e. breakoint.)
      */
     const unsigned long TYPE_BREAKPOINT       = 1;
     /**
      * Error handler returned an "invoke debugger" value.
      */
     const unsigned long TYPE_DEBUG_REQUESTED  = 2;
     /**
      * Debugger keyword encountered.
      */
     const unsigned long TYPE_DEBUGGER_KEYWORD = 3;
     /**
      * Exception was thrown.
      */
     const unsigned long TYPE_THROW            = 4;
     /**
      * RETURN_* values must be kept in sync with JSD_HOOK_RETURN_* #defines in
      * jsdebug.h.
      */
     /**
      * Indicates unrecoverable error processing the hook. This will cause
      * the script being executed to be aborted without raising a JavaScript
      * exception.
      */
     const unsigned long RETURN_HOOK_ERROR     = 0;
     /**
      * Continue processing normally. This is the "do nothing special" return
      * value for all hook types *except* TYPE_THROW. Returning RETURN_CONTINUE
      * from TYPE_THROW cause the exception to be ignored. Return
      * RETURN_CONTINUE_THROW to continue exception processing from TYPE_THROW
      * hooks.
      */
     const unsigned long RETURN_CONTINUE       = 1;
     /**
      * Same effect as RETURN_HOOK_ERROR.
      */
     const unsigned long RETURN_ABORT          = 2;
     /**
      * Return the value of the |val| parameter.
      */
     const unsigned long RETURN_RET_WITH_VAL   = 3;
     /**
      * Throw the value of the |val| parameter.
      */
     const unsigned long RETURN_THROW_WITH_VAL = 4;
     /**
      * Continue the current throw.
      */
     const unsigned long RETURN_CONTINUE_THROW = 5;
     /**
      * @param frame A jsdIStackFrame object representing the bottom stack frame.
      * @param type  One of the jsdIExecutionHook::TYPE_ constants.
      * @param val   in  - Current exception (if any) when this method is called.
      *              out - If you return RETURN_THROW_WITH_VAL, value to be
      *                    thrown.
      *                    If you return RETURN_RET_WITH_VAL, value to return.
      *                    All other return values, not significant.
      * @retval      One of the jsdIExecutionHook::RETURN_* constants.
      */
     unsigned long onExecute(in jsdIStackFrame frame,
                             in unsigned long type, inout jsdIValue val);
 };
 /**
  * Objects which inherit this interface may go away, with (jsdIScript) or
  * without (all others) notification. These objects are generally wrappers
  * around JSD structures that go away when you call jsdService::Off().
  */
 [scriptable, uuid(46f1e23e-1dd2-11b2-9ceb-8285f2e95e69)]
 interface jsdIEphemeral : nsISupports
 {
     /**
      * |true| if this object is still valid. If not, many or all of the methods
      * and/or properties of the inheritor may no longer be callable.
      */
     readonly attribute boolean isValid;
     /**
      * Mark this instance as invalid.
      */
     [noscript] void invalidate();
 };
 /* handle objects */
 /**
  * Context object. Only context's which are also nsISupports objects can be
  * reflected by this interface.
  */
 [scriptable, uuid(3e5c934d-6863-4d81-96f5-76a3b962fc2b)]
 interface jsdIContext : jsdIEphemeral
 {
     /* Internal use only. */
     [noscript] readonly attribute JSContext   JSContext;
     /**
      * OPT_* values must be kept in sync with JSOPTION_* #defines in jsapi.h.
      */
     /**
      * Strict mode is on.
      */
     const long OPT_STRICT      = 0x01;
     /**
      * Warnings reported as errors.
      */
     const long OPT_WERR        = 0x02;
     /**
      * Makes eval() use the last object on its 'obj' param's scope chain as the
      * ECMA 'variables object'.
      */
     const long OPT_VAROBJFIX   = 0x04;
     /**
      * Private data for this object is an nsISupports object. Attempting to
      * alter this bit will result in an NS_ERROR_ILLEGAL_VALUE.
      */
     const long OPT_ISUPPORTS   = 0x08;
     /**
      * OPT_* values above, OR'd together.
      */
     attribute unsigned long          options;
     /**
      * Unique tag among all valid jsdIContext objects, useful as a hash key.
      */
     readonly attribute unsigned long tag;
     /**
      * Private data for this context, if it is an nsISupports, |null| otherwise.
      */
     readonly attribute nsISupports   privateData;
     /**
      * Retrieve the underlying context wrapped by this jsdIContext.
      */
     readonly attribute nsISupports   wrappedContext;
     /**
      * Top of the scope chain for this context.
      */
     readonly attribute jsdIValue     globalObject;
     /**
      * |true| if this context should be allowed to run scripts, |false|
      * otherwise. This attribute is only valid for contexts which implement
      * nsIScriptContext. Setting or getting this attribute on any other
      * context will throw a NS_ERROR_NO_INTERFACE exception.
      */
     attribute boolean                scriptsEnabled;
 };
 /**
  * Stack frame objects. These are only valid inside the jsdIExecutionHook which
  * gave it to you. After you return from that handler the bottom frame, and any
  * frame you found attached through it, are invalidated via the jsdIEphemeral
  * interface. Once a jsdIStackFrame has been invalidated all method and
  * property accesses will throw a NS_ERROR_NOT_AVAILABLE exception.
  */
 [scriptable, uuid(7c95422c-7579-4a6f-8ef7-e5b391552ee5)]
 interface jsdIStackFrame : jsdIEphemeral
 {
     /** Internal use only. */
     [noscript] readonly attribute JSDContext        JSDContext;
     /** Internal use only. */
     [noscript] readonly attribute JSDThreadState    JSDThreadState;
     /** Internal use only. */
     [noscript] readonly attribute JSDStackFrameInfo JSDStackFrameInfo;
     /**
      * True if stack frame represents a frame created as a result of a debugger
      * evaluation.
      */
     readonly attribute boolean isDebugger;
     /**
      * True if stack frame is constructing a new object.
      */
     readonly attribute boolean isConstructing;
     /**
      * Link to the caller's stack frame.
      */
     readonly attribute jsdIStackFrame callingFrame;
     /**
      * Executon context.
      */
     readonly attribute jsdIContext    executionContext;
     /**
      * Function name executing in this stack frame.
      */
     readonly attribute AUTF8String    functionName;
     /**
      * Script running in this stack frame, null for native frames.
      */
     readonly attribute jsdIScript     script;
     /**
      * Current program counter in this stack frame.
      */
     readonly attribute unsigned long  pc;
     /**
      * Current line number (using the script's pc to line map.)
      */
     readonly attribute unsigned long  line;
     /**
      * Function object running in this stack frame.
      */
     readonly attribute jsdIValue      callee;
     /**
      * Top object in the scope chain.
      */
     readonly attribute jsdIValue      scope;
     /**
      * |this| object for this stack frame.
      */
     readonly attribute jsdIValue      thisValue;
     /**
      * Evaluate arbitrary JavaScript in this stack frame.
      * @param bytes    Script to be evaluated.
      * @param fileName Filename to compile this script under. This is the
      *                 filename you'll see in error messages, etc.
      * @param line     Starting line number for this script. One based.
      * @retval         Result of evaluating the script.
      */
     boolean eval(in AString bytes, in AUTF8String fileName,
                  in unsigned long line, out jsdIValue result);
 };
 /**
  * Script object. In JavaScript engine terms, there's a single script for each
  * function, and one for the top level script.
  */
 [scriptable, uuid(8ce9b2a2-cc33-48a8-9f47-8696186ed9a5)]
 interface jsdIScript : jsdIEphemeral
 {
     /** Internal use only. */
     [noscript] readonly attribute JSDContext JSDContext;
     /** Internal use only. */
     [noscript] readonly attribute JSDScript  JSDScript;
     /**
      * Last version set on this context.
      * Scripts typically select this with the "language" attribute.
      * See the VERSION_* consts on jsdIDebuggerService.
      */
     readonly attribute long          version;
     /**
      * Tag value guaranteed unique among jsdIScript objects. Useful as a
      * hash key in script.
      */
     readonly attribute unsigned long tag;
     /**
      * FLAG_* values need to be kept in sync with JSD_SCRIPT_* #defines in
      * jsdebug.h.
      */
     /**
      * Determines whether or not to collect profile information for this
      * script. The context flag FLAG_PROFILE_WHEN_SET decides the logic.
      */
     const unsigned long FLAG_PROFILE = 0x01;
     /**
      * Determines whether or not to ignore breakpoints, etc. in this script.
      * The context flag JSD_DEBUG_WHEN_SET decides the logic.
      */
     const unsigned long FLAG_DEBUG   = 0x02;
     /**
      * Determines whether to invoke the onScriptDestroy callback for this
      * script. The default is for this to be true if the onScriptCreated
      * callback was invoked for this script.
      */
     const unsigned long FLAG_CALL_DESTROY_HOOK = 0x04;
     /**
      * FLAG_* attributes from above, OR'd together.
      */
     attribute unsigned long flags;
     /**
      * Filename given for this script when it was compiled.
      * This data is copied from the underlying structure when the jsdIScript
      * instance is created and is therefore available even after the script is
      * invalidated.
      */
     readonly attribute AUTF8String   fileName;
     /**
      * Function name for this script. "anonymous" for unnamed functions (or
      * a function actually named anonymous), empty for top level scripts.
      * This data is copied from the underlying structure when the jsdIScript
      * instance is created and is therefore available even after the script is
      * invalidated.
      */
     readonly attribute AUTF8String   functionName;
     /**
      * The names of the arguments for this function; empty if this is
      * not a function.
      */
     void getParameterNames([optional] out unsigned long count,
                            [array, size_is(count), retval] out wstring paramNames);
     /**
      * Fetch the function object as a jsdIValue.
      */
     readonly attribute jsdIValue     functionObject;
     /**
      * Source code for this script, without function declaration.
      */
     readonly attribute AString functionSource;
     /**
      * Line number in source file containing the first line of this script.
      * This data is copied from the underlying structure when the jsdIScript
      * instance is created and is therefore available even after the script is
      * invalidated.
      */
     readonly attribute unsigned long baseLineNumber;
     /**
      * Total number of lines in this script.
      * This data is copied from the underlying structure when the jsdIScript
      * instance is created and is therefore available even after the script is
      * invalidated.
      */
     readonly attribute unsigned long lineExtent;
     /**
      * Number of times this script has been called.
      */
     readonly attribute unsigned long callCount;
     /**
      * Number of times this script called itself, directly or indirectly.
      */
     readonly attribute unsigned long maxRecurseDepth;
     /**
      * Shortest execution time recorded, in milliseconds.
      */
     readonly attribute double minExecutionTime;
     /**
      * Longest execution time recorded, in milliseconds.
      */
     readonly attribute double maxExecutionTime;
     /**
      * Total time spent in this function, in milliseconds.
      */
     readonly attribute double totalExecutionTime;
     /**
      * Shortest execution time recorded, in milliseconds, excluding time spent
      * in other called code.
      */
     readonly attribute double minOwnExecutionTime;
     /**
      * Longest execution time recorded, in milliseconds, excluding time spent
      * in other called code.
      */
     readonly attribute double maxOwnExecutionTime;
     /**
      * Total time spent in this function, in milliseconds, excluding time spent
      * in other called code.
      */
     readonly attribute double totalOwnExecutionTime;
     /**
      * Clear profile data for this script.
      */
     void clearProfileData();
     const unsigned long PCMAP_SOURCETEXT  = 1; /* map to actual source text    */
     const unsigned long PCMAP_PRETTYPRINT = 2; /* map to pretty printed source */
     /**
      * Get the closest line number to a given PC.
      * The |pcmap| argument specifies which pc to source line map to use.
      */
     unsigned long pcToLine(in unsigned long pc, in unsigned long pcmap);
     /**
      * Get the first PC associated with a line.
      * The |pcmap| argument specifies which pc to source line map to use.
      */
     unsigned long lineToPc(in unsigned long line, in unsigned long pcmap);
     /**
      * Determine is a particular line is executable, like checking that
      * lineToPc == pcToLine, except in one call.
      * The |pcmap| argument specifies which pc to source line map to use.
      */
     boolean isLineExecutable(in unsigned long line, in unsigned long pcmap);
     /**
      * Return a list of all executable lines in a script.
      * |pcmap| specifies which pc to source line map to use.
      * |startLine| and |maxLines| may be used to retrieve a chunk at a time.
      */
     void getExecutableLines(in unsigned long pcmap,
                             in unsigned long startLine, in unsigned long maxLines,
                             [optional] out unsigned long count,
                             [array, size_is(count), retval] out unsigned long executableLines);
     /**
      * Set a breakpoint at a PC in this script.
      */
     void setBreakpoint(in unsigned long pc);
     /**
      * Clear a breakpoint at a PC in this script.
      */
     void clearBreakpoint(in unsigned long pc);
     /**
      * Clear all breakpoints set in this script.
      */
     void clearAllBreakpoints();
     /**
      * Call interrupt hook at least once per source line
      */
     void enableSingleStepInterrupts(in boolean mode);
 };
 /**
  * Value objects. Represents typeless JavaScript values (jsval in SpiderMonkey
  * terminology.)  These are valid until the debugger is turned off. Holding a
  * jsdIValue adds a root for the underlying JavaScript value, so don't keep it
  * if you don't need to.
  */
 [scriptable, uuid(1cd3535b-4ddb-4202-9053-e0ec88f5c82b)]
 interface jsdIValue : jsdIEphemeral
 {
     /** Internal use only. */
     [noscript] readonly attribute JSDContext JSDContext;
     /** Internal use only. */
     [noscript] readonly attribute JSDValue   JSDValue;
     /**
      * |false| unless the value is a function declared in script.
      */
     readonly attribute boolean isNative;
     /**
      * |true| if the value represents a number, either double or integer.
      * |false| for all other values, including numbers assigned as strings
      * (eg. x = "1";)
      */
     readonly attribute boolean isNumber;
     /**
      * |true| if the value represents a JavaScript primitive number or AUTF8String
      */
     readonly attribute boolean isPrimitive;
     /** Value is either |true| or |false|. */
     const unsigned long TYPE_BOOLEAN  = 0;
     /** Value is a primitive number that is too large to fit in an integer. */
     const unsigned long TYPE_DOUBLE   = 1;
     /** Value is a primitive number that fits into an integer. */
     const unsigned long TYPE_INT      = 2;
     /** Value is a function. */
     const unsigned long TYPE_FUNCTION = 3;
     /** Value is |null|. */
     const unsigned long TYPE_NULL     = 4;
     /** Value is an object. */
     const unsigned long TYPE_OBJECT   = 5;
     /** Value is a primitive AUTF8String. */
     const unsigned long TYPE_STRING   = 6;
     /** Value is void. */
     const unsigned long TYPE_VOID     = 7;
     /**
      * One of the TYPE_* values above.
      */
     readonly attribute unsigned long jsType;
     /**
      * Prototype value if this value represents an object, null if the value is
      * not an object or the object has no prototype.
      */
     readonly attribute jsdIValue     jsPrototype;
     /**
      * Parent value if this value represents an object, null if the value is not
      * an object or the object has no parent.
      */
     readonly attribute jsdIValue     jsParent;
     /**
      * Class name if this value represents an object. Empty AUTF8String if the value
      * is not an object.
      */
     readonly attribute AUTF8String   jsClassName;
     /**
      * Constructor name if this value represents an object. Empty AUTF8String if the
      * value is not an object.
      */
     readonly attribute jsdIValue     jsConstructor;
     /**
      * Function name if this value represents a function. Empty AUTF8String if the
      * value is not a function.
      */
     readonly attribute AUTF8String   jsFunctionName;
     /**
      * Value if interpreted as a boolean. Converts if necessary.
      */
     readonly attribute boolean       booleanValue;
     /**
      * Value if interpreted as a double. Converts if necessary.
      */
     readonly attribute double        doubleValue;
     /**
      * Value if interpreted as an integer. Converts if necessary.
      */
     readonly attribute long          intValue;
     /**
      * Value if interpreted as an object.
      */
     readonly attribute jsdIObject    objectValue;
     /**
      * Value if interpreted as a AUTF8String. Converts if necessary.
      */
     readonly attribute AUTF8String   stringValue;
     /**
      * Number of properties. 0 if the value is not an object, or the value is
      * an object but has no properties.
      */
     readonly attribute long propertyCount;
     /**
      * Retrieves all properties if this value represents an object. If this
      * value is not an object a 0 element array is returned.
      * @param propArray Array of jsdIProperty values for this value.
      * @param length    Size of array.
      */
     void getProperties([array, size_is(length)] out jsdIProperty propArray,
                        out unsigned long length);
     /**
      * Retrieves a single property from the value. Only valid if the value
      * represents an object.
      * @param name Name of the property to retrieve.
      * @retval     jsdIProperty for the requested property name or null if no
      *             property exists for the requested name.
      */
     jsdIProperty getProperty(in AUTF8String name);
     /**
      * jsdIValues are wrappers around JavaScript engine structures. Much of the
      * data is copied instead of shared. The refresh method is used to resync
      * the jsdIValue with the underlying structure.
      */
     void refresh();
     /**
      * When called from JavaScript, this method returns the JavaScript value
      * wrapped by this jsdIValue. The calling script is free to use the result
      * as it would any other JavaScript value.
      * When called from another language this method returns an xpconnect
      * defined error code.
      */
     [implicit_jscontext] jsval getWrappedValue();
     /**
      * If this is a function value, return its associated jsdIScript.
      * Otherwise, return null.
      */
     readonly attribute jsdIScript script;
 };
 /**
  * Properties specific to values which are also objects.
  * XXX We don't add roots for these yet, so make sure you hold on to the
  * jsdIValue from whence your jsdIObject instance came for at least as long as
  * you hold the jsdIObject.
  * XXX Maybe the jsClassName, jsConstructorName, and property related attribute/
  * functions from jsdIValue should move to this interface. We could inherit from
  * jsdIValue or use interface flattening or something.
  */
 [scriptable, uuid(87d86308-7a27-4255-b23c-ce2394f02473)]
 interface jsdIObject : nsISupports
 {
     /** Internal use only. */
     [noscript] readonly attribute JSDContext JSDContext;
     /** Internal use only. */
     [noscript] readonly attribute JSDObject  JSDObject;
     /**
      * The URL (filename) that contains the script which caused this object
      * to be created.
      */
     readonly attribute AUTF8String   creatorURL;
     /**
      * Line number in the creatorURL where this object was created.
      */
     readonly attribute unsigned long creatorLine;
     /**
      * The URL (filename) that contains the script which defined the constructor
      * used to create this object.
      */
     readonly attribute AUTF8String   constructorURL;
     /**
      * Line number in the creatorURL where this object was created.
      */
     readonly attribute unsigned long constructorLine;
     /**
      * jsdIValue for this object.
      */
     readonly attribute jsdIValue     value;
 };
 /**
  * Representation of a property of an object. When an instance is invalid, all
  * method and property access will result in a NS_UNAVAILABLE error.
  */
 [scriptable, uuid(acf1329e-aaf6-4d6a-a1eb-f75858566f09)]
 interface jsdIProperty : jsdIEphemeral
 {
     /** Internal use only. */
     [noscript] readonly attribute JSDContext  JSDContext;
     /** Internal use only. */
     [noscript] readonly attribute JSDProperty JSDProperty;
     /**
      * FLAG_* values must be kept in sync with JSDPD_* #defines in jsdebug.h.
      */
     /** visible to for/in loop */
     const unsigned long FLAG_ENUMERATE = 0x01;
     /** assignment is error */
     const unsigned long FLAG_READONLY  = 0x02;
     /** property cannot be deleted */
     const unsigned long FLAG_PERMANENT = 0x04;
     /** property has an alias id */
     const unsigned long FLAG_ALIAS     = 0x08;
     /** argument to function */
     const unsigned long FLAG_ARGUMENT  = 0x10;
     /** local variable in function */
     const unsigned long FLAG_VARIABLE  = 0x20;
     /** exception occurred looking up property, value is exception */
     const unsigned long FLAG_EXCEPTION = 0x40;
     /** native getter returned false without throwing an exception */
     const unsigned long FLAG_ERROR     = 0x80;
     /** found via explicit lookup (property defined elsewhere.) */
     const unsigned long FLAG_HINTED    = 0x800;
     /** FLAG_* values OR'd together, representing the flags for this property. */
     readonly attribute unsigned long flags;
     /** jsdIValue representing the alias for this property. */
     readonly attribute jsdIValue     alias;
     /** name for this property. */
     readonly attribute jsdIValue     name;
     /** value of this property. */
     readonly attribute jsdIValue     value;
 };

The Tor Browser / annotate

js/jsd/idl/jsdIDebuggerService.idl@a63d609f5ebe (annotated)

js/jsd/idl/jsdIDebuggerService.idl