jsdidebuggerservice.idl

caffeine-monkey java实现的js模拟引擎

     * 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.
     */