The Tor Browser / file comparison

comparison: js/jsd/idl/jsdIDebuggerService.idl

js/jsd/idl/jsdIDebuggerService.idl

changeset 0
6474c204b198
equal deleted inserted replaced
-1:000000000000 0:3e567da7fa0b
1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5
6 #include "nsISupports.idl"
7
8 %{ C++
9 #include "jsdebug.h"
10 #include "nsAString.h"
11 %}
12
13 [ptr] native JSDContext(JSDContext);
14 [ptr] native JSDObject(JSDObject);
15 [ptr] native JSDProperty(JSDProperty);
16 [ptr] native JSDScript(JSDScript);
17 [ptr] native JSDStackFrameInfo(JSDStackFrameInfo);
18 [ptr] native JSDThreadState(JSDThreadState);
19 [ptr] native JSDValue(JSDValue);
20 [ptr] native JSRuntime(JSRuntime);
21 [ptr] native JSContext(JSContext);
22 [ptr] native JSCompartment(JSCompartment);
23
24 /* interfaces we declare in this file */
25 interface jsdIDebuggerService;
26 interface jsdIFilter;
27 interface jsdINestCallback;
28 interface jsdIFilterEnumerator;
29 interface jsdIContextEnumerator;
30 interface jsdIScriptEnumerator;
31 interface jsdIScriptHook;
32 interface jsdIErrorHook;
33 interface jsdIExecutionHook;
34 interface jsdICallHook;
35 interface jsdIEphemeral;
36 interface jsdIContext;
37 interface jsdIStackFrame;
38 interface jsdIScript;
39 interface jsdIValue;
40 interface jsdIObject;
41 interface jsdIProperty;
42 interface jsdIActivationCallback;
43
44 /**
45 * Debugger service. It is not a good idea to have more than one active client
46 * of the debugger service.
47 *
48 * Note that all the APIs in this file are deprecated. All consumers of
49 * these interfaces should switch to using the new Debugger API, documented
50 * here: https://wiki.mozilla.org/Debugger
51 */
52 [scriptable, uuid(39609752-2d73-4019-a324-a374dee16d3c)]
53 interface jsdIDebuggerService : nsISupports
54 {
55 /** Internal use only. */
56 [noscript] readonly attribute JSDContext JSDContext;
57
58 /**
59 * Called when an error or warning occurs.
60 */
61 attribute jsdIErrorHook errorHook;
62 /**
63 * Called when a jsdIScript is created or destroyed.
64 */
65 attribute jsdIScriptHook scriptHook;
66 /**
67 * Called when the engine encounters a breakpoint.
68 */
69 attribute jsdIExecutionHook breakpointHook;
70 /**
71 * Called when the engine encounters the debugger keyword.
72 */
73 attribute jsdIExecutionHook debuggerHook;
74 /**
75 * Called when the errorHook returns false.
76 */
77 attribute jsdIExecutionHook debugHook;
78 /**
79 * Called before the next PC is executed.
80 */
81 attribute jsdIExecutionHook interruptHook;
82 /**
83 * Called when an exception is thrown (even if it will be caught.)
84 */
85 attribute jsdIExecutionHook throwHook;
86 /**
87 * Called before and after a toplevel script is evaluated.
88 */
89 attribute jsdICallHook topLevelHook;
90 /**
91 * Called before and after a function is called.
92 */
93 attribute jsdICallHook functionHook;
94
95 /**
96 * Link native frames in call stacks.
97 */
98 const unsigned long ENABLE_NATIVE_FRAMES = 0x01;
99 /**
100 * Normally, if a script has a 0 in JSD_SCRIPT_PROFILE_BIT it is included in
101 * profile data, otherwise it is not profiled. Setting the
102 * PROFILE_WHEN_SET flag reverses this convention.
103 */
104 const unsigned long PROFILE_WHEN_SET = 0x02;
105 /**
106 * Normally, when the script in the top frame of a thread state has a 1 in
107 * JSD_SCRIPT_DEBUG_BIT, the execution hook is ignored. Setting the
108 * DEBUG_WHEN_SET flag reverses this convention.
109 */
110 const unsigned long DEBUG_WHEN_SET = 0x04;
111 /**
112 * When this flag is set the internal call hook will collect profile data.
113 */
114 const unsigned long COLLECT_PROFILE_DATA = 0x08;
115 /**
116 * When this flag is set, stack frames that are disabled for debugging
117 * will not appear in the call stack chain.
118 */
119 const unsigned long HIDE_DISABLED_FRAMES = 0x10;
120 /**
121 * When this flag is set, the debugger will only check the
122 * JSD_SCRIPT_DEBUG_BIT on the top (most recent) stack frame. This
123 * makes it possible to stop in an enabled frame which was called from
124 * a stack that contains a disabled frame.
125 *
126 * When this flag is *not* set, any stack that contains a disabled frame
127 * will not be debugged (the execution hook will not be invoked.)
128 *
129 * This only applies when the reason for calling the hook would have
130 * been TYPE_INTERRUPTED or TYPE_THROW. TYPE_BREAKPOINT,
131 * TYPE_DEBUG_REQUESTED, and TYPE_DEBUGGER_KEYWORD always stop, regardless
132 * of this setting, as long as the top frame is not disabled.
133 *
134 * If HIDE_DISABLED_FRAMES is set, this is effectively set as well.
135 */
136 const unsigned long MASK_TOP_FRAME_ONLY = 0x20;
137 /**
138 * This flag has been retired, do not re-use. It previously provided a hook
139 * for object allocation.
140 */
141 const unsigned long DISABLE_OBJECT_TRACE_RETIRED = 0x40;
142
143 /**
144 * Debugger service flags.
145 */
146 attribute unsigned long flags;
147
148 /**
149 * Major version number of implementation.
150 */
151 readonly attribute unsigned long implementationMajor;
152 /**
153 * Minor version number of implementation.
154 */
155 readonly attribute unsigned long implementationMinor;
156 /**
157 * Free form AUTF8String identifier for implementation.
158 */
159 readonly attribute AUTF8String implementationString;
160
161 /**
162 * |true| if the debugger service has been turned on. This does not
163 * necessarily mean another app is actively using the service, as the
164 * autostart pref may have turned the service on.
165 */
166 readonly attribute boolean isOn;
167
168
169 /**
170 * Synchronous activation of the debugger is no longer supported,
171 * and will throw an exception.
172 */
173 void on();
174
175 /**
176 * Turn on the debugger. This function should only be called from
177 * JavaScript code. The debugger will be enabled on the runtime the call is
178 * made on, as determined by nsIXPCNativeCallContext.
179 *
180 * The debugger will be activated asynchronously, because there can be no
181 * JS on the stack when code is to be re-compiled for debug mode.
182 */
183 void asyncOn(in jsdIActivationCallback callback);
184
185 /**
186 * Called by nsIXPConnect after it's had a chance to recompile for
187 * debug mode.
188 */
189 [noscript] void activateDebugger(in JSRuntime rt);
190
191 /**
192 * Called by nsIXPConnect to deactivate debugger on setup failure.
193 */
194 [noscript] void deactivateDebugger();
195
196 /**
197 * Recompile all active scripts in the runtime for debugMode.
198 */
199 [noscript] void recompileForDebugMode(in JSContext cx, in JSCompartment comp, in boolean mode);
200
201 /**
202 * Turn the debugger off. This will invalidate all of your jsdIEphemeral
203 * derived objects, and clear all of your breakpoints.
204 */
205 void off ();
206
207 /**
208 * Peek at the current pause depth of the debugger.
209 *
210 * @return depth Number of pause() calls still waiting to be unPause()d.
211 */
212 readonly attribute unsigned long pauseDepth;
213 /**
214 * Temporarily disable the debugger. Hooks will not be called while the
215 * debugger is paused. Multiple calls to pause will increase the "pause
216 * depth", and equal number of unPause calles must be made to resume
217 * normal debugging.
218 *
219 * @return depth Number of times pause has been called since the debugger
220 * has been unpaused.
221 */
222 unsigned long pause();
223 /**
224 * Undo a pause. Once this is called, the debugger won't start
225 * getting execution callbacks until the stack is fully unwound so
226 * that no JS scripts are live. There is no way to query whether
227 * there are such scripts left to unwind at a given point in time.
228 *
229 * @return depth The number of remaining pending pause calls.
230 */
231 unsigned long unPause();
232
233 /**
234 * Force the engine to perform garbage collection.
235 */
236 void GC();
237
238 /**
239 * Clear profile data for all scripts.
240 */
241 void clearProfileData();
242
243 /**
244 * Adds an execution hook filter. These filters are consulted each time one
245 * of the jsdIExecutionHooks is about to be called. Filters are matched in
246 * a first in, first compared fashion. The first filter to match determines
247 * whether or not the hook is called. Use swapFilter to reorder existing
248 * filters, and removeFilter to remove them.
249 *
250 * If |filter| is already present this method throws NS_ERROR_INVALID_ARG.
251 *
252 * @param filter Object representing the filter to add.
253 * @param after Insert |filter| after this one. Pass null to insert at
254 * the beginning.
255 */
256 void insertFilter(in jsdIFilter filter, in jsdIFilter after);
257 /**
258 * Same as insertFilter, except always add to the end of the list.
259 */
260 void appendFilter(in jsdIFilter filter);
261 /**
262 * Remove a filter.
263 *
264 * If |filter| is not present this method throws NS_ERROR_INVALID_ARG.
265 *
266 * @param filter Object representing the filter to remove. Must be the exact
267 * object passed to addFilter, not just a new object with the same
268 * properties.
269 */
270 void removeFilter(in jsdIFilter filter);
271 /**
272 * Swap position of two filters.
273 *
274 * If |filter_a| is not present, this method throws NS_ERROR_INVALID_ARG.
275 * If |filter_b| is not present, filter_a is replaced by filter_b.
276 * If |filter_a| == |filter_b|, then filter is refreshed.
277 */
278 void swapFilters(in jsdIFilter filter_a, in jsdIFilter filter_b);
279 /**
280 * Enumerate registered filters. This routine refreshes each filter before
281 * passing them on to the enumeration function. Calling this with a null
282 * |enumerator| is equivalent to jsdIService::refreshFilters.
283 *
284 * @param enumerator jsdIFilterEnumerator instance to be called back for the
285 * enumeration.
286 */
287 void enumerateFilters(in jsdIFilterEnumerator enumerator);
288 /**
289 * Force the debugger to resync its internal filter cache with the
290 * actual values in the jsdIFilter objects. To refresh a single filter
291 * use jsdIService::swapFilters. This method is equivalent to
292 * jsdIService::enumerateFilters with a null enumerator.
293 */
294 void refreshFilters();
295 /**
296 * Clear the list of filters.
297 */
298 void clearFilters();
299
300 /**
301 * Enumerate all known contexts.
302 */
303 void enumerateContexts(in jsdIContextEnumerator enumerator);
304
305 /**
306 * Enumerate all scripts the debugger knows about. Any scripts created
307 * before you turned the debugger on, or after turning the debugger off
308 * will not be available unless the autostart perf is set.
309 *
310 * @param enumerator jsdIScriptEnumerator instance to be called back for
311 * the enumeration.
312 */
313 void enumerateScripts(in jsdIScriptEnumerator enumerator);
314 /**
315 * Clear all breakpoints in all scripts.
316 */
317 void clearAllBreakpoints();
318
319 /**
320 * When called from JavaScript, this method returns the jsdIValue wrapper
321 * for the given value. If a wrapper does not exist one will be created.
322 * When called from another language this method returns an xpconnect
323 * defined error code.
324 */
325 jsdIValue wrapValue(in jsval value);
326
327 /* XXX these two routines are candidates for refactoring. The only problem
328 * is that it is not clear where and how they should land.
329 */
330
331 /**
332 * Push a new network queue, and enter a new UI event loop.
333 * @param callback jsdINestCallback instance to be called back after the
334 * network queue has been pushed, but before the
335 * UI loop starts.
336 * @return depth returns the current number of times the event loop has been
337 * nested. your code can use it for sanity checks.
338 */
339 unsigned long enterNestedEventLoop(in jsdINestCallback callback);
340 /**
341 * Exit the current nested event loop after the current iteration completes,
342 * and pop the network event queue.
343 *
344 * @return depth returns the current number of times the event loop has been
345 * nested. your code can use it for sanity checks.
346 */
347 unsigned long exitNestedEventLoop();
348
349 /**
350 * Output dump of JS heap.
351 *
352 * @param fileName Filename to dump the heap into.
353 */
354 void dumpHeap(in AUTF8String fileName);
355
356 /**
357 * Suppress console warnings about using JSD, which is a deprecated API.
358 *
359 * This applies only to the next call to asyncOn; any subsequent calls
360 * will elicit the warning, unless you call 'acknowledgeDeprecation'
361 * before each of them, too. This arrangement ensures that one add-on's
362 * acknowledgement doesn't suppress warnings for other add-ons.
363 */
364 void acknowledgeDeprecation();
365 };
366
367 /* callback interfaces */
368
369 /**
370 * Object representing a pattern of global object and/or url the debugger should
371 * ignore. The debugger service itself will not modify properties of these
372 * objects.
373 */
374 [scriptable, uuid(9ae587cd-b78c-47f0-a612-4b3a211a6a71)]
375 interface jsdIFilter : nsISupports
376 {
377 /**
378 * These two bytes of the flags attribute are reserved for interpretation
379 * by the jsdService implementation. You can do what you like with the
380 * remaining flags.
381 */
382 const unsigned long FLAG_RESERVED_MASK = 0xFF;
383 /**
384 * Filters without this flag set are ignored.
385 */
386 const unsigned long FLAG_ENABLED = 0x01;
387 /**
388 * Filters with this flag set are "pass" filters, they allow matching hooks
389 * to continue. Filters without this flag block matching hooks.
390 */
391 const unsigned long FLAG_PASS = 0x02;
392
393 /**
394 * FLAG_* values from above, OR'd together.
395 */
396 attribute unsigned long flags;
397
398 /**
399 * String representing the url pattern to be filtered. Supports limited
400 * glob matching, at the beginning and end of the pattern only. For example,
401 * "chrome://venkman*" filters all urls that start with chrome/venkman,
402 * "*.cgi" filters all cgi's, and "http://myserver/utils.js" filters only
403 * the utils.js file on "myserver". A null urlPattern matches all urls.
404 *
405 * The jsdIService caches this value internally, to if it changes you must
406 * swap the filter with itself using jsdIService::swapFilters.
407 */
408 attribute AUTF8String urlPattern;
409
410 /**
411 * Line number for the start of this filter. Line numbers are one based.
412 * Assigning a 0 to this attribute will tell the debugger to ignore the
413 * entire file.
414 */
415 attribute unsigned long startLine;
416
417 /**
418 * Line number for the end of this filter. Line numbers are one based.
419 * Assigning a 0 to this attribute will tell the debugger to ignore from
420 * |startLine| to the end of the file.
421 */
422 attribute unsigned long endLine;
423 };
424
425 /**
426 * Notify client code that debugMode has been activated.
427 */
428 [scriptable, function, uuid(6da7f5fb-3a84-4abe-9e23-8b2045960732)]
429 interface jsdIActivationCallback : nsISupports
430 {
431 void onDebuggerActivated();
432 };
433
434 /**
435 * Pass an instance of one of these to jsdIDebuggerService::enterNestedEventLoop.
436 */
437 [scriptable, function, uuid(88bea60f-9b5d-4b39-b08b-1c3a278782c6)]
438 interface jsdINestCallback : nsISupports
439 {
440 /**
441 * This method will be called after pre-nesting work has completed, such
442 * as pushing the js context and network event queue, but before the new
443 * event loop starts.
444 */
445 void onNest();
446 };
447
448 /**
449 * Pass an instance of one of these to jsdIDebuggerService::enumerateFilters.
450 */
451 [scriptable, function, uuid(e391ba85-9379-4762-b387-558e38db730f)]
452 interface jsdIFilterEnumerator : nsISupports
453 {
454 /**
455 * The enumerateFilter method will be called once for every filter the
456 * debugger knows about.
457 */
458 void enumerateFilter(in jsdIFilter filter);
459 };
460
461 /**
462 * Pass an instance of one of these to jsdIDebuggerService::enumerateScripts.
463 */
464 [scriptable, function, uuid(4eef60c2-9bbc-48fa-b196-646a832c6c81)]
465 interface jsdIScriptEnumerator : nsISupports
466 {
467 /**
468 * The enumerateScript method will be called once for every script the
469 * debugger knows about.
470 */
471 void enumerateScript(in jsdIScript script);
472 };
473
474 /**
475 * Pass an instance of one of these to jsdIDebuggerService::enumerateContexts.
476 */
477 [scriptable, function, uuid(57d18286-550c-4ca9-ac33-56f12ebba91e)]
478 interface jsdIContextEnumerator : nsISupports
479 {
480 /**
481 * The enumerateContext method will be called once for every context
482 * currently in use.
483 */
484 void enumerateContext(in jsdIContext executionContext);
485 };
486
487 /**
488 * Set jsdIDebuggerService::scriptHook to an instance of one of these.
489 */
490 [scriptable, uuid(d030d1a2-a58a-4f19-b9e3-96da4e2cdd09)]
491 interface jsdIScriptHook : nsISupports
492 {
493 /**
494 * Called when scripts are created.
495 */
496 void onScriptCreated(in jsdIScript script);
497 /**
498 * Called when the JavaScript engine destroys a script. The jsdIScript
499 * object passed in will already be invalidated.
500 */
501 void onScriptDestroyed(in jsdIScript script);
502 };
503
504 /**
505 * Hook instances of this interface up to the
506 * jsdIDebuggerService::functionHook and toplevelHook properties.
507 */
508 [scriptable, function, uuid(3eff1314-7ae3-4cf8-833b-c33c24a55633)]
509 interface jsdICallHook : nsISupports
510 {
511 /**
512 * TYPE_* values must be kept in sync with the JSD_HOOK_* #defines
513 * in jsdebug.h.
514 */
515
516 /**
517 * Toplevel script is starting.
518 */
519 const unsigned long TYPE_TOPLEVEL_START = 0;
520 /**
521 * Toplevel script has completed.
522 */
523 const unsigned long TYPE_TOPLEVEL_END = 1;
524 /**
525 * Function is being called.
526 */
527 const unsigned long TYPE_FUNCTION_CALL = 2;
528 /**
529 * Function is returning.
530 */
531 const unsigned long TYPE_FUNCTION_RETURN = 3;
532
533 /**
534 * Called before the JavaScript engine executes a top level script or calls
535 * a function.
536 */
537 void onCall(in jsdIStackFrame frame, in unsigned long type);
538 };
539
540 [scriptable, function, uuid(e6b45eee-d974-4d85-9d9e-f5a67218deb4)]
541 interface jsdIErrorHook : nsISupports
542 {
543 /**
544 * REPORT_* values must be kept in sync with JSREPORT_* #defines in
545 * jsapi.h
546 */
547
548 /**
549 * Report is an error.
550 */
551 const unsigned long REPORT_ERROR = 0x00;
552 /**
553 * Report is only a warning.
554 */
555 const unsigned long REPORT_WARNING = 0x01;
556 /**
557 * Report represents an uncaught exception.
558 */
559 const unsigned long REPORT_EXCEPTION = 0x02;
560 /**
561 * Report is due to strict mode.
562 */
563 const unsigned long REPORT_STRICT = 0x04;
564
565 /**
566 * Called when the JavaScript engine encounters an error. Return |true|
567 * to pass the error along, |false| to invoke the debugHook.
568 */
569 boolean onError(in AUTF8String message, in AUTF8String fileName,
570 in unsigned long line, in unsigned long pos,
571 in unsigned long flags, in unsigned long errnum,
572 in jsdIValue exc);
573 };
574
575 /**
576 * Hook instances of this interface up to the
577 * jsdIDebuggerService::breakpointHook, debuggerHook, errorHook, interruptHook,
578 * and throwHook properties.
579 */
580 [scriptable, function, uuid(3a722496-9d78-4f0a-a797-293d9e8cb8d2)]
581 interface jsdIExecutionHook : nsISupports
582 {
583 /**
584 * TYPE_* values must be kept in sync with JSD_HOOK_* #defines in jsdebug.h.
585 */
586
587 /**
588 * Execution stopped because we're in single step mode.
589 */
590 const unsigned long TYPE_INTERRUPTED = 0;
591 /**
592 * Execution stopped by a trap instruction (i.e. breakoint.)
593 */
594 const unsigned long TYPE_BREAKPOINT = 1;
595 /**
596 * Error handler returned an "invoke debugger" value.
597 */
598 const unsigned long TYPE_DEBUG_REQUESTED = 2;
599 /**
600 * Debugger keyword encountered.
601 */
602 const unsigned long TYPE_DEBUGGER_KEYWORD = 3;
603 /**
604 * Exception was thrown.
605 */
606 const unsigned long TYPE_THROW = 4;
607
608 /**
609 * RETURN_* values must be kept in sync with JSD_HOOK_RETURN_* #defines in
610 * jsdebug.h.
611 */
612
613 /**
614 * Indicates unrecoverable error processing the hook. This will cause
615 * the script being executed to be aborted without raising a JavaScript
616 * exception.
617 */
618 const unsigned long RETURN_HOOK_ERROR = 0;
619 /**
620 * Continue processing normally. This is the "do nothing special" return
621 * value for all hook types *except* TYPE_THROW. Returning RETURN_CONTINUE
622 * from TYPE_THROW cause the exception to be ignored. Return
623 * RETURN_CONTINUE_THROW to continue exception processing from TYPE_THROW
624 * hooks.
625 */
626 const unsigned long RETURN_CONTINUE = 1;
627 /**
628 * Same effect as RETURN_HOOK_ERROR.
629 */
630 const unsigned long RETURN_ABORT = 2;
631 /**
632 * Return the value of the |val| parameter.
633 */
634 const unsigned long RETURN_RET_WITH_VAL = 3;
635 /**
636 * Throw the value of the |val| parameter.
637 */
638 const unsigned long RETURN_THROW_WITH_VAL = 4;
639 /**
640 * Continue the current throw.
641 */
642 const unsigned long RETURN_CONTINUE_THROW = 5;
643
644 /**
645 * @param frame A jsdIStackFrame object representing the bottom stack frame.
646 * @param type One of the jsdIExecutionHook::TYPE_ constants.
647 * @param val in - Current exception (if any) when this method is called.
648 * out - If you return RETURN_THROW_WITH_VAL, value to be
649 * thrown.
650 * If you return RETURN_RET_WITH_VAL, value to return.
651 * All other return values, not significant.
652 * @retval One of the jsdIExecutionHook::RETURN_* constants.
653 */
654 unsigned long onExecute(in jsdIStackFrame frame,
655 in unsigned long type, inout jsdIValue val);
656 };
657
658 /**
659 * Objects which inherit this interface may go away, with (jsdIScript) or
660 * without (all others) notification. These objects are generally wrappers
661 * around JSD structures that go away when you call jsdService::Off().
662 */
663 [scriptable, uuid(46f1e23e-1dd2-11b2-9ceb-8285f2e95e69)]
664 interface jsdIEphemeral : nsISupports
665 {
666 /**
667 * |true| if this object is still valid. If not, many or all of the methods
668 * and/or properties of the inheritor may no longer be callable.
669 */
670 readonly attribute boolean isValid;
671 /**
672 * Mark this instance as invalid.
673 */
674 [noscript] void invalidate();
675 };
676
677 /* handle objects */
678
679 /**
680 * Context object. Only context's which are also nsISupports objects can be
681 * reflected by this interface.
682 */
683 [scriptable, uuid(3e5c934d-6863-4d81-96f5-76a3b962fc2b)]
684 interface jsdIContext : jsdIEphemeral
685 {
686 /* Internal use only. */
687 [noscript] readonly attribute JSContext JSContext;
688
689 /**
690 * OPT_* values must be kept in sync with JSOPTION_* #defines in jsapi.h.
691 */
692
693 /**
694 * Strict mode is on.
695 */
696 const long OPT_STRICT = 0x01;
697 /**
698 * Warnings reported as errors.
699 */
700 const long OPT_WERR = 0x02;
701 /**
702 * Makes eval() use the last object on its 'obj' param's scope chain as the
703 * ECMA 'variables object'.
704 */
705 const long OPT_VAROBJFIX = 0x04;
706 /**
707 * Private data for this object is an nsISupports object. Attempting to
708 * alter this bit will result in an NS_ERROR_ILLEGAL_VALUE.
709 */
710 const long OPT_ISUPPORTS = 0x08;
711 /**
712 * OPT_* values above, OR'd together.
713 */
714 attribute unsigned long options;
715
716 /**
717 * Unique tag among all valid jsdIContext objects, useful as a hash key.
718 */
719 readonly attribute unsigned long tag;
720
721 /**
722 * Private data for this context, if it is an nsISupports, |null| otherwise.
723 */
724 readonly attribute nsISupports privateData;
725
726 /**
727 * Retrieve the underlying context wrapped by this jsdIContext.
728 */
729 readonly attribute nsISupports wrappedContext;
730
731 /**
732 * Top of the scope chain for this context.
733 */
734 readonly attribute jsdIValue globalObject;
735
736 /**
737 * |true| if this context should be allowed to run scripts, |false|
738 * otherwise. This attribute is only valid for contexts which implement
739 * nsIScriptContext. Setting or getting this attribute on any other
740 * context will throw a NS_ERROR_NO_INTERFACE exception.
741 */
742 attribute boolean scriptsEnabled;
743 };
744
745 /**
746 * Stack frame objects. These are only valid inside the jsdIExecutionHook which
747 * gave it to you. After you return from that handler the bottom frame, and any
748 * frame you found attached through it, are invalidated via the jsdIEphemeral
749 * interface. Once a jsdIStackFrame has been invalidated all method and
750 * property accesses will throw a NS_ERROR_NOT_AVAILABLE exception.
751 */
752 [scriptable, uuid(7c95422c-7579-4a6f-8ef7-e5b391552ee5)]
753 interface jsdIStackFrame : jsdIEphemeral
754 {
755 /** Internal use only. */
756 [noscript] readonly attribute JSDContext JSDContext;
757 /** Internal use only. */
758 [noscript] readonly attribute JSDThreadState JSDThreadState;
759 /** Internal use only. */
760 [noscript] readonly attribute JSDStackFrameInfo JSDStackFrameInfo;
761
762 /**
763 * True if stack frame represents a frame created as a result of a debugger
764 * evaluation.
765 */
766 readonly attribute boolean isDebugger;
767 /**
768 * True if stack frame is constructing a new object.
769 */
770 readonly attribute boolean isConstructing;
771
772 /**
773 * Link to the caller's stack frame.
774 */
775 readonly attribute jsdIStackFrame callingFrame;
776 /**
777 * Executon context.
778 */
779 readonly attribute jsdIContext executionContext;
780 /**
781 * Function name executing in this stack frame.
782 */
783 readonly attribute AUTF8String functionName;
784 /**
785 * Script running in this stack frame, null for native frames.
786 */
787 readonly attribute jsdIScript script;
788 /**
789 * Current program counter in this stack frame.
790 */
791 readonly attribute unsigned long pc;
792 /**
793 * Current line number (using the script's pc to line map.)
794 */
795 readonly attribute unsigned long line;
796 /**
797 * Function object running in this stack frame.
798 */
799 readonly attribute jsdIValue callee;
800 /**
801 * Top object in the scope chain.
802 */
803 readonly attribute jsdIValue scope;
804 /**
805 * |this| object for this stack frame.
806 */
807 readonly attribute jsdIValue thisValue;
808 /**
809 * Evaluate arbitrary JavaScript in this stack frame.
810 * @param bytes Script to be evaluated.
811 * @param fileName Filename to compile this script under. This is the
812 * filename you'll see in error messages, etc.
813 * @param line Starting line number for this script. One based.
814 * @retval Result of evaluating the script.
815 */
816 boolean eval(in AString bytes, in AUTF8String fileName,
817 in unsigned long line, out jsdIValue result);
818
819 };
820
821 /**
822 * Script object. In JavaScript engine terms, there's a single script for each
823 * function, and one for the top level script.
824 */
825 [scriptable, uuid(8ce9b2a2-cc33-48a8-9f47-8696186ed9a5)]
826 interface jsdIScript : jsdIEphemeral
827 {
828 /** Internal use only. */
829 [noscript] readonly attribute JSDContext JSDContext;
830 /** Internal use only. */
831 [noscript] readonly attribute JSDScript JSDScript;
832
833 /**
834 * Last version set on this context.
835 * Scripts typically select this with the "language" attribute.
836 * See the VERSION_* consts on jsdIDebuggerService.
837 */
838 readonly attribute long version;
839
840 /**
841 * Tag value guaranteed unique among jsdIScript objects. Useful as a
842 * hash key in script.
843 */
844 readonly attribute unsigned long tag;
845
846 /**
847 * FLAG_* values need to be kept in sync with JSD_SCRIPT_* #defines in
848 * jsdebug.h.
849 */
850
851 /**
852 * Determines whether or not to collect profile information for this
853 * script. The context flag FLAG_PROFILE_WHEN_SET decides the logic.
854 */
855 const unsigned long FLAG_PROFILE = 0x01;
856 /**
857 * Determines whether or not to ignore breakpoints, etc. in this script.
858 * The context flag JSD_DEBUG_WHEN_SET decides the logic.
859 */
860 const unsigned long FLAG_DEBUG = 0x02;
861 /**
862 * Determines whether to invoke the onScriptDestroy callback for this
863 * script. The default is for this to be true if the onScriptCreated
864 * callback was invoked for this script.
865 */
866 const unsigned long FLAG_CALL_DESTROY_HOOK = 0x04;
867
868 /**
869 * FLAG_* attributes from above, OR'd together.
870 */
871 attribute unsigned long flags;
872
873 /**
874 * Filename given for this script when it was compiled.
875 * This data is copied from the underlying structure when the jsdIScript
876 * instance is created and is therefore available even after the script is
877 * invalidated.
878 */
879 readonly attribute AUTF8String fileName;
880 /**
881 * Function name for this script. "anonymous" for unnamed functions (or
882 * a function actually named anonymous), empty for top level scripts.
883 * This data is copied from the underlying structure when the jsdIScript
884 * instance is created and is therefore available even after the script is
885 * invalidated.
886 */
887 readonly attribute AUTF8String functionName;
888 /**
889 * The names of the arguments for this function; empty if this is
890 * not a function.
891 */
892 void getParameterNames([optional] out unsigned long count,
893 [array, size_is(count), retval] out wstring paramNames);
894 /**
895 * Fetch the function object as a jsdIValue.
896 */
897 readonly attribute jsdIValue functionObject;
898 /**
899 * Source code for this script, without function declaration.
900 */
901 readonly attribute AString functionSource;
902 /**
903 * Line number in source file containing the first line of this script.
904 * This data is copied from the underlying structure when the jsdIScript
905 * instance is created and is therefore available even after the script is
906 * invalidated.
907 */
908 readonly attribute unsigned long baseLineNumber;
909 /**
910 * Total number of lines in this script.
911 * This data is copied from the underlying structure when the jsdIScript
912 * instance is created and is therefore available even after the script is
913 * invalidated.
914 */
915 readonly attribute unsigned long lineExtent;
916
917 /**
918 * Number of times this script has been called.
919 */
920 readonly attribute unsigned long callCount;
921 /**
922 * Number of times this script called itself, directly or indirectly.
923 */
924 readonly attribute unsigned long maxRecurseDepth;
925 /**
926 * Shortest execution time recorded, in milliseconds.
927 */
928 readonly attribute double minExecutionTime;
929 /**
930 * Longest execution time recorded, in milliseconds.
931 */
932 readonly attribute double maxExecutionTime;
933 /**
934 * Total time spent in this function, in milliseconds.
935 */
936 readonly attribute double totalExecutionTime;
937 /**
938 * Shortest execution time recorded, in milliseconds, excluding time spent
939 * in other called code.
940 */
941 readonly attribute double minOwnExecutionTime;
942 /**
943 * Longest execution time recorded, in milliseconds, excluding time spent
944 * in other called code.
945 */
946 readonly attribute double maxOwnExecutionTime;
947 /**
948 * Total time spent in this function, in milliseconds, excluding time spent
949 * in other called code.
950 */
951 readonly attribute double totalOwnExecutionTime;
952
953 /**
954 * Clear profile data for this script.
955 */
956 void clearProfileData();
957
958 const unsigned long PCMAP_SOURCETEXT = 1; /* map to actual source text */
959 const unsigned long PCMAP_PRETTYPRINT = 2; /* map to pretty printed source */
960
961 /**
962 * Get the closest line number to a given PC.
963 * The |pcmap| argument specifies which pc to source line map to use.
964 */
965 unsigned long pcToLine(in unsigned long pc, in unsigned long pcmap);
966 /**
967 * Get the first PC associated with a line.
968 * The |pcmap| argument specifies which pc to source line map to use.
969 */
970 unsigned long lineToPc(in unsigned long line, in unsigned long pcmap);
971 /**
972 * Determine is a particular line is executable, like checking that
973 * lineToPc == pcToLine, except in one call.
974 * The |pcmap| argument specifies which pc to source line map to use.
975 */
976 boolean isLineExecutable(in unsigned long line, in unsigned long pcmap);
977
978 /**
979 * Return a list of all executable lines in a script.
980 * |pcmap| specifies which pc to source line map to use.
981 * |startLine| and |maxLines| may be used to retrieve a chunk at a time.
982 */
983 void getExecutableLines(in unsigned long pcmap,
984 in unsigned long startLine, in unsigned long maxLines,
985 [optional] out unsigned long count,
986 [array, size_is(count), retval] out unsigned long executableLines);
987
988 /**
989 * Set a breakpoint at a PC in this script.
990 */
991 void setBreakpoint(in unsigned long pc);
992 /**
993 * Clear a breakpoint at a PC in this script.
994 */
995 void clearBreakpoint(in unsigned long pc);
996 /**
997 * Clear all breakpoints set in this script.
998 */
999 void clearAllBreakpoints();
1000 /**
1001 * Call interrupt hook at least once per source line
1002 */
1003 void enableSingleStepInterrupts(in boolean mode);
1004 };
1005
1006 /**
1007 * Value objects. Represents typeless JavaScript values (jsval in SpiderMonkey
1008 * terminology.) These are valid until the debugger is turned off. Holding a
1009 * jsdIValue adds a root for the underlying JavaScript value, so don't keep it
1010 * if you don't need to.
1011 */
1012 [scriptable, uuid(1cd3535b-4ddb-4202-9053-e0ec88f5c82b)]
1013 interface jsdIValue : jsdIEphemeral
1014 {
1015 /** Internal use only. */
1016 [noscript] readonly attribute JSDContext JSDContext;
1017 /** Internal use only. */
1018 [noscript] readonly attribute JSDValue JSDValue;
1019
1020 /**
1021 * |false| unless the value is a function declared in script.
1022 */
1023 readonly attribute boolean isNative;
1024 /**
1025 * |true| if the value represents a number, either double or integer.
1026 * |false| for all other values, including numbers assigned as strings
1027 * (eg. x = "1";)
1028 */
1029 readonly attribute boolean isNumber;
1030 /**
1031 * |true| if the value represents a JavaScript primitive number or AUTF8String
1032 */
1033 readonly attribute boolean isPrimitive;
1034
1035 /** Value is either |true| or |false|. */
1036 const unsigned long TYPE_BOOLEAN = 0;
1037 /** Value is a primitive number that is too large to fit in an integer. */
1038 const unsigned long TYPE_DOUBLE = 1;
1039 /** Value is a primitive number that fits into an integer. */
1040 const unsigned long TYPE_INT = 2;
1041 /** Value is a function. */
1042 const unsigned long TYPE_FUNCTION = 3;
1043 /** Value is |null|. */
1044 const unsigned long TYPE_NULL = 4;
1045 /** Value is an object. */
1046 const unsigned long TYPE_OBJECT = 5;
1047 /** Value is a primitive AUTF8String. */
1048 const unsigned long TYPE_STRING = 6;
1049 /** Value is void. */
1050 const unsigned long TYPE_VOID = 7;
1051
1052 /**
1053 * One of the TYPE_* values above.
1054 */
1055 readonly attribute unsigned long jsType;
1056 /**
1057 * Prototype value if this value represents an object, null if the value is
1058 * not an object or the object has no prototype.
1059 */
1060 readonly attribute jsdIValue jsPrototype;
1061 /**
1062 * Parent value if this value represents an object, null if the value is not
1063 * an object or the object has no parent.
1064 */
1065 readonly attribute jsdIValue jsParent;
1066 /**
1067 * Class name if this value represents an object. Empty AUTF8String if the value
1068 * is not an object.
1069 */
1070 readonly attribute AUTF8String jsClassName;
1071 /**
1072 * Constructor name if this value represents an object. Empty AUTF8String if the
1073 * value is not an object.
1074 */
1075 readonly attribute jsdIValue jsConstructor;
1076 /**
1077 * Function name if this value represents a function. Empty AUTF8String if the
1078 * value is not a function.
1079 */
1080 readonly attribute AUTF8String jsFunctionName;
1081
1082 /**
1083 * Value if interpreted as a boolean. Converts if necessary.
1084 */
1085 readonly attribute boolean booleanValue;
1086 /**
1087 * Value if interpreted as a double. Converts if necessary.
1088 */
1089 readonly attribute double doubleValue;
1090 /**
1091 * Value if interpreted as an integer. Converts if necessary.
1092 */
1093 readonly attribute long intValue;
1094 /**
1095 * Value if interpreted as an object.
1096 */
1097 readonly attribute jsdIObject objectValue;
1098 /**
1099 * Value if interpreted as a AUTF8String. Converts if necessary.
1100 */
1101 readonly attribute AUTF8String stringValue;
1102
1103 /**
1104 * Number of properties. 0 if the value is not an object, or the value is
1105 * an object but has no properties.
1106 */
1107 readonly attribute long propertyCount;
1108
1109 /**
1110 * Retrieves all properties if this value represents an object. If this
1111 * value is not an object a 0 element array is returned.
1112 * @param propArray Array of jsdIProperty values for this value.
1113 * @param length Size of array.
1114 */
1115 void getProperties([array, size_is(length)] out jsdIProperty propArray,
1116 out unsigned long length);
1117 /**
1118 * Retrieves a single property from the value. Only valid if the value
1119 * represents an object.
1120 * @param name Name of the property to retrieve.
1121 * @retval jsdIProperty for the requested property name or null if no
1122 * property exists for the requested name.
1123 */
1124 jsdIProperty getProperty(in AUTF8String name);
1125
1126 /**
1127 * jsdIValues are wrappers around JavaScript engine structures. Much of the
1128 * data is copied instead of shared. The refresh method is used to resync
1129 * the jsdIValue with the underlying structure.
1130 */
1131 void refresh();
1132
1133 /**
1134 * When called from JavaScript, this method returns the JavaScript value
1135 * wrapped by this jsdIValue. The calling script is free to use the result
1136 * as it would any other JavaScript value.
1137 * When called from another language this method returns an xpconnect
1138 * defined error code.
1139 */
1140 [implicit_jscontext] jsval getWrappedValue();
1141
1142 /**
1143 * If this is a function value, return its associated jsdIScript.
1144 * Otherwise, return null.
1145 */
1146 readonly attribute jsdIScript script;
1147 };
1148
1149 /**
1150 * Properties specific to values which are also objects.
1151 * XXX We don't add roots for these yet, so make sure you hold on to the
1152 * jsdIValue from whence your jsdIObject instance came for at least as long as
1153 * you hold the jsdIObject.
1154 * XXX Maybe the jsClassName, jsConstructorName, and property related attribute/
1155 * functions from jsdIValue should move to this interface. We could inherit from
1156 * jsdIValue or use interface flattening or something.
1157 */
1158 [scriptable, uuid(87d86308-7a27-4255-b23c-ce2394f02473)]
1159 interface jsdIObject : nsISupports
1160 {
1161 /** Internal use only. */
1162 [noscript] readonly attribute JSDContext JSDContext;
1163 /** Internal use only. */
1164 [noscript] readonly attribute JSDObject JSDObject;
1165
1166 /**
1167 * The URL (filename) that contains the script which caused this object
1168 * to be created.
1169 */
1170 readonly attribute AUTF8String creatorURL;
1171 /**
1172 * Line number in the creatorURL where this object was created.
1173 */
1174 readonly attribute unsigned long creatorLine;
1175 /**
1176 * The URL (filename) that contains the script which defined the constructor
1177 * used to create this object.
1178 */
1179 readonly attribute AUTF8String constructorURL;
1180 /**
1181 * Line number in the creatorURL where this object was created.
1182 */
1183 readonly attribute unsigned long constructorLine;
1184 /**
1185 * jsdIValue for this object.
1186 */
1187 readonly attribute jsdIValue value;
1188 };
1189
1190 /**
1191 * Representation of a property of an object. When an instance is invalid, all
1192 * method and property access will result in a NS_UNAVAILABLE error.
1193 */
1194 [scriptable, uuid(acf1329e-aaf6-4d6a-a1eb-f75858566f09)]
1195 interface jsdIProperty : jsdIEphemeral
1196 {
1197 /** Internal use only. */
1198 [noscript] readonly attribute JSDContext JSDContext;
1199 /** Internal use only. */
1200 [noscript] readonly attribute JSDProperty JSDProperty;
1201
1202 /**
1203 * FLAG_* values must be kept in sync with JSDPD_* #defines in jsdebug.h.
1204 */
1205
1206 /** visible to for/in loop */
1207 const unsigned long FLAG_ENUMERATE = 0x01;
1208 /** assignment is error */
1209 const unsigned long FLAG_READONLY = 0x02;
1210 /** property cannot be deleted */
1211 const unsigned long FLAG_PERMANENT = 0x04;
1212 /** property has an alias id */
1213 const unsigned long FLAG_ALIAS = 0x08;
1214 /** argument to function */
1215 const unsigned long FLAG_ARGUMENT = 0x10;
1216 /** local variable in function */
1217 const unsigned long FLAG_VARIABLE = 0x20;
1218 /** exception occurred looking up property, value is exception */
1219 const unsigned long FLAG_EXCEPTION = 0x40;
1220 /** native getter returned false without throwing an exception */
1221 const unsigned long FLAG_ERROR = 0x80;
1222 /** found via explicit lookup (property defined elsewhere.) */
1223 const unsigned long FLAG_HINTED = 0x800;
1224
1225 /** FLAG_* values OR'd together, representing the flags for this property. */
1226 readonly attribute unsigned long flags;
1227 /** jsdIValue representing the alias for this property. */
1228 readonly attribute jsdIValue alias;
1229 /** name for this property. */
1230 readonly attribute jsdIValue name;
1231 /** value of this property. */
1232 readonly attribute jsdIValue value;
1233 };

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial