gecko-dev/js/jsd/idl/jsdIDebuggerService.idl

/* -*- 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();
    
    /**
     * 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, to 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;
};

*/