js/jsd/jsdebug.h

   1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 1998
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 /*
  39  * Header for JavaScript Debugging support - All public functions
  40  */
  41
  42 #ifndef jsdebug_h___
  43 #define jsdebug_h___
  44
  45 /* Get jstypes.h included first. After that we can use PR macros for doing
  46 *  this extern "C" stuff!
  47 */
  48 #ifdef __cplusplus
  49 extern "C"
  50 {
  51 #endif
  52 #include "jstypes.h"
  53 #ifdef __cplusplus
  54 }
  55 #endif
  56
  57 #include "jsapi.h"
  58 #include "jsdbgapi.h"
  59 #ifdef LIVEWIRE
  60 #include "lwdbgapi.h"
  61 #endif
  62
  63 JS_BEGIN_EXTERN_C
  64
  65 /*
  66  * The linkage of JSD API functions differs depending on whether the file is
  67  * used within the JSD library or not.  Any source file within the JSD
  68  * libraray should define EXPORT_JSD_API whereas any client of the library
  69  * should not.
  70  */
  71 #ifdef EXPORT_JSD_API
  72 #define JSD_PUBLIC_API(t)    JS_EXPORT_API(t)
  73 #define JSD_PUBLIC_DATA(t)   JS_EXPORT_DATA(t)
  74 #else
  75 #define JSD_PUBLIC_API(t)    JS_IMPORT_API(t)
  76 #define JSD_PUBLIC_DATA(t)   JS_IMPORT_DATA(t)
  77 #endif
  78
  79 #define JSD_FRIEND_API(t)    JSD_PUBLIC_API(t)
  80 #define JSD_FRIEND_DATA(t)   JSD_PUBLIC_DATA(t)
  81
  82 /***************************************************************************/
  83 /* Opaque typedefs for handles */
  84
  85 typedef struct JSDContext        JSDContext;
  86 typedef struct JSDScript         JSDScript;
  87 typedef struct JSDSourceText     JSDSourceText;
  88 typedef struct JSDThreadState    JSDThreadState;
  89 typedef struct JSDStackFrameInfo JSDStackFrameInfo;
  90 typedef struct JSDValue          JSDValue;
  91 typedef struct JSDProperty       JSDProperty;
  92 typedef struct JSDObject         JSDObject;
  93
  94 /***************************************************************************/
  95 /* High Level calls */
  96
  97 /*
  98 * callback stuff for calls in EXE to be accessed by this code
  99 * when it lives in an explicitly loaded DLL
 100 */
 101
 102 /*
 103 * This callback allows JSD to inform the embedding when JSD has been
 104 * turned on or off. This is especially useful in the Java-based debugging
 105 * system used in mozilla because the debugger applet controls starting
 106 * up the JSD system.
 107 */
 108 typedef void
 109 (* JSD_SetContextProc)(JSDContext* jsdc, void* user);
 110
 111 /* This struct could have more fields in future versions */
 112 typedef struct
 113 {
 114     uintN              size;       /* size of this struct (init before use)*/
 115     JSD_SetContextProc setContext;
 116 } JSD_UserCallbacks;
 117
 118 /*
 119 * Used by an embedding to tell JSD what JSRuntime to use and to set
 120 * callbacks without starting up JSD. This assumes only one JSRuntime
 121 * will be used. This exists to support the mozilla Java-based debugger
 122 * system.
 123 */
 124 extern JSD_PUBLIC_API(void)
 125 JSD_SetUserCallbacks(JSRuntime*         jsrt,
 126                      JSD_UserCallbacks* callbacks,
 127                      void*              user);
 128
 129 /*
 130 * Startup JSD.
 131 * This version of the init function requires that JSD_SetUserCallbacks()
 132 * has been previously called (with a non-NULL callback struct pointer)
 133 */
 134 extern JSD_PUBLIC_API(JSDContext*)
 135 JSD_DebuggerOn(void);
 136
 137 /*
 138 * Startup JSD on a particular JSRuntime with (optional) callbacks
 139 */
 140 extern JSD_PUBLIC_API(JSDContext*)
 141 JSD_DebuggerOnForUser(JSRuntime*         jsrt,
 142                       JSD_UserCallbacks* callbacks,
 143                       void*              user);
 144
 145 /*
 146  * Startup JSD in an application that uses compartments. Debugger
 147  * objects will be allocated in the same compartment as scopeobj.
 148  */
 149 extern JSD_PUBLIC_API(JSDContext*)
 150 JSD_DebuggerOnForUserWithCompartment(JSRuntime*         jsrt,
 151                                      JSD_UserCallbacks* callbacks,
 152                                      void*              user,
 153                                      JSObject*          scopeobj);
 154
 155 /*
 156 * Shutdown JSD for this JSDContext
 157 */
 158 extern JSD_PUBLIC_API(void)
 159 JSD_DebuggerOff(JSDContext* jsdc);
 160
 161 /*
 162  * Pause JSD for this JSDContext
 163  */
 164 extern JSD_PUBLIC_API(void)
 165 JSD_DebuggerPause(JSDContext* jsdc);
 166
 167 /*
 168  * Unpause JSD for this JSDContext
 169  */
 170 extern JSD_PUBLIC_API(void)
 171 JSD_DebuggerUnpause(JSDContext* jsdc);
 172
 173 /*
 174 * Get the Major Version (initial JSD release used major version = 1)
 175 */
 176 extern JSD_PUBLIC_API(uintN)
 177 JSD_GetMajorVersion(void);
 178
 179 /*
 180 * Get the Minor Version (initial JSD release used minor version = 0)
 181 */
 182 extern JSD_PUBLIC_API(uintN)
 183 JSD_GetMinorVersion(void);
 184
 185 /*
 186 * Returns a 'dumb' JSContext that can be used for utility purposes as needed
 187 */
 188 extern JSD_PUBLIC_API(JSContext*)
 189 JSD_GetDefaultJSContext(JSDContext* jsdc);
 190
 191 /*
 192 * Set the private data for this context, returns previous value
 193 */
 194 extern JSD_PUBLIC_API(void *)
 195 JSD_SetContextPrivate(JSDContext *jsdc, void *data);
 196
 197 /*
 198 * Get the private data for this context
 199 */
 200 extern JSD_PUBLIC_API(void *)
 201 JSD_GetContextPrivate(JSDContext *jsdc);
 202
 203 /*
 204 * Clear profile data for all scripts
 205 */
 206 extern JSD_PUBLIC_API(void)
 207 JSD_ClearAllProfileData(JSDContext* jsdc);
 208
 209 /*
 210 * Context flags.
 211 */
 212
 213 /* Include native frames in JSDThreadStates. */
 214 #define JSD_INCLUDE_NATIVE_FRAMES 0x01
 215 /*
 216 * Normally, if a script has a 0 in JSD_SCRIPT_PROFILE_BIT it is included in
 217 * profile data, otherwise it is not profiled.  Setting the JSD_PROFILE_WHEN_SET
 218 * flag reverses this convention.
 219 */
 220 #define JSD_PROFILE_WHEN_SET      0x02
 221 /*
 222 * Normally, when the script in the top frame of a thread state has a 1 in
 223 * JSD_SCRIPT_DEBUG_BIT, the execution hook is ignored.  Setting the
 224 * JSD_DEBUG_WHEN_SET flag reverses this convention.
 225 */
 226 #define JSD_DEBUG_WHEN_SET        0x04
 227 /*
 228 * When this flag is set the internal call hook will collect profile data.
 229 */
 230 #define JSD_COLLECT_PROFILE_DATA  0x08
 231 /*
 232 * When this flag is set, stack frames that are disabled for debugging
 233 * will not appear in the call stack chain.
 234 */
 235 #define JSD_HIDE_DISABLED_FRAMES  0x10
 236 /*
 237 * When this flag is set, the debugger will only check the
 238 * JSD_SCRIPT_DEBUG_BIT on the top (most recent) stack frame.  This
 239 * makes it possible to stop in an enabled frame which was called from
 240 * a stack that contains a disabled frame.
 241 *
 242 * When this flag is *not* set, any stack that contains a disabled frame
 243 * will not be debugged (the execution hook will not be invoked.)
 244 *
 245 * This only applies when the reason for calling the hook would have
 246 * been JSD_HOOK_INTERRUPTED or JSD_HOOK_THROW.  JSD_HOOK_BREAKPOINT,
 247 * JSD_HOOK_DEBUG_REQUESTED, and JSD_HOOK_DEBUGGER_KEYWORD always stop,
 248 * regardless of this setting, as long as the top frame is not disabled.
 249 *
 250 * If JSD_HIDE_DISABLED_FRAMES is set, this is effectively set as well.
 251 */
 252 #define JSD_MASK_TOP_FRAME_ONLY   0x20
 253
 254 /*
 255 * 0x40 was formerly used to hook into object creation.
 256 */
 257 #define JSD_DISABLE_OBJECT_TRACE_RETIRED 0x40
 258
 259
 260 extern JSD_PUBLIC_API(void)
 261 JSD_SetContextFlags (JSDContext* jsdc, uint32 flags);
 262
 263 extern JSD_PUBLIC_API(uint32)
 264 JSD_GetContextFlags (JSDContext* jsdc);
 265
 266 /*
 267 * Notify JSD that this JSContext is 'in use'. This allows JSD to hook the
 268 * ErrorReporter. For the most part this is done automatically whenever
 269 * events like script loading happen. But, it is a good idea to call this
 270 * from the embedding when new contexts come into use.
 271 */
 272 extern JSD_PUBLIC_API(void)
 273 JSD_JSContextInUse(JSDContext* jsdc, JSContext* context);
 274
 275 /*
 276 * Find the JSDContext (if any) associated with the JSRuntime of a
 277 * given JSContext.
 278 */
 279 extern JSD_PUBLIC_API(JSDContext*)
 280 JSD_JSDContextForJSContext(JSContext* context);
 281
 282 /***************************************************************************/
 283 /* Script functions */
 284
 285 /*
 286 * Lock the entire script subsystem. This grabs a highlevel lock that
 287 * protects the JSD internal information about scripts. It is important
 288 * to wrap script related calls in this lock in multithreaded situations
 289 * -- i.e. where the debugger is running on a different thread than the
 290 * interpreter -- or when multiple debugger threads may be accessing this
 291 * subsystem. It is safe (and best) to use this locking even if the
 292 * environment might not be multi-threaded. Safely nestable.
 293 */
 294 extern JSD_PUBLIC_API(void)
 295 JSD_LockScriptSubsystem(JSDContext* jsdc);
 296
 297 /*
 298 * Unlock the entire script subsystem -- see JSD_LockScriptSubsystem
 299 */
 300 extern JSD_PUBLIC_API(void)
 301 JSD_UnlockScriptSubsystem(JSDContext* jsdc);
 302
 303 /*
 304 * Iterate through all the active scripts for this JSDContext.
 305 * NOTE: must initialize iterp to NULL to start iteration.
 306 * NOTE: must lock and unlock the subsystem
 307 * example:
 308 *
 309 *  JSDScript jsdscript;
 310 *  JSDScript iter = NULL;
 311 *
 312 *  JSD_LockScriptSubsystem(jsdc);
 313 *  while((jsdscript = JSD_IterateScripts(jsdc, &iter)) != NULL) {
 314 *     *** use jsdscript here ***
 315 *  }
 316 *  JSD_UnlockScriptSubsystem(jsdc);
 317 */
 318 extern JSD_PUBLIC_API(JSDScript*)
 319 JSD_IterateScripts(JSDContext* jsdc, JSDScript **iterp);
 320
 321 /*
 322 * Get the number of times this script has been called.
 323 */
 324 extern JSD_PUBLIC_API(uintN)
 325 JSD_GetScriptCallCount(JSDContext* jsdc, JSDScript *script);
 326
 327 /*
 328 * Get the max number of times this script called itself, directly or indirectly.
 329 */
 330 extern JSD_PUBLIC_API(uintN)
 331 JSD_GetScriptMaxRecurseDepth(JSDContext* jsdc, JSDScript *script);
 332
 333 /*
 334 * Get the shortest execution time recorded.
 335 */
 336 extern JSD_PUBLIC_API(jsdouble)
 337 JSD_GetScriptMinExecutionTime(JSDContext* jsdc, JSDScript *script);
 338
 339 /*
 340 * Get the longest execution time recorded.
 341 */
 342 extern JSD_PUBLIC_API(jsdouble)
 343 JSD_GetScriptMaxExecutionTime(JSDContext* jsdc, JSDScript *script);
 344
 345 /*
 346 * Get the total amount of time spent in this script.
 347 */
 348 extern JSD_PUBLIC_API(jsdouble)
 349 JSD_GetScriptTotalExecutionTime(JSDContext* jsdc, JSDScript *script);
 350
 351 /*
 352 * Get the shortest execution time recorded, excluding time spent in called
 353 * functions.
 354 */
 355 extern JSD_PUBLIC_API(jsdouble)
 356 JSD_GetScriptMinOwnExecutionTime(JSDContext* jsdc, JSDScript *script);
 357
 358 /*
 359 * Get the longest execution time recorded, excluding time spent in called
 360 * functions.
 361 */
 362 extern JSD_PUBLIC_API(jsdouble)
 363 JSD_GetScriptMaxOwnExecutionTime(JSDContext* jsdc, JSDScript *script);
 364
 365 /*
 366 * Get the total amount of time spent in this script, excluding time spent
 367 * in called functions.
 368 */
 369 extern JSD_PUBLIC_API(jsdouble)
 370 JSD_GetScriptTotalOwnExecutionTime(JSDContext* jsdc, JSDScript *script);
 371
 372 /*
 373 * Clear profile data for this script.
 374 */
 375 extern JSD_PUBLIC_API(void)
 376 JSD_ClearScriptProfileData(JSDContext* jsdc, JSDScript *script);
 377
 378 /*
 379 * Get the JSScript for a JSDScript
 380 */
 381 extern JSD_PUBLIC_API(JSScript*)
 382 JSD_GetJSScript(JSDContext* jsdc, JSDScript *script);
 383
 384 /*
 385 * Get the JSFunction for a JSDScript
 386 */
 387 extern JSD_PUBLIC_API(JSFunction*)
 388 JSD_GetJSFunction(JSDContext* jsdc, JSDScript *script);
 389
 390 /*
 391 * Determines whether or not to collect profile information for this
 392 * script.  The context flag JSD_PROFILE_WHEN_SET decides the logic.
 393 */
 394 #define JSD_SCRIPT_PROFILE_BIT 0x01
 395 /*
 396 * Determines whether or not to ignore breakpoints, etc. in this script.
 397 * The context flag JSD_DEBUG_WHEN_SET decides the logic.
 398 */
 399 #define JSD_SCRIPT_DEBUG_BIT   0x02
 400
 401 extern JSD_PUBLIC_API(uint32)
 402 JSD_GetScriptFlags(JSDContext *jsdc, JSDScript* jsdscript);
 403
 404 extern JSD_PUBLIC_API(void)
 405 JSD_SetScriptFlags(JSDContext *jsdc, JSDScript* jsdscript, uint32 flags);
 406
 407 /*
 408 * Set the private data for this script, returns previous value
 409 */
 410 extern JSD_PUBLIC_API(void *)
 411 JSD_SetScriptPrivate(JSDScript* jsdscript, void *data);
 412
 413 /*
 414 * Get the private data for this script
 415 */
 416 extern JSD_PUBLIC_API(void *)
 417 JSD_GetScriptPrivate(JSDScript* jsdscript);
 418
 419 /*
 420 * Determine if this script is still loaded in the interpreter
 421 */
 422 extern JSD_PUBLIC_API(JSBool)
 423 JSD_IsActiveScript(JSDContext* jsdc, JSDScript *jsdscript);
 424
 425 /*
 426 * Get the filename associated with this script
 427 */
 428 extern JSD_PUBLIC_API(const char*)
 429 JSD_GetScriptFilename(JSDContext* jsdc, JSDScript *jsdscript);
 430
 431 /*
 432 * Get the function name associated with this script (NULL if not a function).
 433 * If the function does not have a name the result is the string "anonymous".
 434 * *** new for gecko 2.0 ****
 435 */
 436 extern JSD_PUBLIC_API(JSString *)
 437 JSD_GetScriptFunctionId(JSDContext* jsdc, JSDScript *jsdscript);
 438
 439 /*
 440 * Get the base linenumber of the sourcefile from which this script was loaded.
 441 * This is one-based -- i.e. the first line of a file is line '1'. This may
 442 * return 0 if this infomation is unknown.
 443 */
 444 extern JSD_PUBLIC_API(uintN)
 445 JSD_GetScriptBaseLineNumber(JSDContext* jsdc, JSDScript *jsdscript);
 446
 447 /*
 448 * Get the count of source lines associated with this script (1 or greater)
 449 */
 450 extern JSD_PUBLIC_API(uintN)
 451 JSD_GetScriptLineExtent(JSDContext* jsdc, JSDScript *jsdscript);
 452
 453 /*
 454 * Declaration of callback for notification of script creation and destruction.
 455 * 'creating' is JS_TRUE if creating new script, JS_FALSE if destroying existing
 456 * script (callback called just before actual destruction).
 457 * 'callerdata' is what was passed to JSD_SetScriptHook to set the hook.
 458 */
 459 typedef void
 460 (* JSD_ScriptHookProc)(JSDContext* jsdc,
 461                        JSDScript*  jsdscript,
 462                        JSBool      creating,
 463                        void*       callerdata);
 464
 465 /*
 466 * Set a hook to be called when scripts are created or destroyed (loaded or
 467 * unloaded).
 468 * 'callerdata' can be whatever you want it to be.
 469 */
 470 extern JSD_PUBLIC_API(JSBool)
 471 JSD_SetScriptHook(JSDContext* jsdc, JSD_ScriptHookProc hook, void* callerdata);
 472
 473 /*
 474 * Get the current script hook.
 475 */
 476 extern JSD_PUBLIC_API(JSBool)
 477 JSD_GetScriptHook(JSDContext* jsdc, JSD_ScriptHookProc* hook, void** callerdata);
 478
 479 /*
 480 * Get a 'Program Counter' value for a given line. This represents the location
 481 * of the first bit of executable code for this line of source. This 'pc' should
 482 * be considered an opaque handle.
 483 * 0 is returned for invalid scripts, or lines that lie outside the script.
 484 * If no code is on the given line, then the returned pc represents the first
 485 * code within the script (if any) after the given line.
 486 * This function can be used to set breakpoints -- see JSD_SetExecutionHook
 487 */
 488 extern JSD_PUBLIC_API(jsuword)
 489 JSD_GetClosestPC(JSDContext* jsdc, JSDScript* jsdscript, uintN line);
 490
 491 /*
 492 * Get the source line number for a given 'Program Counter' location.
 493 * Returns 0 if no source line information is appropriate (or available) for
 494 * the given pc.
 495 */
 496 extern JSD_PUBLIC_API(uintN)
 497 JSD_GetClosestLine(JSDContext* jsdc, JSDScript* jsdscript, jsuword pc);
 498
 499 /* these are only used in cases where scripts are created outside of JS*/
 500
 501 /*
 502 * Direct call to notify JSD that a script has been created.
 503 * Embeddings that use the normal jsapi script functions need not call this.
 504 * Any embedding that follows the (discouraged!) practice of contructing script
 505 * structures manually should call this function to inform JSD. (older ssjs
 506 * systems do this).
 507 */
 508 extern JSD_PUBLIC_API(void)
 509 JSD_ScriptCreated(JSDContext* jsdc,
 510                   JSContext   *cx,
 511                   const char  *filename,    /* URL this script loads from */
 512                   uintN       lineno,       /* line where this script starts */
 513                   JSScript    *script,
 514                   JSFunction  *fun);
 515
 516 /*
 517 * see JSD_ScriptCreated
 518 */
 519 extern JSD_PUBLIC_API(void)
 520 JSD_ScriptDestroyed(JSDContext* jsdc,
 521                     JSContext   *cx,
 522                     JSScript    *script);
 523
 524 /***************************************************************************/
 525 /* Source Text functions */
 526
 527 /*
 528 * In some embeddings (e.g. mozilla) JavaScript source code from a 'file' may be
 529 * execute before the entire 'file' has even been loaded. This system supports
 530 * access to such incrmentally loaded source. It also allows for the possibility
 531 * that source loading may fail or be aborted (though the source that did load
 532 * may still be usable). Remember that this source is the entire 'file'
 533 * contents and that the JavaScript code may only be part of that source.
 534 *
 535 * For any given URL there can only be one source text item (the most recently
 536 * loaded).
 537 */
 538
 539 /* these coorespond to netscape.jsdebug.SourceTextItem.java values -
 540 *  change in both places if anywhere
 541 */
 542
 543 typedef enum
 544 {
 545     JSD_SOURCE_INITED       = 0, /* initialized, but contains no source yet */
 546     JSD_SOURCE_PARTIAL      = 1, /* some source loaded, more expected */
 547     JSD_SOURCE_COMPLETED    = 2, /* all source finished loading */
 548     JSD_SOURCE_ABORTED      = 3, /* user aborted loading, some may be loaded */
 549     JSD_SOURCE_FAILED       = 4, /* loading failed, some may be loaded */
 550     JSD_SOURCE_CLEARED      = 5  /* text has been cleared by debugger */
 551 } JSDSourceStatus;
 552
 553 /*
 554 * Lock the entire source text subsystem. This grabs a highlevel lock that
 555 * protects the JSD internal information about sources. It is important to
 556 * wrap source text related calls in this lock in multithreaded situations
 557 * -- i.e. where the debugger is running on a different thread than the
 558 * interpreter (or the loader of sources) -- or when multiple debugger
 559 * threads may be accessing this subsystem. It is safe (and best) to use
 560 * this locking even if the environment might not be multi-threaded.
 561 * Safely Nestable.
 562 */
 563 extern JSD_PUBLIC_API(void)
 564 JSD_LockSourceTextSubsystem(JSDContext* jsdc);
 565
 566 /*
 567 * Unlock the entire source text subsystem. see JSD_LockSourceTextSubsystem.
 568 */
 569 extern JSD_PUBLIC_API(void)
 570 JSD_UnlockSourceTextSubsystem(JSDContext* jsdc);
 571
 572 /*
 573 * Iterate the source test items. Use the same pattern of calls shown in
 574 * the example for JSD_IterateScripts - NOTE that the SourceTextSubsystem.
 575 * must be locked before and unlocked after iterating.
 576 */
 577 extern JSD_PUBLIC_API(JSDSourceText*)
 578 JSD_IterateSources(JSDContext* jsdc, JSDSourceText **iterp);
 579
 580 /*
 581 * Find the source text item for the given URL (or filename - or whatever
 582 * string the given embedding uses to describe source locations).
 583 * Returns NULL is not found.
 584 */
 585 extern JSD_PUBLIC_API(JSDSourceText*)
 586 JSD_FindSourceForURL(JSDContext* jsdc, const char* url);
 587
 588 /*
 589 * Get the URL string associated with the given source text item
 590 */
 591 extern JSD_PUBLIC_API(const char*)
 592 JSD_GetSourceURL(JSDContext* jsdc, JSDSourceText* jsdsrc);
 593
 594 /*
 595 * Get the actual source text. This gives access to the actual storage of
 596 * the source - it sHould *not* be written to.
 597 * The buffer is NOT zero terminated (nor is it guaranteed to have space to
 598 * hold a zero terminating char).
 599 * XXX this is 8-bit character data. Unicode source is not yet supported.
 600 */
 601 extern JSD_PUBLIC_API(JSBool)
 602 JSD_GetSourceText(JSDContext* jsdc, JSDSourceText* jsdsrc,
 603                   const char** ppBuf, intN* pLen);
 604
 605 /*
 606 * Clear the text -- delete the text and set the status to JSD_SOURCE_CLEARED.
 607 * This is useful if source is done loading and the debugger wishes to store
 608 * the text data itself (e.g. in a Java String). This allows avoidance of
 609 * storing the same text in multiple places.
 610 */
 611 extern JSD_PUBLIC_API(void)
 612 JSD_ClearSourceText(JSDContext* jsdc, JSDSourceText* jsdsrc);
 613
 614 /*
 615 * Return the status of the source text item. see JSDSourceStatus enum.
 616 */
 617 extern JSD_PUBLIC_API(JSDSourceStatus)
 618 JSD_GetSourceStatus(JSDContext* jsdc, JSDSourceText* jsdsrc);
 619
 620 /*
 621 * Has the source been altered since the last call to JSD_SetSourceDirty?
 622 * Use of JSD_IsSourceDirty and JSD_SetSourceDirty is still supported, but
 623 * discouraged in favor of the JSD_GetSourceAlterCount system. This dirty
 624 * scheme ASSUMES that there is only one consumer of the data.
 625 */
 626 extern JSD_PUBLIC_API(JSBool)
 627 JSD_IsSourceDirty(JSDContext* jsdc, JSDSourceText* jsdsrc);
 628
 629 /*
 630 * Clear the dirty flag
 631 */
 632 extern JSD_PUBLIC_API(void)
 633 JSD_SetSourceDirty(JSDContext* jsdc, JSDSourceText* jsdsrc, JSBool dirty);
 634
 635 /*
 636 * Each time a source text item is altered this value is incremented. Any
 637 * consumer can store this value when they retieve other data about the
 638 * source text item and then check later to see if the current value is
 639 * different from their stored value. Thus they can know if they have stale
 640 * data or not. NOTE: this value is not gauranteed to start at any given number.
 641 */
 642 extern JSD_PUBLIC_API(uintN)
 643 JSD_GetSourceAlterCount(JSDContext* jsdc, JSDSourceText* jsdsrc);
 644
 645 /*
 646 * Force an increment in the alter count for a source text item. This is
 647 * normally automatic when the item changes, but a give consumer may want to
 648 * force this to amke an item appear to have changed even if it has not.
 649 */
 650 extern JSD_PUBLIC_API(uintN)
 651 JSD_IncrementSourceAlterCount(JSDContext* jsdc, JSDSourceText* jsdsrc);
 652
 653 /*
 654 * Destroy *all* the source text items
 655 * (new for server-side USE WITH CARE)
 656 */
 657 extern JSD_PUBLIC_API(void)
 658 JSD_DestroyAllSources( JSDContext* jsdc );
 659
 660 /* functions for adding source items */
 661
 662 /*
 663 * Add a new item for a given URL. If an iten already exists for the given URL
 664 * then the old item is removed.
 665 * 'url' may not be NULL.
 666 */
 667 extern JSD_PUBLIC_API(JSDSourceText*)
 668 JSD_NewSourceText(JSDContext* jsdc, const char* url);
 669
 670 /*
 671 * Append text (or change status -- e.g. set completed) for a source text
 672 * item. Text need not be zero terminated. Callers should consider the returned
 673 * JSDSourceText to be the 'current' item for future use. This may return NULL
 674 * if called after this item has been replaced by a call to JSD_NewSourceText.
 675 */
 676 extern JSD_PUBLIC_API(JSDSourceText*)
 677 JSD_AppendSourceText(JSDContext*     jsdc,
 678                      JSDSourceText*  jsdsrc,
 679                      const char*     text,       /* *not* zero terminated */
 680                      size_t          length,
 681                      JSDSourceStatus status);
 682
 683 /*
 684 * Unicode varient of JSD_AppendSourceText.
 685 *
 686 * NOTE: At this point text is stored in 8bit ASCII so this function just
 687 * extracts the bottom 8bits from each jschar. At some future point we may
 688 * switch to storing and exposing 16bit Unicode.
 689 */
 690 extern JSD_PUBLIC_API(JSDSourceText*)
 691 JSD_AppendUCSourceText(JSDContext*     jsdc,
 692                        JSDSourceText*  jsdsrc,
 693                        const jschar*   text,       /* *not* zero terminated */
 694                        size_t          length,
 695                        JSDSourceStatus status);
 696 /*
 697  * Convienence function for adding complete source of url in one call.
 698  * same as:
 699  *   JSDSourceText* jsdsrc;
 700  *   JSD_LOCK_SOURCE_TEXT(jsdc);
 701  *   jsdsrc = jsd_NewSourceText(jsdc, url);
 702  *   if(jsdsrc)
 703  *       jsdsrc = jsd_AppendSourceText(jsdc, jsdsrc,
 704  *                                     text, length, JSD_SOURCE_PARTIAL);
 705  *   if(jsdsrc)
 706  *       jsdsrc = jsd_AppendSourceText(jsdc, jsdsrc,
 707  *                                     NULL, 0, JSD_SOURCE_COMPLETED);
 708  *   JSD_UNLOCK_SOURCE_TEXT(jsdc);
 709  *   return jsdsrc ? JS_TRUE : JS_FALSE;
 710  */
 711 extern JSD_PUBLIC_API(JSBool)
 712 JSD_AddFullSourceText(JSDContext* jsdc,
 713                       const char* text,       /* *not* zero terminated */
 714                       size_t      length,
 715                       const char* url);
 716
 717 /***************************************************************************/
 718 /* Execution/Interrupt Hook functions */
 719
 720 /* possible 'type' params for JSD_ExecutionHookProc */
 721 #define JSD_HOOK_INTERRUPTED            0
 722 #define JSD_HOOK_BREAKPOINT             1
 723 #define JSD_HOOK_DEBUG_REQUESTED        2
 724 #define JSD_HOOK_DEBUGGER_KEYWORD       3
 725 #define JSD_HOOK_THROW                  4
 726
 727 /* legal return values for JSD_ExecutionHookProc */
 728 #define JSD_HOOK_RETURN_HOOK_ERROR      0
 729 #define JSD_HOOK_RETURN_CONTINUE        1
 730 #define JSD_HOOK_RETURN_ABORT           2
 731 #define JSD_HOOK_RETURN_RET_WITH_VAL    3
 732 #define JSD_HOOK_RETURN_THROW_WITH_VAL  4
 733 #define JSD_HOOK_RETURN_CONTINUE_THROW  5
 734
 735 /*
 736 * Implement a callback of this form in order to hook execution.
 737 */
 738 typedef uintN
 739 (* JSD_ExecutionHookProc)(JSDContext*     jsdc,
 740                           JSDThreadState* jsdthreadstate,
 741                           uintN           type,
 742                           void*           callerdata,
 743                           jsval*          rval);
 744
 745 /* possible 'type' params for JSD_CallHookProc */
 746 #define JSD_HOOK_TOPLEVEL_START  0   /* about to evaluate top level script */
 747 #define JSD_HOOK_TOPLEVEL_END    1   /* done evaluting top level script    */
 748 #define JSD_HOOK_FUNCTION_CALL   2   /* about to call a function           */
 749 #define JSD_HOOK_FUNCTION_RETURN 3   /* done calling function              */
 750
 751 /*
 752 * Implement a callback of this form in order to hook function call/returns.
 753 * Return JS_TRUE from a TOPLEVEL_START or FUNCTION_CALL type call hook if you
 754 * want to hear about the TOPLEVEL_END or FUNCTION_RETURN too.  Return value is
 755 * ignored to TOPLEVEL_END and FUNCTION_RETURN type hooks.
 756 */
 757 typedef JSBool
 758 (* JSD_CallHookProc)(JSDContext*     jsdc,
 759                      JSDThreadState* jsdthreadstate,
 760                      uintN           type,
 761                      void*           callerdata);
 762
 763 /*
 764 * Set Hook to be called whenever the given pc is about to be executed --
 765 * i.e. for 'trap' or 'breakpoint'
 766 */
 767 extern JSD_PUBLIC_API(JSBool)
 768 JSD_SetExecutionHook(JSDContext*           jsdc,
 769                      JSDScript*            jsdscript,
 770                      jsuword               pc,
 771                      JSD_ExecutionHookProc hook,
 772                      void*                 callerdata);
 773
 774 /*
 775 * Clear the hook for this pc
 776 */
 777 extern JSD_PUBLIC_API(JSBool)
 778 JSD_ClearExecutionHook(JSDContext*          jsdc,
 779                        JSDScript*           jsdscript,
 780                        jsuword              pc);
 781
 782 /*
 783 * Clear all the pc specific hooks for this script
 784 */
 785 extern JSD_PUBLIC_API(JSBool)
 786 JSD_ClearAllExecutionHooksForScript(JSDContext* jsdc, JSDScript* jsdscript);
 787
 788 /*
 789 * Clear all the pc specific hooks for the entire JSRuntime associated with
 790 * this JSDContext
 791 */
 792 extern JSD_PUBLIC_API(JSBool)
 793 JSD_ClearAllExecutionHooks(JSDContext* jsdc);
 794
 795 /*
 796 * Set a hook to be called before the next instruction is executed. Depending
 797 * on the threading situation and whether or not an JS code is currently
 798 * executing the hook might be called before this call returns, or at some
 799 * future time. The hook will continue to be called as each instruction
 800 * executes until cleared.
 801 */
 802 extern JSD_PUBLIC_API(JSBool)
 803 JSD_SetInterruptHook(JSDContext*           jsdc,
 804                      JSD_ExecutionHookProc hook,
 805                      void*                 callerdata);
 806
 807 /*
 808 * Call the interrupt hook at least once per source line
 809 */
 810 extern JSD_PUBLIC_API(JSBool)
 811 JSD_EnableSingleStepInterrupts(JSDContext* jsdc, JSDScript *jsdscript, JSBool enable);
 812
 813 /*
 814 * Clear the current interrupt hook.
 815 */
 816 extern JSD_PUBLIC_API(JSBool)
 817 JSD_ClearInterruptHook(JSDContext* jsdc);
 818
 819 /*
 820 * Set the hook that should be called whenever a JSD_ErrorReporter hook
 821 * returns JSD_ERROR_REPORTER_DEBUG.
 822 */
 823 extern JSD_PUBLIC_API(JSBool)
 824 JSD_SetDebugBreakHook(JSDContext*           jsdc,
 825                       JSD_ExecutionHookProc hook,
 826                       void*                 callerdata);
 827
 828 /*
 829 * Clear the debug break hook
 830 */
 831 extern JSD_PUBLIC_API(JSBool)
 832 JSD_ClearDebugBreakHook(JSDContext* jsdc);
 833
 834 /*
 835 * Set the hook that should be called when the 'debugger' keyword is
 836 * encountered by the JavaScript interpreter during execution.
 837 */
 838 extern JSD_PUBLIC_API(JSBool)
 839 JSD_SetDebuggerHook(JSDContext*           jsdc,
 840                     JSD_ExecutionHookProc hook,
 841                     void*                 callerdata);
 842
 843 /*
 844 * Clear the 'debugger' keyword hook
 845 */
 846 extern JSD_PUBLIC_API(JSBool)
 847 JSD_ClearDebuggerHook(JSDContext* jsdc);
 848
 849 /*
 850 * Set the hook that should be called when a JS exception is thrown.
 851 * NOTE: the 'do default' return value is: JSD_HOOK_RETURN_CONTINUE_THROW
 852 */
 853 extern JSD_PUBLIC_API(JSBool)
 854 JSD_SetThrowHook(JSDContext*           jsdc,
 855                  JSD_ExecutionHookProc hook,
 856                  void*                 callerdata);
 857 /*
 858 * Clear the throw hook
 859 */
 860 extern JSD_PUBLIC_API(JSBool)
 861 JSD_ClearThrowHook(JSDContext* jsdc);
 862
 863 /*
 864 * Set the hook that should be called when a toplevel script begins or completes.
 865 */
 866 extern JSD_PUBLIC_API(JSBool)
 867 JSD_SetTopLevelHook(JSDContext*      jsdc,
 868                     JSD_CallHookProc hook,
 869                     void*            callerdata);
 870 /*
 871 * Clear the toplevel call hook
 872 */
 873 extern JSD_PUBLIC_API(JSBool)
 874 JSD_ClearTopLevelHook(JSDContext* jsdc);
 875
 876 /*
 877 * Set the hook that should be called when a function call or return happens.
 878 */
 879 extern JSD_PUBLIC_API(JSBool)
 880 JSD_SetFunctionHook(JSDContext*      jsdc,
 881                     JSD_CallHookProc hook,
 882                     void*            callerdata);
 883 /*
 884 * Clear the function call hook
 885 */
 886 extern JSD_PUBLIC_API(JSBool)
 887 JSD_ClearFunctionHook(JSDContext* jsdc);
 888
 889 /***************************************************************************/
 890 /* Stack Frame functions */
 891
 892 /*
 893 * Get the count of call stack frames for the given JSDThreadState
 894 */
 895 extern JSD_PUBLIC_API(uintN)
 896 JSD_GetCountOfStackFrames(JSDContext* jsdc, JSDThreadState* jsdthreadstate);
 897
 898 /*
 899 * Get the 'current' call stack frame for the given JSDThreadState
 900 */
 901 extern JSD_PUBLIC_API(JSDStackFrameInfo*)
 902 JSD_GetStackFrame(JSDContext* jsdc, JSDThreadState* jsdthreadstate);
 903
 904 /*
 905 * Get the JSContext for the given JSDThreadState
 906 */
 907 extern JSD_PUBLIC_API(JSContext*)
 908 JSD_GetJSContext(JSDContext* jsdc, JSDThreadState* jsdthreadstate);
 909
 910 /*
 911 * Get the calling call stack frame for the given frame
 912 */
 913 extern JSD_PUBLIC_API(JSDStackFrameInfo*)
 914 JSD_GetCallingStackFrame(JSDContext* jsdc,
 915                          JSDThreadState* jsdthreadstate,
 916                          JSDStackFrameInfo* jsdframe);
 917
 918 /*
 919 * Get the script for the given call stack frame
 920 */
 921 extern JSD_PUBLIC_API(JSDScript*)
 922 JSD_GetScriptForStackFrame(JSDContext* jsdc,
 923                            JSDThreadState* jsdthreadstate,
 924                            JSDStackFrameInfo* jsdframe);
 925
 926 /*
 927 * Get the 'Program Counter' for the given call stack frame
 928 */
 929 extern JSD_PUBLIC_API(jsuword)
 930 JSD_GetPCForStackFrame(JSDContext* jsdc,
 931                        JSDThreadState* jsdthreadstate,
 932                        JSDStackFrameInfo* jsdframe);
 933
 934 /*
 935 * Get the JavaScript Call Object for the given call stack frame.
 936 * *** new for version 1.1 ****
 937 */
 938 extern JSD_PUBLIC_API(JSDValue*)
 939 JSD_GetCallObjectForStackFrame(JSDContext* jsdc,
 940                                JSDThreadState* jsdthreadstate,
 941                                JSDStackFrameInfo* jsdframe);
 942
 943 /*
 944 * Get the head of the scope chain for the given call stack frame.
 945 * the chain can be traversed using JSD_GetValueParent.
 946 * *** new for version 1.1 ****
 947 */
 948 extern JSD_PUBLIC_API(JSDValue*)
 949 JSD_GetScopeChainForStackFrame(JSDContext* jsdc,
 950                                JSDThreadState* jsdthreadstate,
 951                                JSDStackFrameInfo* jsdframe);
 952
 953 /*
 954 * Get the 'this' Object for the given call stack frame.
 955 * *** new for version 1.1 ****
 956 */
 957 extern JSD_PUBLIC_API(JSDValue*)
 958 JSD_GetThisForStackFrame(JSDContext* jsdc,
 959                          JSDThreadState* jsdthreadstate,
 960                          JSDStackFrameInfo* jsdframe);
 961
 962 /*
 963 * Get the name of the function executing in this stack frame.  Especially useful
 964 * for native frames (without script objects.)
 965 * *** new for gecko 2.0 ****
 966 */
 967 extern JSD_PUBLIC_API(JSString *)
 968 JSD_GetIdForStackFrame(JSDContext* jsdc,
 969                        JSDThreadState* jsdthreadstate,
 970                        JSDStackFrameInfo* jsdframe);
 971
 972 /*
 973 * True if stack frame represents a frame created as a result of a debugger
 974 * evaluation.
 975 */
 976 extern JSD_PUBLIC_API(JSBool)
 977 JSD_IsStackFrameDebugger(JSDContext* jsdc,
 978                          JSDThreadState* jsdthreadstate,
 979                          JSDStackFrameInfo* jsdframe);
 980
 981 /*
 982 * True if stack frame is constructing a new object.
 983 */
 984 extern JSD_PUBLIC_API(JSBool)
 985 JSD_IsStackFrameConstructing(JSDContext* jsdc,
 986                              JSDThreadState* jsdthreadstate,
 987                              JSDStackFrameInfo* jsdframe);
 988
 989 /*
 990 * Evaluate the given unicode source code in the context of the given stack frame.
 991 * returns JS_TRUE and puts result in rval on success, JS_FALSE on failure.
 992 * NOTE: The ErrorReporter hook might be called if this fails.
 993 */
 994 extern JSD_PUBLIC_API(JSBool)
 995 JSD_EvaluateUCScriptInStackFrame(JSDContext* jsdc,
 996                                  JSDThreadState* jsdthreadstate,
 997                                  JSDStackFrameInfo* jsdframe,
 998                                  const jschar *bytes, uintN length,
 999                                  const char *filename, uintN lineno,
1000                                  jsval *rval);
1001
1002 /*
1003 * Same as above, but does not eat exceptions.
1004 */
1005 extern JSD_PUBLIC_API(JSBool)
1006 JSD_AttemptUCScriptInStackFrame(JSDContext* jsdc,
1007                                 JSDThreadState* jsdthreadstate,
1008                                 JSDStackFrameInfo* jsdframe,
1009                                 const jschar *bytes, uintN length,
1010                                 const char *filename, uintN lineno,
1011                                 jsval *rval);
1012
1013 /* single byte character version of JSD_EvaluateUCScriptInStackFrame */
1014 extern JSD_PUBLIC_API(JSBool)
1015 JSD_EvaluateScriptInStackFrame(JSDContext* jsdc,
1016                                JSDThreadState* jsdthreadstate,
1017                                JSDStackFrameInfo* jsdframe,
1018                                const char *bytes, uintN length,
1019                                const char *filename, uintN lineno, jsval *rval);
1020
1021 /*
1022 * Same as above, but does not eat exceptions.
1023 */
1024 extern JSD_PUBLIC_API(JSBool)
1025 JSD_AttemptScriptInStackFrame(JSDContext* jsdc,
1026                               JSDThreadState* jsdthreadstate,
1027                               JSDStackFrameInfo* jsdframe,
1028                               const char *bytes, uintN length,
1029                               const char *filename, uintN lineno, jsval *rval);
1030
1031 /*
1032 * Convert the given jsval to a string
1033 * NOTE: The ErrorReporter hook might be called if this fails.
1034 */
1035 extern JSD_PUBLIC_API(JSString*)
1036 JSD_ValToStringInStackFrame(JSDContext* jsdc,
1037                             JSDThreadState* jsdthreadstate,
1038                             JSDStackFrameInfo* jsdframe,
1039                             jsval val);
1040
1041 /*
1042 * Get the JSDValue currently being thrown as an exception (may be NULL).
1043 * NOTE: must eventually release by calling JSD_DropValue (if not NULL)
1044 * *** new for version 1.1 ****
1045 */
1046 extern JSD_PUBLIC_API(JSDValue*)
1047 JSD_GetException(JSDContext* jsdc, JSDThreadState* jsdthreadstate);
1048
1049 /*
1050 * Set the JSDValue currently being thrown as an exception.
1051 * *** new for version 1.1 ****
1052 */
1053 extern JSD_PUBLIC_API(JSBool)
1054 JSD_SetException(JSDContext* jsdc, JSDThreadState* jsdthreadstate,
1055                  JSDValue* jsdval);
1056
1057 /***************************************************************************/
1058 /* Error Reporter functions */
1059
1060 /*
1061 * XXX The ErrorReporter Hook scheme is going to change soon to more
1062 *     Fully support exceptions.
1063 */
1064
1065 /* legal return values for JSD_ErrorReporter */
1066 #define JSD_ERROR_REPORTER_PASS_ALONG   0 /* pass along to regular reporter */
1067 #define JSD_ERROR_REPORTER_RETURN       1 /* don't pass to error reporter */
1068 #define JSD_ERROR_REPORTER_DEBUG        2 /* force call to DebugBreakHook */
1069 #define JSD_ERROR_REPORTER_CLEAR_RETURN 3 /* clear exception and don't pass */
1070
1071 /*
1072 * Implement a callback of this form in order to hook the ErrorReporter
1073 */
1074 typedef uintN
1075 (* JSD_ErrorReporter)(JSDContext*     jsdc,
1076                       JSContext*      cx,
1077                       const char*     message,
1078                       JSErrorReport*  report,
1079                       void*           callerdata);
1080
1081 /* Set ErrorReporter hook */
1082 extern JSD_PUBLIC_API(JSBool)
1083 JSD_SetErrorReporter(JSDContext*       jsdc,
1084                      JSD_ErrorReporter reporter,
1085                      void*             callerdata);
1086
1087 /* Get Current ErrorReporter hook */
1088 extern JSD_PUBLIC_API(JSBool)
1089 JSD_GetErrorReporter(JSDContext*        jsdc,
1090                      JSD_ErrorReporter* reporter,
1091                      void**             callerdata);
1092
1093 /***************************************************************************/
1094 /* Generic locks that callers can use for their own purposes */
1095
1096 /*
1097 * Is Locking and GetThread supported in this build?
1098 */
1099 extern JSD_PUBLIC_API(JSBool)
1100 JSD_IsLockingAndThreadIdSupported();
1101
1102 /*
1103 * Create a reentrant/nestable lock
1104 */
1105 extern JSD_PUBLIC_API(void*)
1106 JSD_CreateLock();
1107
1108 /*
1109 * Aquire lock for this thread (or block until available). Increments a
1110 * counter if this thread already owns the lock.
1111 */
1112 extern JSD_PUBLIC_API(void)
1113 JSD_Lock(void* lock);
1114
1115 /*
1116 * Release lock for this thread (or decrement the counter if JSD_Lock
1117 * was previous called more than once).
1118 */
1119 extern JSD_PUBLIC_API(void)
1120 JSD_Unlock(void* lock);
1121
1122 /*
1123 * For debugging only if not (JS_THREADSAFE AND DEBUG) then returns JS_TRUE
1124 *    So JSD_IsLocked(lock) may not equal !JSD_IsUnlocked(lock)
1125 */
1126 extern JSD_PUBLIC_API(JSBool)
1127 JSD_IsLocked(void* lock);
1128
1129 /*
1130 * See above...
1131 */
1132 extern JSD_PUBLIC_API(JSBool)
1133 JSD_IsUnlocked(void* lock);
1134
1135 /*
1136 * return an ID uniquely identifying this thread.
1137 */
1138 extern JSD_PUBLIC_API(void*)
1139 JSD_CurrentThread();
1140
1141 /***************************************************************************/
1142 /* Value and Property Functions  --- All NEW for 1.1 --- */
1143
1144 /*
1145 * NOTE: JSDValue and JSDProperty objects are reference counted. This allows
1146 * for rooting these objects AND any underlying garbage collected jsvals.
1147 * ALL JSDValue and JSDProperty objects returned by the functions below
1148 * MUST eventually be released using the appropriate JSD_Dropxxx function.
1149 */
1150
1151 /*
1152 * Create a new JSDValue to wrap the given jsval
1153 * NOTE: must eventually release by calling JSD_DropValue (if not NULL)
1154 * *** new for version 1.1 ****
1155 */
1156 extern JSD_PUBLIC_API(JSDValue*)
1157 JSD_NewValue(JSDContext* jsdc, jsval val);
1158
1159 /*
1160 * Release the JSDValue. After this call the object MUST not be referenced again!
1161 * *** new for version 1.1 ****
1162 */
1163 extern JSD_PUBLIC_API(void)
1164 JSD_DropValue(JSDContext* jsdc, JSDValue* jsdval);
1165
1166 /*
1167 * Get the jsval wrapped by this JSDValue
1168 * *** new for version 1.1 ****
1169 */
1170 extern JSD_PUBLIC_API(jsval)
1171 JSD_GetValueWrappedJSVal(JSDContext* jsdc, JSDValue* jsdval);
1172
1173 /*
1174 * Clear all property and association information about the given JSDValue.
1175 * Such information will be lazily regenerated when later accessed. This
1176 * function must be called to make changes to the properties of an object
1177 * visible to the accessor functions below (if the properties et.al. have
1178 * changed since a previous call to those accessors).
1179 * *** new for version 1.1 ****
1180 */
1181 extern JSD_PUBLIC_API(void)
1182 JSD_RefreshValue(JSDContext* jsdc, JSDValue* jsdval);
1183
1184 /**************************************************/
1185
1186 /*
1187 * Does the JSDValue wrap a JSObject?
1188 * *** new for version 1.1 ****
1189 */
1190 extern JSD_PUBLIC_API(JSBool)
1191 JSD_IsValueObject(JSDContext* jsdc, JSDValue* jsdval);
1192
1193 /*
1194 * Does the JSDValue wrap a number (int or double)?
1195 * *** new for version 1.1 ****
1196 */
1197 extern JSD_PUBLIC_API(JSBool)
1198 JSD_IsValueNumber(JSDContext* jsdc, JSDValue* jsdval);
1199
1200 /*
1201 * Does the JSDValue wrap an int?
1202 * *** new for version 1.1 ****
1203 */
1204 extern JSD_PUBLIC_API(JSBool)
1205 JSD_IsValueInt(JSDContext* jsdc, JSDValue* jsdval);
1206
1207 /*
1208 * Does the JSDValue wrap a double?
1209 * *** new for version 1.1 ****
1210 */
1211 extern JSD_PUBLIC_API(JSBool)
1212 JSD_IsValueDouble(JSDContext* jsdc, JSDValue* jsdval);
1213
1214 /*
1215 * Does the JSDValue wrap a JSString?
1216 * *** new for version 1.1 ****
1217 */
1218 extern JSD_PUBLIC_API(JSBool)
1219 JSD_IsValueString(JSDContext* jsdc, JSDValue* jsdval);
1220
1221 /*
1222 * Does the JSDValue wrap a JSBool?
1223 * *** new for version 1.1 ****
1224 */
1225 extern JSD_PUBLIC_API(JSBool)
1226 JSD_IsValueBoolean(JSDContext* jsdc, JSDValue* jsdval);
1227
1228 /*
1229 * Does the JSDValue wrap a JSVAL_NULL?
1230 * *** new for version 1.1 ****
1231 */
1232 extern JSD_PUBLIC_API(JSBool)
1233 JSD_IsValueNull(JSDContext* jsdc, JSDValue* jsdval);
1234
1235 /*
1236 * Does the JSDValue wrap a JSVAL_VOID?
1237 * *** new for version 1.1 ****
1238 */
1239 extern JSD_PUBLIC_API(JSBool)
1240 JSD_IsValueVoid(JSDContext* jsdc, JSDValue* jsdval);
1241
1242 /*
1243 * Does the JSDValue wrap a primative (not a JSObject)?
1244 * *** new for version 1.1 ****
1245 */
1246 extern JSD_PUBLIC_API(JSBool)
1247 JSD_IsValuePrimitive(JSDContext* jsdc, JSDValue* jsdval);
1248
1249 /*
1250 * Does the JSDValue wrap a function?
1251 * *** new for version 1.1 ****
1252 */
1253 extern JSD_PUBLIC_API(JSBool)
1254 JSD_IsValueFunction(JSDContext* jsdc, JSDValue* jsdval);
1255
1256 /*
1257 * Does the JSDValue wrap a native function?
1258 * *** new for version 1.1 ****
1259 */
1260 extern JSD_PUBLIC_API(JSBool)
1261 JSD_IsValueNative(JSDContext* jsdc, JSDValue* jsdval);
1262
1263 /**************************************************/
1264
1265 /*
1266 * Return JSBool value (does NOT do conversion).
1267 * *** new for version 1.1 ****
1268 */
1269 extern JSD_PUBLIC_API(JSBool)
1270 JSD_GetValueBoolean(JSDContext* jsdc, JSDValue* jsdval);
1271
1272 /*
1273 * Return int32 value (does NOT do conversion).
1274 * *** new for version 1.1 ****
1275 */
1276 extern JSD_PUBLIC_API(int32)
1277 JSD_GetValueInt(JSDContext* jsdc, JSDValue* jsdval);
1278
1279 /*
1280 * Return double value (does NOT do conversion).
1281 * *** new for version 1.1 ****
1282 */
1283 extern JSD_PUBLIC_API(jsdouble)
1284 JSD_GetValueDouble(JSDContext* jsdc, JSDValue* jsdval);
1285
1286 /*
1287 * Return JSString value (DOES do conversion if necessary).
1288 * NOTE that the JSString returned is not protected from garbage
1289 * collection. It should be immediately read or wrapped using
1290 * JSD_NewValue(jsdc,STRING_TO_JSVAL(str)) if necessary.
1291 * *** new for version 1.1 ****
1292 */
1293 extern JSD_PUBLIC_API(JSString*)
1294 JSD_GetValueString(JSDContext* jsdc, JSDValue* jsdval);
1295
1296 /*
1297 * Return name of function IFF JSDValue represents a function.
1298 * *** new for gecko 2.0 ****
1299 */
1300 extern JSD_PUBLIC_API(JSString *)
1301 JSD_GetValueFunctionId(JSDContext* jsdc, JSDValue* jsdval);
1302
1303 /*
1304 * Return function object IFF JSDValue represents a function or an object
1305 * wrapping a function.
1306 * *** new for version 1.1 ****
1307 */
1308 extern JSD_PUBLIC_API(JSFunction*)
1309 JSD_GetValueFunction(JSDContext* jsdc, JSDValue* jsdval);
1310
1311 /**************************************************/
1312
1313 /*
1314 * Return the number of properties for the JSDValue.
1315 * *** new for version 1.1 ****
1316 */
1317 extern JSD_PUBLIC_API(uintN)
1318 JSD_GetCountOfProperties(JSDContext* jsdc, JSDValue* jsdval);
1319
1320 /*
1321 * Iterate through the properties of the JSDValue.
1322 * Use form similar to that shown for JSD_IterateScripts (no locking required).
1323 * NOTE: each JSDProperty returned must eventually be released by calling
1324 * JSD_DropProperty.
1325 * *** new for version 1.1 ****
1326 */
1327 extern JSD_PUBLIC_API(JSDProperty*)
1328 JSD_IterateProperties(JSDContext* jsdc, JSDValue* jsdval, JSDProperty **iterp);
1329
1330 /*
1331 * Get the JSDProperty for the property of this JSDVal with this name.
1332 * NOTE: must eventually release by calling JSD_DropProperty (if not NULL)
1333 * *** new for version 1.1 ****
1334 */
1335 extern JSD_PUBLIC_API(JSDProperty*)
1336 JSD_GetValueProperty(JSDContext* jsdc, JSDValue* jsdval, JSString* name);
1337
1338 /*
1339 * Get the prototype object for this JSDValue.
1340 * NOTE: must eventually release by calling JSD_DropValue (if not NULL)
1341 * *** new for version 1.1 ****
1342 */
1343 extern JSD_PUBLIC_API(JSDValue*)
1344 JSD_GetValuePrototype(JSDContext* jsdc, JSDValue* jsdval);
1345
1346 /*
1347 * Get the parent object for this JSDValue.
1348 * NOTE: must eventually release by calling JSD_DropValue (if not NULL)
1349 * *** new for version 1.1 ****
1350 */
1351 extern JSD_PUBLIC_API(JSDValue*)
1352 JSD_GetValueParent(JSDContext* jsdc, JSDValue* jsdval);
1353
1354 /*
1355 * Get the ctor object for this JSDValue (or likely its prototype's ctor).
1356 * NOTE: must eventually release by calling JSD_DropValue (if not NULL)
1357 * *** new for version 1.1 ****
1358 */
1359 extern JSD_PUBLIC_API(JSDValue*)
1360 JSD_GetValueConstructor(JSDContext* jsdc, JSDValue* jsdval);
1361
1362 /*
1363 * Get the name of the class for this object.
1364 * *** new for version 1.1 ****
1365 */
1366 extern JSD_PUBLIC_API(const char*)
1367 JSD_GetValueClassName(JSDContext* jsdc, JSDValue* jsdval);
1368
1369 /*
1370 * Get the script for the given value if the given value represents a
1371 * scripted function.  Otherwise, return null.
1372 */
1373 extern JSD_PUBLIC_API(JSDScript*)
1374 JSD_GetScriptForValue(JSDContext* jsdc, JSDValue* jsdval);
1375
1376 /**************************************************/
1377
1378 /* possible or'd together bitflags returned by JSD_GetPropertyFlags
1379  *
1380  * XXX these must stay the same as the JSPD_ flags in jsdbgapi.h
1381  */
1382 #define JSDPD_ENUMERATE  JSPD_ENUMERATE    /* visible to for/in loop */
1383 #define JSDPD_READONLY   JSPD_READONLY     /* assignment is error */
1384 #define JSDPD_PERMANENT  JSPD_PERMANENT    /* property cannot be deleted */
1385 #define JSDPD_ALIAS      JSPD_ALIAS        /* property has an alias id */
1386 #define JSDPD_ARGUMENT   JSPD_ARGUMENT     /* argument to function */
1387 #define JSDPD_VARIABLE   JSPD_VARIABLE     /* local variable in function */
1388 #define JSDPD_EXCEPTION  JSPD_EXCEPTION    /* exception occurred looking up */
1389                                            /* proprety, value is exception  */
1390 #define JSDPD_ERROR      JSPD_ERROR        /* native getter returned JS_FALSE */
1391                                            /* without throwing an exception */
1392 /* this is not one of the JSPD_ flags in jsdbgapi.h  - careful not to overlap*/
1393 #define JSDPD_HINTED     0x800             /* found via explicit lookup */
1394
1395 /*
1396 * Release this JSDProperty
1397 * *** new for version 1.1 ****
1398 */
1399 extern JSD_PUBLIC_API(void)
1400 JSD_DropProperty(JSDContext* jsdc, JSDProperty* jsdprop);
1401
1402 /*
1403 * Get the JSDValue represeting the name of this property (int or string)
1404 * NOTE: must eventually release by calling JSD_DropValue
1405 * *** new for version 1.1 ****
1406 */
1407 extern JSD_PUBLIC_API(JSDValue*)
1408 JSD_GetPropertyName(JSDContext* jsdc, JSDProperty* jsdprop);
1409
1410 /*
1411 * Get the JSDValue represeting the current value of this property
1412 * NOTE: must eventually release by calling JSD_DropValue (if not NULL)
1413 * *** new for version 1.1 ****
1414 */
1415 extern JSD_PUBLIC_API(JSDValue*)
1416 JSD_GetPropertyValue(JSDContext* jsdc, JSDProperty* jsdprop);
1417
1418 /*
1419 * Get the JSDValue represeting the alias of this property (if JSDPD_ALIAS set)
1420 * NOTE: must eventually release by calling JSD_DropValue (if not NULL)
1421 * *** new for version 1.1 ****
1422 */
1423 extern JSD_PUBLIC_API(JSDValue*)
1424 JSD_GetPropertyAlias(JSDContext* jsdc, JSDProperty* jsdprop);
1425
1426 /*
1427 * Get the flags for this property
1428 * *** new for version 1.1 ****
1429 */
1430 extern JSD_PUBLIC_API(uintN)
1431 JSD_GetPropertyFlags(JSDContext* jsdc, JSDProperty* jsdprop);
1432
1433 /*
1434 * Get Variable or Argument slot number (if JSDPD_ARGUMENT or JSDPD_VARIABLE set)
1435 * *** new for version 1.1 ****
1436 */
1437 extern JSD_PUBLIC_API(uintN)
1438 JSD_GetPropertyVarArgSlot(JSDContext* jsdc, JSDProperty* jsdprop);
1439
1440 /***************************************************************************/
1441 /* Object Functions  --- All NEW for 1.1 --- */
1442
1443 /*
1444 * JSDObjects exist to allow a means of iterating through all JSObjects in the
1445 * engine. They are created and destroyed as the wrapped JSObjects are created
1446 * and destroyed in the engine. JSDObjects additionally track the location in
1447 * the JavaScript source where their wrapped JSObjects were created and the name
1448 * and location of the (non-native) constructor used.
1449 *
1450 * NOTE: JSDObjects are NOT reference counted. The have only weak links to
1451 * jsObjects - thus they do not inhibit garbage collection of JSObjects. If
1452 * you need a JSDObject to safely persist then wrap it in a JSDValue (using
1453 * jsd_GetValueForObject).
1454 */
1455
1456 /*
1457 * Lock the entire Object subsystem -- see JSD_UnlockObjectSubsystem
1458 * *** new for version 1.1 ****
1459 */
1460 extern JSD_PUBLIC_API(void)
1461 JSD_LockObjectSubsystem(JSDContext* jsdc);
1462
1463 /*
1464 * Unlock the entire Object subsystem -- see JSD_LockObjectSubsystem
1465 * *** new for version 1.1 ****
1466 */
1467 extern JSD_PUBLIC_API(void)
1468 JSD_UnlockObjectSubsystem(JSDContext* jsdc);
1469
1470 /*
1471 * Iterate through the known objects
1472 * Use form similar to that shown for JSD_IterateScripts.
1473 * NOTE: the ObjectSubsystem must be locked before and unlocked after iterating.
1474 * *** new for version 1.1 ****
1475 */
1476 extern JSD_PUBLIC_API(JSDObject*)
1477 JSD_IterateObjects(JSDContext* jsdc, JSDObject** iterp);
1478
1479 /*
1480 * Get the JSObject represented by this JSDObject
1481 * *** new for version 1.1 ****
1482 */
1483 extern JSD_PUBLIC_API(JSObject*)
1484 JSD_GetWrappedObject(JSDContext* jsdc, JSDObject* jsdobj);
1485
1486 /*
1487 * Get the URL of the line of source that caused this object to be created.
1488 * May be NULL.
1489 * *** new for version 1.1 ****
1490 */
1491 extern JSD_PUBLIC_API(const char*)
1492 JSD_GetObjectNewURL(JSDContext* jsdc, JSDObject* jsdobj);
1493
1494 /*
1495 * Get the line number of the line of source that caused this object to be
1496 * created. May be 0 indicating that the line number is unknown.
1497 * *** new for version 1.1 ****
1498 */
1499 extern JSD_PUBLIC_API(uintN)
1500 JSD_GetObjectNewLineNumber(JSDContext* jsdc, JSDObject* jsdobj);
1501
1502 /*
1503 * Get the URL of the line of source of the constructor for this object.
1504 * May be NULL.
1505 * *** new for version 1.1 ****
1506 */
1507 extern JSD_PUBLIC_API(const char*)
1508 JSD_GetObjectConstructorURL(JSDContext* jsdc, JSDObject* jsdobj);
1509
1510 /*
1511 * Get the line number of the line of source of the constructor for this object.
1512 * created. May be 0 indicating that the line number is unknown.
1513 * *** new for version 1.1 ****
1514 */
1515 extern JSD_PUBLIC_API(uintN)
1516 JSD_GetObjectConstructorLineNumber(JSDContext* jsdc, JSDObject* jsdobj);
1517
1518 /*
1519 * Get the name of the constructor for this object.
1520 * May be NULL.
1521 * *** new for version 1.1 ****
1522 */
1523 extern JSD_PUBLIC_API(const char*)
1524 JSD_GetObjectConstructorName(JSDContext* jsdc, JSDObject* jsdobj);
1525
1526 /*
1527 * Get JSDObject representing this JSObject.
1528 * May return NULL.
1529 * *** new for version 1.1 ****
1530 */
1531 extern JSD_PUBLIC_API(JSDObject*)
1532 JSD_GetJSDObjectForJSObject(JSDContext* jsdc, JSObject* jsobj);
1533
1534 /*
1535 * Get JSDObject representing this JSDValue.
1536 * May return NULL.
1537 * *** new for version 1.1 ****
1538 */
1539 extern JSD_PUBLIC_API(JSDObject*)
1540 JSD_GetObjectForValue(JSDContext* jsdc, JSDValue* jsdval);
1541
1542 /*
1543 * Create a JSDValue to wrap (and root) this JSDObject.
1544 * NOTE: must eventually release by calling JSD_DropValue (if not NULL)
1545 * *** new for version 1.1 ****
1546 */
1547 extern JSD_PUBLIC_API(JSDValue*)
1548 JSD_GetValueForObject(JSDContext* jsdc, JSDObject* jsdobj);
1549
1550 /***************************************************************************/
1551 /* Livewire specific API */
1552 #ifdef LIVEWIRE
1553
1554 extern JSD_PUBLIC_API(LWDBGScript*)
1555 JSDLW_GetLWScript(JSDContext* jsdc, JSDScript* jsdscript);
1556
1557 extern JSD_PUBLIC_API(JSDSourceText*)
1558 JSDLW_PreLoadSource(JSDContext* jsdc, LWDBGApp* app,
1559                     const char* filename, JSBool clear);
1560
1561 extern JSD_PUBLIC_API(JSDSourceText*)
1562 JSDLW_ForceLoadSource(JSDContext* jsdc, JSDSourceText* jsdsrc);
1563
1564 extern JSD_PUBLIC_API(JSBool)
1565 JSDLW_RawToProcessedLineNumber(JSDContext* jsdc, JSDScript* jsdscript,
1566                                uintN lineIn, uintN* lineOut);
1567
1568 extern JSD_PUBLIC_API(JSBool)
1569 JSDLW_ProcessedToRawLineNumber(JSDContext* jsdc, JSDScript* jsdscript,
1570                                uintN lineIn, uintN* lineOut);
1571
1572 #endif
1573 /***************************************************************************/
1574
1575 JS_END_EXTERN_C
1576
1577 #endif /* jsdebug_h___ */