| /* -*- 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, <rginda@netscape.com> |
| * |
| * 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); |
| |
| /* 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(9dd9006a-4e5e-4a80-ac3d-007fb7335ca4)] |
| 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 string identifier for implementation. |
| */ |
| readonly attribute string 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(); |
| |
| /** |
| * Output dump of JS heap. |
| * |
| * @param fileName Filename to dump the heap into. |
| */ |
| void DumpHeap(in string fileName); |
| |
| /** |
| * 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*/); |
| |
| /* 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 (); |
| }; |
| |
| /* 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(05593438-1b83-4517-864f-3cea3d37a266)] |
| 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 string 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(54382875-ed12-4f90-9a63-1f0498d0a3f2)] |
| 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(4c2f706e-1dd2-11b2-9ebc-85a06e948830)] |
| 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(912e342a-1dd2-11b2-b09f-cf3af38c15f0)] |
| 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(ae89a7e2-1dd1-11b2-8c2f-af82086291a5)] |
| 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(f102caf6-1dd1-11b2-bd43-c1dbacb95a98)] |
| 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(b7dd3c1c-1dd1-11b2-83eb-8a857d199e0f)] |
| 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 string message, in string 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(9a7b6ad0-1dd1-11b2-a789-fcfae96356a2)] |
| 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(a2dd25a4-1dd1-11b2-bda6-ed525acd4c35)] |
| 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(b6d50784-1dd1-11b2-a932-882246c6fe45)] |
| 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 string 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 string 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(a38f65ca-1dd1-11b2-95d5-ff2947e9c920)] |
| 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 string 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 string functionName; |
| /** |
| * 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(b7964304-1dd1-11b2-ba20-cf4205772e9d)] |
| 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 string |
| */ |
| 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 string. */ |
| 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 string if the value |
| * is not an object. |
| */ |
| readonly attribute string jsClassName; |
| /** |
| * Constructor name if this value represents an object. Empty string if the |
| * value is not an object. |
| */ |
| readonly attribute jsdIValue jsConstructor; |
| /** |
| * Function name if this value represents a function. Empty string if the |
| * value is not a function. |
| */ |
| readonly attribute string 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 string. Converts if necessary. |
| */ |
| readonly attribute string 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 string 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(); |
| }; |
| |
| /** |
| * 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(d500e8b8-1dd1-11b2-89a1-cdf55d91cbbd)] |
| 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 string 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 string 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(b8816e56-1dd1-11b2-81dc-8ba99a833d9e)] |
| 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; |
| }; |
| |
| */ |
| |