jsdIDebuggerService in Firefox 3.0

Implemented by

@mozilla.org/js/jsd/debugger-service;1

[scriptable, uuid(9dd9006a-4e5e-4a80-ac3d-007fb7335ca4)]

Constants

 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 = 1

 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 = 2

 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 = 4

 When this flag is set the internal call hook will collect profile data.

const unsigned long COLLECT_PROFILE_DATA = 8

 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 = 16

 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 = 32

 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 = 64

Attributes

 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 when an error or warning occurs.

attribute jsdIErrorHook errorHook

 Debugger service flags.

attribute unsigned long flags

 Called before and after a function is called.

attribute jsdICallHook functionHook

 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

 Called before the next PC is executed.

attribute jsdIExecutionHook interruptHook

 |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

 Debugger service.  It's not a good idea to have more than one active client of
 the debugger service.

 Internal use only. */

[noscript] readonly attribute JSDContext JSDContext

 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

 Called when a jsdIScript is created or destroyed.

attribute jsdIScriptHook scriptHook

 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

Methods

 Same as insertFilter, except always add to the end of the list.

void appendFilter(in jsdIFilter filter)

 Clear all breakpoints in all scripts.

void clearAllBreakpoints()

 Clear the list of filters.

void clearFilters()

 Clear profile data for all scripts.

void clearProfileData()

 Output dump of JS heap.

 @param fileName Filename to dump the heap into.

void DumpHeap(in string fileName)

 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)

 Enumerate all known contexts.

void enumerateContexts(in jsdIContextEnumerator enumerator)

 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)

 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)

 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()

 Force the engine to perform garbage collection.

void GC()

 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)

 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()

 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)

 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()

 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()

 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)

 Undo a pause.

 @return depth The number of remaining pending pause calls.

unsigned long unPause()

 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()