mirror of
https://gitlab.winehq.org/wine/wine-gecko.git
synced 2024-09-13 09:24:08 -07:00
1250 lines
41 KiB
Plaintext
1250 lines
41 KiB
Plaintext
/* -*- 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.
|
|
*/
|
|
[scriptable, uuid(9be5b327-6818-464d-9695-f33885fd8377)]
|
|
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;
|
|
|
|
|
|
/**
|
|
* VERSION_* values must be kept in sync with the JSVersion enumeration in
|
|
* jspubtd.h.
|
|
*/
|
|
|
|
/**
|
|
* Possible values for jsdIScript::version and jsdIContext::version.
|
|
*/
|
|
const long VERSION_1_0 = 100;
|
|
const long VERSION_1_1 = 110;
|
|
const long VERSION_1_2 = 120;
|
|
const long VERSION_1_3 = 130;
|
|
const long VERSION_1_4 = 140;
|
|
const long VERSION_1_5 = 150;
|
|
const long VERSION_DEFAULT = 0;
|
|
const long VERSION_UNKNOWN = -1;
|
|
|
|
/**
|
|
* These flags need to be kept in sync with the context flags defined in
|
|
* jsdebug.h
|
|
*/
|
|
|
|
/**
|
|
* 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);
|
|
};
|
|
|
|
/* 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;
|
|
|
|
/**
|
|
* Last version set on this context.
|
|
* Scripts typically select this with the "language" attribute.
|
|
* See the VERSION_* consts on jsdIDebuggerService.
|
|
*/
|
|
attribute long version;
|
|
|
|
/**
|
|
* 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 JS_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;
|
|
};
|