/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- * * ***** BEGIN LICENSE BLOCK ***** * Version: MPL 1.1/GPL 2.0/LGPL 2.1 * * The contents of this file are subject to the Mozilla Public License Version * 1.1 (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * http://www.mozilla.org/MPL/ * * Software distributed under the License is distributed on an "AS IS" basis, * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License * for the specific language governing rights and limitations under the * License. * * The Original Code is mozilla.org code. * * The Initial Developer of the Original Code is * Netscape Communications Corporation. * Portions created by the Initial Developer are Copyright (C) 1998 * the Initial Developer. All Rights Reserved. * * Contributor(s): * Robert Ginda, * * Alternatively, the contents of this file may be used under the terms of * either the GNU General Public License Version 2 or later (the "GPL"), or * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), * in which case the provisions of the GPL or the LGPL are applicable instead * of those above. If you wish to allow use of your version of this file only * under the terms of either the GPL or the LGPL, and not to allow others to * use your version of this file under the terms of the MPL, indicate your * decision by deleting the provisions above and replace them with the notice * and other provisions required by the GPL or the LGPL. If you do not delete * the provisions above, a recipient may use your version of this file under * the terms of any one of the MPL, the GPL or the LGPL. * * ***** END LICENSE BLOCK ***** */ #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); native JSVal(jsval); /* 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; /** * Debugger service. It's not a good idea to have more than one active client of * the debugger service. */ [scriptable, uuid(dc0a24db-f8ac-4889-80d0-6016545a2dda)] 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; /** * When this flag is set, object creation will not be tracked. This will * reduce the performance price you pay by enabling the debugger. */ const unsigned long DISABLE_OBJECT_TRACE = 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 should register an app-start observer in order * to begin collecting debug information when mozilla is launched. */ attribute boolean initAtStartup; /** * |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; /** * 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. */ void on (); /** * Turn on the debugger for a given runtime. * * @param rt The runtime you want to debug. You cannot turn the debugger * on for multiple runtimes. */ [noscript] void onForRuntime (in JSRuntime rt); /** * Turn the debugger off. This will invalidate all of your jsdIEphemeral * derived objects, and clear all of your breakpoints. In theory you * should be able to turn the debugger back on at some later time without * any problems. */ 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. * * @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 jsvalue value*/); /** * The same as above but to be called from C++. */ [noscript] jsdIValue wrapJSValue (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(0c9189d9-4287-47a4-bca6-6ed65aaf737f)] 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; /** * An nsISupports version of the global object to be filtered. A null glob * matches all hooks. This attribute must be QI'able to the * (non-scriptable) nsIScriptGlobalObject interface. * * The jsdIService caches this value internally, so if it changes you must * swap the filter with itself using jsdIService::swapFilters. */ attribute nsISupports globalObject; /** * 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; }; /** * Pass an instance of one of these to jsdIDebuggerService::enterNestedEventLoop. */ [scriptable, 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, 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, uuid(5ba76b99-acb1-4ed8-a4e4-a716a7d9097e)] 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, uuid(d96af02e-3379-4db5-885d-fee28d178701)] 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(cf7ecc3f-361b-44af-84a7-4b0d6cdca204)] 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, uuid(191d2738-22e8-4756-b366-6c878c87d73b)] 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, uuid(cea9ab1a-4b5d-416f-a197-9ffa7046f2ce)] 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, 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(0633ca73-105e-4e8e-bcc5-13405d61754a)] 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 native frame. */ readonly attribute boolean isNative; /** * 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(18e09893-f461-4b4b-94d3-776fb0069c6f)] 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; /** * 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); /** * 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 (); }; /** * 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(9cab158f-dc78-41dd-9d11-79e05cb3f2bd)] 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. */ void 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(a735a94c-9d41-4997-8fcb-cfa8b649a5b7)] 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(4491ecd4-fb6b-43fb-bd6f-5d1473f1df24)] 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; /** slot number if this property is a local variable or parameter. */ readonly attribute unsigned long varArgSlot; }; /* [scriptable, uuid(a47adad2-1dd1-11b2-b9e9-8e67a47beca5)] interface jsdISourceText : nsISupports {}; [scriptable, uuid(b6d1c006-1dd1-11b2-b9d8-b4d1ccfb74d8)] interface jsdIThreadState : nsISupports { [noscript] readonly attribute JSDContext JSDContext; [noscript] readonly attribute JSDThreadState JSDThreadState; readonly attribute unsigned long frameCount; readonly attribute jsdIStackFrame topFrame; attribute jsdIValue pendingException; }; */