jsdidebuggerservice.idl

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

/* -*- 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, <[e-mail]>
 *
 * 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 jsdIPC;
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