Back to index

lightning-sunbird  0.9+nobinonly
jsdebug.h
Go to the documentation of this file.
00001 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is mozilla.org code.
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1998
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either the GNU General Public License Version 2 or later (the "GPL"), or
00026  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 /*
00039  * Header for JavaScript Debugging support - All public functions
00040  */
00041 
00042 #ifndef jsdebug_h___
00043 #define jsdebug_h___
00044 
00045 /* Get jstypes.h included first. After that we can use PR macros for doing
00046 *  this extern "C" stuff!
00047 */
00048 #ifdef __cplusplus
00049 extern "C"
00050 {
00051 #endif
00052 #include "jstypes.h"
00053 #ifdef __cplusplus
00054 }
00055 #endif
00056 
00057 JS_BEGIN_EXTERN_C
00058 #include "jsapi.h"
00059 #include "jsdbgapi.h"
00060 #ifdef LIVEWIRE
00061 #include "lwdbgapi.h"
00062 #endif
00063 JS_END_EXTERN_C
00064 
00065 JS_BEGIN_EXTERN_C
00066 
00067 /*
00068  * The linkage of JSD API functions differs depending on whether the file is
00069  * used within the JSD library or not.  Any source file within the JSD
00070  * libraray should define EXPORT_JSD_API whereas any client of the library
00071  * should not.
00072  */
00073 #ifdef EXPORT_JSD_API
00074 #define JSD_PUBLIC_API(t)    JS_EXPORT_API(t)
00075 #define JSD_PUBLIC_DATA(t)   JS_EXPORT_DATA(t)
00076 #else
00077 #define JSD_PUBLIC_API(t)    JS_IMPORT_API(t)
00078 #define JSD_PUBLIC_DATA(t)   JS_IMPORT_DATA(t)
00079 #endif
00080 
00081 #define JSD_FRIEND_API(t)    JSD_PUBLIC_API(t)
00082 #define JSD_FRIEND_DATA(t)   JSD_PUBLIC_DATA(t)
00083 
00084 /***************************************************************************/
00085 /* Opaque typedefs for handles */
00086 
00087 typedef struct JSDContext        JSDContext;
00088 typedef struct JSDScript         JSDScript;
00089 typedef struct JSDSourceText     JSDSourceText;
00090 typedef struct JSDThreadState    JSDThreadState;
00091 typedef struct JSDStackFrameInfo JSDStackFrameInfo;
00092 typedef struct JSDValue          JSDValue;
00093 typedef struct JSDProperty       JSDProperty;
00094 typedef struct JSDObject         JSDObject;
00095 
00096 /***************************************************************************/
00097 /* High Level calls */
00098 
00099 /*
00100 * callback stuff for calls in EXE to be accessed by this code
00101 * when it lives in an explicitly loaded DLL
00102 */
00103 
00104 /*
00105 * This callback allows JSD to inform the embedding when JSD has been
00106 * turned on or off. This is especially useful in the Java-based debugging
00107 * system used in mozilla because the debugger applet controls starting
00108 * up the JSD system.
00109 */
00110 typedef void
00111 (* JS_DLL_CALLBACK JSD_SetContextProc)(JSDContext* jsdc, void* user);
00112 
00113 /* This struct could have more fields in future versions */
00114 typedef struct
00115 {
00116     uintN              size;       /* size of this struct (init before use)*/
00117     JSD_SetContextProc setContext;
00118 } JSD_UserCallbacks;
00119 
00120 /*
00121 * Used by an embedding to tell JSD what JSRuntime to use and to set
00122 * callbacks without starting up JSD. This assumes only one JSRuntime
00123 * will be used. This exists to support the mozilla Java-based debugger
00124 * system.
00125 */
00126 extern JSD_PUBLIC_API(void)
00127 JSD_SetUserCallbacks(JSRuntime*         jsrt,
00128                      JSD_UserCallbacks* callbacks,
00129                      void*              user);
00130 
00131 /*
00132 * Startup JSD.
00133 * This version of the init function requires that JSD_SetUserCallbacks()
00134 * has been previously called (with a non-NULL callback struct pointer)
00135 */
00136 extern JSD_PUBLIC_API(JSDContext*)
00137 JSD_DebuggerOn(void);
00138 
00139 /*
00140 * Startup JSD on a particular JSRuntime with (optional) callbacks
00141 */
00142 extern JSD_PUBLIC_API(JSDContext*)
00143 JSD_DebuggerOnForUser(JSRuntime*         jsrt,
00144                       JSD_UserCallbacks* callbacks,
00145                       void*              user);
00146 
00147 /*
00148 * Shutdown JSD for this JSDContext
00149 */
00150 extern JSD_PUBLIC_API(void)
00151 JSD_DebuggerOff(JSDContext* jsdc);
00152 
00153 /*
00154 * Get the Major Version (initial JSD release used major version = 1)
00155 */
00156 extern JSD_PUBLIC_API(uintN)
00157 JSD_GetMajorVersion(void);
00158 
00159 /*
00160 * Get the Minor Version (initial JSD release used minor version = 0)
00161 */
00162 extern JSD_PUBLIC_API(uintN)
00163 JSD_GetMinorVersion(void);
00164 
00165 /*
00166 * Returns a 'dumb' JSContext that can be used for utility purposes as needed
00167 */
00168 extern JSD_PUBLIC_API(JSContext*)
00169 JSD_GetDefaultJSContext(JSDContext* jsdc);
00170 
00171 /*
00172 * Set the private data for this context, returns previous value
00173 */
00174 extern JSD_PUBLIC_API(void *)
00175 JSD_SetContextPrivate(JSDContext *jsdc, void *data);
00176 
00177 /*
00178 * Get the private data for this context
00179 */
00180 extern JSD_PUBLIC_API(void *)
00181 JSD_GetContextPrivate(JSDContext *jsdc);
00182 
00183 /*
00184 * Clear profile data for all scripts
00185 */
00186 extern JSD_PUBLIC_API(void)
00187 JSD_ClearAllProfileData(JSDContext* jsdc);
00188 
00189 /*
00190 * Context flags.
00191 */
00192 
00193 /* Include native frames in JSDThreadStates. */
00194 #define JSD_INCLUDE_NATIVE_FRAMES 0x01
00195 /*
00196 * Normally, if a script has a 0 in JSD_SCRIPT_PROFILE_BIT it is included in
00197 * profile data, otherwise it is not profiled.  Setting the JSD_PROFILE_WHEN_SET
00198 * flag reverses this convention.
00199 */
00200 #define JSD_PROFILE_WHEN_SET      0x02
00201 /*
00202 * Normally, when the script in the top frame of a thread state has a 1 in
00203 * JSD_SCRIPT_DEBUG_BIT, the execution hook is ignored.  Setting the
00204 * JSD_DEBUG_WHEN_SET flag reverses this convention.
00205 */
00206 #define JSD_DEBUG_WHEN_SET        0x04
00207 /*
00208 * When this flag is set the internal call hook will collect profile data.
00209 */
00210 #define JSD_COLLECT_PROFILE_DATA  0x08
00211 /*
00212 * When this flag is set, stack frames that are disabled for debugging
00213 * will not appear in the call stack chain.
00214 */
00215 #define JSD_HIDE_DISABLED_FRAMES  0x10
00216 /*
00217 * When this flag is set, the debugger will only check the
00218 * JSD_SCRIPT_DEBUG_BIT on the top (most recent) stack frame.  This
00219 * makes it possible to stop in an enabled frame which was called from
00220 * a stack that contains a disabled frame.
00221 *
00222 * When this flag is *not* set, any stack that contains a disabled frame
00223 * will not be debugged (the execution hook will not be invoked.)
00224 *
00225 * This only applies when the reason for calling the hook would have
00226 * been JSD_HOOK_INTERRUPTED or JSD_HOOK_THROW.  JSD_HOOK_BREAKPOINT,
00227 * JSD_HOOK_DEBUG_REQUESTED, and JSD_HOOK_DEBUGGER_KEYWORD always stop,
00228 * regardless of this setting, as long as the top frame is not disabled.
00229 *
00230 * If JSD_HIDE_DISABLED_FRAMES is set, this is effectively set as well.
00231 */
00232 #define JSD_MASK_TOP_FRAME_ONLY   0x20
00233 /*
00234 * When this flag is set, object creation will not be tracked.  This will
00235 * reduce the performance price you pay by enabling the debugger.
00236 */
00237 #define JSD_DISABLE_OBJECT_TRACE  0x40
00238 
00239 extern JSD_PUBLIC_API(void)
00240 JSD_SetContextFlags (JSDContext* jsdc, uint32 flags);
00241 
00242 extern JSD_PUBLIC_API(uint32)
00243 JSD_GetContextFlags (JSDContext* jsdc);     
00244 
00245 /*
00246 * Notify JSD that this JSContext is 'in use'. This allows JSD to hook the
00247 * ErrorReporter. For the most part this is done automatically whenever
00248 * events like script loading happen. But, it is a good idea to call this
00249 * from the embedding when new contexts come into use.
00250 */
00251 extern JSD_PUBLIC_API(void)
00252 JSD_JSContextInUse(JSDContext* jsdc, JSContext* context);
00253 
00254 /*
00255 * Find the JSDContext (if any) associated with the JSRuntime of a
00256 * given JSContext.
00257 */
00258 extern JSD_PUBLIC_API(JSDContext*)
00259 JSD_JSDContextForJSContext(JSContext* context);
00260 
00261 /***************************************************************************/
00262 /* Script functions */
00263 
00264 /*
00265 * Lock the entire script subsystem. This grabs a highlevel lock that
00266 * protects the JSD internal information about scripts. It is important
00267 * to wrap script related calls in this lock in multithreaded situations
00268 * -- i.e. where the debugger is running on a different thread than the
00269 * interpreter -- or when multiple debugger threads may be accessing this
00270 * subsystem. It is safe (and best) to use this locking even if the
00271 * environment might not be multi-threaded. Safely nestable.
00272 */
00273 extern JSD_PUBLIC_API(void)
00274 JSD_LockScriptSubsystem(JSDContext* jsdc);
00275 
00276 /*
00277 * Unlock the entire script subsystem -- see JSD_LockScriptSubsystem
00278 */
00279 extern JSD_PUBLIC_API(void)
00280 JSD_UnlockScriptSubsystem(JSDContext* jsdc);
00281 
00282 /*
00283 * Iterate through all the active scripts for this JSDContext.
00284 * NOTE: must initialize iterp to NULL to start iteration.
00285 * NOTE: must lock and unlock the subsystem
00286 * example:
00287 *
00288 *  JSDScript jsdscript;
00289 *  JSDScript iter = NULL;
00290 *
00291 *  JSD_LockScriptSubsystem(jsdc);
00292 *  while((jsdscript = JSD_IterateScripts(jsdc, &iter)) != NULL) {
00293 *     *** use jsdscript here ***
00294 *  }
00295 *  JSD_UnlockScriptSubsystem(jsdc);
00296 */
00297 extern JSD_PUBLIC_API(JSDScript*)
00298 JSD_IterateScripts(JSDContext* jsdc, JSDScript **iterp);
00299 
00300 /*
00301 * Get the number of times this script has been called.
00302 */
00303 extern JSD_PUBLIC_API(uintN)
00304 JSD_GetScriptCallCount(JSDContext* jsdc, JSDScript *script);
00305 
00306 /*
00307 * Get the max number of times this script called itself, directly or indirectly.
00308 */
00309 extern JSD_PUBLIC_API(uintN)
00310 JSD_GetScriptMaxRecurseDepth(JSDContext* jsdc, JSDScript *script);
00311 
00312 /*
00313 * Get the shortest execution time recorded.
00314 */
00315 extern JSD_PUBLIC_API(jsdouble)
00316 JSD_GetScriptMinExecutionTime(JSDContext* jsdc, JSDScript *script);
00317 
00318 /*
00319 * Get the longest execution time recorded.
00320 */
00321 extern JSD_PUBLIC_API(jsdouble)
00322 JSD_GetScriptMaxExecutionTime(JSDContext* jsdc, JSDScript *script);
00323 
00324 /*
00325 * Get the total amount of time spent in this script.
00326 */
00327 extern JSD_PUBLIC_API(jsdouble)
00328 JSD_GetScriptTotalExecutionTime(JSDContext* jsdc, JSDScript *script);
00329 
00330 /*
00331 * Get the shortest execution time recorded, excluding time spent in called
00332 * functions.
00333 */
00334 extern JSD_PUBLIC_API(jsdouble)
00335 JSD_GetScriptMinOwnExecutionTime(JSDContext* jsdc, JSDScript *script);
00336 
00337 /*
00338 * Get the longest execution time recorded, excluding time spent in called
00339 * functions.
00340 */
00341 extern JSD_PUBLIC_API(jsdouble)
00342 JSD_GetScriptMaxOwnExecutionTime(JSDContext* jsdc, JSDScript *script);
00343 
00344 /*
00345 * Get the total amount of time spent in this script, excluding time spent
00346 * in called functions.
00347 */
00348 extern JSD_PUBLIC_API(jsdouble)
00349 JSD_GetScriptTotalOwnExecutionTime(JSDContext* jsdc, JSDScript *script);
00350 
00351 /*
00352 * Clear profile data for this script.
00353 */
00354 extern JSD_PUBLIC_API(void)
00355 JSD_ClearScriptProfileData(JSDContext* jsdc, JSDScript *script);
00356 
00357 /*
00358 * Get the JSScript for a JSDScript
00359 */
00360 extern JSD_PUBLIC_API(JSScript*)
00361 JSD_GetJSScript(JSDContext* jsdc, JSDScript *script);
00362 
00363 /*
00364 * Get the JSFunction for a JSDScript
00365 */
00366 extern JSD_PUBLIC_API(JSFunction*)
00367 JSD_GetJSFunction(JSDContext* jsdc, JSDScript *script);
00368 
00369 /*
00370 * Determines whether or not to collect profile information for this
00371 * script.  The context flag JSD_PROFILE_WHEN_SET decides the logic.
00372 */
00373 #define JSD_SCRIPT_PROFILE_BIT 0x01
00374 /*
00375 * Determines whether or not to ignore breakpoints, etc. in this script.
00376 * The context flag JSD_DEBUG_WHEN_SET decides the logic.
00377 */
00378 #define JSD_SCRIPT_DEBUG_BIT   0x02
00379 
00380 extern JSD_PUBLIC_API(uint32)
00381 JSD_GetScriptFlags(JSDContext *jsdc, JSDScript* jsdscript);
00382 
00383 extern JSD_PUBLIC_API(void)
00384 JSD_SetScriptFlags(JSDContext *jsdc, JSDScript* jsdscript, uint32 flags);
00385 
00386 /*
00387 * Set the private data for this script, returns previous value
00388 */
00389 extern JSD_PUBLIC_API(void *)
00390 JSD_SetScriptPrivate(JSDScript* jsdscript, void *data);
00391 
00392 /*
00393 * Get the private data for this script
00394 */
00395 extern JSD_PUBLIC_API(void *)
00396 JSD_GetScriptPrivate(JSDScript* jsdscript);
00397 
00398 /*
00399 * Determine if this script is still loaded in the interpreter
00400 */
00401 extern JSD_PUBLIC_API(JSBool)
00402 JSD_IsActiveScript(JSDContext* jsdc, JSDScript *jsdscript);
00403 
00404 /*
00405 * Get the filename associated with this script
00406 */
00407 extern JSD_PUBLIC_API(const char*)
00408 JSD_GetScriptFilename(JSDContext* jsdc, JSDScript *jsdscript);
00409 
00410 /*
00411 * Get the function name associated with this script (NULL if not a function)
00412 */
00413 extern JSD_PUBLIC_API(const char*)
00414 JSD_GetScriptFunctionName(JSDContext* jsdc, JSDScript *jsdscript);
00415 
00416 /*
00417 * Get the base linenumber of the sourcefile from which this script was loaded.
00418 * This is one-based -- i.e. the first line of a file is line '1'. This may
00419 * return 0 if this infomation is unknown.
00420 */
00421 extern JSD_PUBLIC_API(uintN)
00422 JSD_GetScriptBaseLineNumber(JSDContext* jsdc, JSDScript *jsdscript);
00423 
00424 /*
00425 * Get the count of source lines associated with this script (1 or greater)
00426 */
00427 extern JSD_PUBLIC_API(uintN)
00428 JSD_GetScriptLineExtent(JSDContext* jsdc, JSDScript *jsdscript);
00429 
00430 /*
00431 * Declaration of callback for notification of script creation and destruction.
00432 * 'creating' is JS_TRUE if creating new script, JS_FALSE if destroying existing
00433 * script (callback called just before actual destruction).
00434 * 'callerdata' is what was passed to JSD_SetScriptHook to set the hook.
00435 */
00436 typedef void
00437 (* JS_DLL_CALLBACK JSD_ScriptHookProc)(JSDContext* jsdc,
00438                                        JSDScript*  jsdscript,
00439                                        JSBool      creating,
00440                                        void*       callerdata);
00441 
00442 /*
00443 * Set a hook to be called when scripts are created or destroyed (loaded or
00444 * unloaded).
00445 * 'callerdata' can be whatever you want it to be.
00446 */
00447 extern JSD_PUBLIC_API(JSBool)
00448 JSD_SetScriptHook(JSDContext* jsdc, JSD_ScriptHookProc hook, void* callerdata);
00449 
00450 /*
00451 * Get the current script hook.
00452 */
00453 extern JSD_PUBLIC_API(JSBool)
00454 JSD_GetScriptHook(JSDContext* jsdc, JSD_ScriptHookProc* hook, void** callerdata);
00455 
00456 /*
00457 * Get a 'Program Counter' value for a given line. This represents the location
00458 * of the first bit of executable code for this line of source. This 'pc' should 
00459 * be considered an opaque handle.
00460 * 0 is returned for invalid scripts, or lines that lie outside the script.
00461 * If no code is on the given line, then the returned pc represents the first
00462 * code within the script (if any) after the given line.
00463 * This function can be used to set breakpoints -- see JSD_SetExecutionHook
00464 */
00465 extern JSD_PUBLIC_API(jsuword)
00466 JSD_GetClosestPC(JSDContext* jsdc, JSDScript* jsdscript, uintN line);
00467 
00468 /*
00469 * Get the source line number for a given 'Program Counter' location.
00470 * Returns 0 if no source line information is appropriate (or available) for
00471 * the given pc.
00472 */
00473 extern JSD_PUBLIC_API(uintN)
00474 JSD_GetClosestLine(JSDContext* jsdc, JSDScript* jsdscript, jsuword pc);
00475 
00476 /* these are only used in cases where scripts are created outside of JS*/
00477 
00478 /*
00479 * Direct call to notify JSD that a script has been created.
00480 * Embeddings that use the normal jsapi script functions need not call this.
00481 * Any embedding that follows the (discouraged!) practice of contructing script
00482 * structures manually should call this function to inform JSD. (older ssjs
00483 * systems do this).
00484 */
00485 extern JSD_PUBLIC_API(void)
00486 JSD_ScriptCreated(JSDContext* jsdc,
00487                   JSContext   *cx,
00488                   const char  *filename,    /* URL this script loads from */
00489                   uintN       lineno,       /* line where this script starts */
00490                   JSScript    *script,
00491                   JSFunction  *fun);
00492 
00493 /*
00494 * see JSD_ScriptCreated
00495 */
00496 extern JSD_PUBLIC_API(void)
00497 JSD_ScriptDestroyed(JSDContext* jsdc,
00498                     JSContext   *cx,
00499                     JSScript    *script);
00500 
00501 /***************************************************************************/
00502 /* Source Text functions */
00503 
00504 /*
00505 * In some embeddings (e.g. mozilla) JavaScript source code from a 'file' may be
00506 * execute before the entire 'file' has even been loaded. This system supports
00507 * access to such incrmentally loaded source. It also allows for the possibility
00508 * that source loading may fail or be aborted (though the source that did load
00509 * may still be usable). Remember that this source is the entire 'file'
00510 * contents and that the JavaScript code may only be part of that source.
00511 *
00512 * For any given URL there can only be one source text item (the most recently
00513 * loaded).
00514 */
00515 
00516 /* these coorespond to netscape.jsdebug.SourceTextItem.java values -
00517 *  change in both places if anywhere
00518 */
00519 
00520 typedef enum
00521 {
00522     JSD_SOURCE_INITED       = 0, /* initialized, but contains no source yet */
00523     JSD_SOURCE_PARTIAL      = 1, /* some source loaded, more expected */
00524     JSD_SOURCE_COMPLETED    = 2, /* all source finished loading */
00525     JSD_SOURCE_ABORTED      = 3, /* user aborted loading, some may be loaded */
00526     JSD_SOURCE_FAILED       = 4, /* loading failed, some may be loaded */
00527     JSD_SOURCE_CLEARED      = 5  /* text has been cleared by debugger */
00528 } JSDSourceStatus;
00529 
00530 /*
00531 * Lock the entire source text subsystem. This grabs a highlevel lock that
00532 * protects the JSD internal information about sources. It is important to
00533 * wrap source text related calls in this lock in multithreaded situations
00534 * -- i.e. where the debugger is running on a different thread than the
00535 * interpreter (or the loader of sources) -- or when multiple debugger
00536 * threads may be accessing this subsystem. It is safe (and best) to use
00537 * this locking even if the environment might not be multi-threaded.
00538 * Safely Nestable.
00539 */
00540 extern JSD_PUBLIC_API(void)
00541 JSD_LockSourceTextSubsystem(JSDContext* jsdc);
00542 
00543 /*
00544 * Unlock the entire source text subsystem. see JSD_LockSourceTextSubsystem.
00545 */
00546 extern JSD_PUBLIC_API(void)
00547 JSD_UnlockSourceTextSubsystem(JSDContext* jsdc);
00548 
00549 /*
00550 * Iterate the source test items. Use the same pattern of calls shown in
00551 * the example for JSD_IterateScripts - NOTE that the SourceTextSubsystem.
00552 * must be locked before and unlocked after iterating.
00553 */
00554 extern JSD_PUBLIC_API(JSDSourceText*)
00555 JSD_IterateSources(JSDContext* jsdc, JSDSourceText **iterp);
00556 
00557 /*
00558 * Find the source text item for the given URL (or filename - or whatever
00559 * string the given embedding uses to describe source locations).
00560 * Returns NULL is not found.
00561 */
00562 extern JSD_PUBLIC_API(JSDSourceText*)
00563 JSD_FindSourceForURL(JSDContext* jsdc, const char* url);
00564 
00565 /*
00566 * Get the URL string associated with the given source text item
00567 */
00568 extern JSD_PUBLIC_API(const char*)
00569 JSD_GetSourceURL(JSDContext* jsdc, JSDSourceText* jsdsrc);
00570 
00571 /*
00572 * Get the actual source text. This gives access to the actual storage of
00573 * the source - it sHould *not* be written to.
00574 * The buffer is NOT zero terminated (nor is it guaranteed to have space to
00575 * hold a zero terminating char).
00576 * XXX this is 8-bit character data. Unicode source is not yet supported.
00577 */
00578 extern JSD_PUBLIC_API(JSBool)
00579 JSD_GetSourceText(JSDContext* jsdc, JSDSourceText* jsdsrc,
00580                   const char** ppBuf, intN* pLen);
00581 
00582 /*
00583 * Clear the text -- delete the text and set the status to JSD_SOURCE_CLEARED.
00584 * This is useful if source is done loading and the debugger wishes to store
00585 * the text data itself (e.g. in a Java String). This allows avoidance of
00586 * storing the same text in multiple places.
00587 */
00588 extern JSD_PUBLIC_API(void)
00589 JSD_ClearSourceText(JSDContext* jsdc, JSDSourceText* jsdsrc);
00590 
00591 /*
00592 * Return the status of the source text item. see JSDSourceStatus enum.
00593 */
00594 extern JSD_PUBLIC_API(JSDSourceStatus)
00595 JSD_GetSourceStatus(JSDContext* jsdc, JSDSourceText* jsdsrc);
00596 
00597 /*
00598 * Has the source been altered since the last call to JSD_SetSourceDirty?
00599 * Use of JSD_IsSourceDirty and JSD_SetSourceDirty is still supported, but
00600 * discouraged in favor of the JSD_GetSourceAlterCount system. This dirty
00601 * scheme ASSUMES that there is only one consumer of the data.
00602 */
00603 extern JSD_PUBLIC_API(JSBool)
00604 JSD_IsSourceDirty(JSDContext* jsdc, JSDSourceText* jsdsrc);
00605 
00606 /*
00607 * Clear the dirty flag
00608 */
00609 extern JSD_PUBLIC_API(void)
00610 JSD_SetSourceDirty(JSDContext* jsdc, JSDSourceText* jsdsrc, JSBool dirty);
00611 
00612 /*
00613 * Each time a source text item is altered this value is incremented. Any
00614 * consumer can store this value when they retieve other data about the
00615 * source text item and then check later to see if the current value is
00616 * different from their stored value. Thus they can know if they have stale
00617 * data or not. NOTE: this value is not gauranteed to start at any given number.
00618 */
00619 extern JSD_PUBLIC_API(uintN)
00620 JSD_GetSourceAlterCount(JSDContext* jsdc, JSDSourceText* jsdsrc);
00621 
00622 /*
00623 * Force an increment in the alter count for a source text item. This is
00624 * normally automatic when the item changes, but a give consumer may want to
00625 * force this to amke an item appear to have changed even if it has not.
00626 */
00627 extern JSD_PUBLIC_API(uintN)
00628 JSD_IncrementSourceAlterCount(JSDContext* jsdc, JSDSourceText* jsdsrc);
00629 
00630 /*
00631 * Destroy *all* the source text items
00632 * (new for server-side USE WITH CARE)
00633 */
00634 extern JSD_PUBLIC_API(void)
00635 JSD_DestroyAllSources( JSDContext* jsdc );
00636 
00637 /* functions for adding source items */
00638 
00639 /*
00640 * Add a new item for a given URL. If an iten already exists for the given URL
00641 * then the old item is removed.
00642 * 'url' may not be NULL.
00643 */
00644 extern JSD_PUBLIC_API(JSDSourceText*)
00645 JSD_NewSourceText(JSDContext* jsdc, const char* url);
00646 
00647 /*
00648 * Append text (or change status -- e.g. set completed) for a source text
00649 * item. Text need not be zero terminated. Callers should consider the returned
00650 * JSDSourceText to be the 'current' item for future use. This may return NULL
00651 * if called after this item has been replaced by a call to JSD_NewSourceText.
00652 */
00653 extern JSD_PUBLIC_API(JSDSourceText*)
00654 JSD_AppendSourceText(JSDContext*     jsdc,
00655                      JSDSourceText*  jsdsrc,
00656                      const char*     text,       /* *not* zero terminated */
00657                      size_t          length,
00658                      JSDSourceStatus status);
00659 
00660 /*
00661 * Unicode varient of JSD_AppendSourceText.
00662 *
00663 * NOTE: At this point text is stored in 8bit ASCII so this function just
00664 * extracts the bottom 8bits from each jschar. At some future point we may
00665 * switch to storing and exposing 16bit Unicode.
00666 */
00667 extern JSD_PUBLIC_API(JSDSourceText*)
00668 JSD_AppendUCSourceText(JSDContext*     jsdc,
00669                        JSDSourceText*  jsdsrc,
00670                        const jschar*   text,       /* *not* zero terminated */
00671                        size_t          length,
00672                        JSDSourceStatus status);
00673 /*
00674  * Convienence function for adding complete source of url in one call.
00675  * same as:
00676  *   JSDSourceText* jsdsrc;
00677  *   JSD_LOCK_SOURCE_TEXT(jsdc);
00678  *   jsdsrc = jsd_NewSourceText(jsdc, url);
00679  *   if(jsdsrc)
00680  *       jsdsrc = jsd_AppendSourceText(jsdc, jsdsrc,
00681  *                                     text, length, JSD_SOURCE_PARTIAL);
00682  *   if(jsdsrc)
00683  *       jsdsrc = jsd_AppendSourceText(jsdc, jsdsrc,
00684  *                                     NULL, 0, JSD_SOURCE_COMPLETED);
00685  *   JSD_UNLOCK_SOURCE_TEXT(jsdc);
00686  *   return jsdsrc ? JS_TRUE : JS_FALSE;
00687  */
00688 extern JSD_PUBLIC_API(JSBool)
00689 JSD_AddFullSourceText(JSDContext* jsdc,
00690                       const char* text,       /* *not* zero terminated */
00691                       size_t      length,
00692                       const char* url);
00693 
00694 /***************************************************************************/
00695 /* Execution/Interrupt Hook functions */
00696 
00697 /* possible 'type' params for JSD_ExecutionHookProc */
00698 #define JSD_HOOK_INTERRUPTED            0
00699 #define JSD_HOOK_BREAKPOINT             1
00700 #define JSD_HOOK_DEBUG_REQUESTED        2
00701 #define JSD_HOOK_DEBUGGER_KEYWORD       3
00702 #define JSD_HOOK_THROW                  4
00703 
00704 /* legal return values for JSD_ExecutionHookProc */
00705 #define JSD_HOOK_RETURN_HOOK_ERROR      0
00706 #define JSD_HOOK_RETURN_CONTINUE        1
00707 #define JSD_HOOK_RETURN_ABORT           2
00708 #define JSD_HOOK_RETURN_RET_WITH_VAL    3
00709 #define JSD_HOOK_RETURN_THROW_WITH_VAL  4
00710 #define JSD_HOOK_RETURN_CONTINUE_THROW  5
00711 
00712 /*
00713 * Implement a callback of this form in order to hook execution.
00714 */
00715 typedef uintN
00716 (* JS_DLL_CALLBACK JSD_ExecutionHookProc)(JSDContext*     jsdc,
00717                                           JSDThreadState* jsdthreadstate,
00718                                           uintN           type,
00719                                           void*           callerdata,
00720                                           jsval*          rval);
00721 
00722 /* possible 'type' params for JSD_CallHookProc */
00723 #define JSD_HOOK_TOPLEVEL_START  0   /* about to evaluate top level script */
00724 #define JSD_HOOK_TOPLEVEL_END    1   /* done evaluting top level script    */
00725 #define JSD_HOOK_FUNCTION_CALL   2   /* about to call a function           */
00726 #define JSD_HOOK_FUNCTION_RETURN 3   /* done calling function              */
00727 
00728 /*
00729 * Implement a callback of this form in order to hook function call/returns.
00730 * Return JS_TRUE from a TOPLEVEL_START or FUNCTION_CALL type call hook if you
00731 * want to hear about the TOPLEVEL_END or FUNCTION_RETURN too.  Return value is
00732 * ignored to TOPLEVEL_END and FUNCTION_RETURN type hooks.
00733 */
00734 typedef JSBool
00735 (* JS_DLL_CALLBACK JSD_CallHookProc)(JSDContext*     jsdc,
00736                                      JSDThreadState* jsdthreadstate,
00737                                      uintN           type,
00738                                      void*           callerdata);
00739 
00740 /*
00741 * Set Hook to be called whenever the given pc is about to be executed --
00742 * i.e. for 'trap' or 'breakpoint'
00743 */
00744 extern JSD_PUBLIC_API(JSBool)
00745 JSD_SetExecutionHook(JSDContext*           jsdc,
00746                      JSDScript*            jsdscript,
00747                      jsuword               pc,
00748                      JSD_ExecutionHookProc hook,
00749                      void*                 callerdata);
00750 
00751 /*
00752 * Clear the hook for this pc
00753 */
00754 extern JSD_PUBLIC_API(JSBool)
00755 JSD_ClearExecutionHook(JSDContext*          jsdc,
00756                        JSDScript*           jsdscript,
00757                        jsuword              pc);
00758 
00759 /*
00760 * Clear all the pc specific hooks for this script
00761 */
00762 extern JSD_PUBLIC_API(JSBool)
00763 JSD_ClearAllExecutionHooksForScript(JSDContext* jsdc, JSDScript* jsdscript);
00764 
00765 /*
00766 * Clear all the pc specific hooks for the entire JSRuntime associated with
00767 * this JSDContext
00768 */
00769 extern JSD_PUBLIC_API(JSBool)
00770 JSD_ClearAllExecutionHooks(JSDContext* jsdc);
00771 
00772 /*
00773 * Set a hook to be called before the next instruction is executed. Depending
00774 * on the threading situation and whether or not an JS code is currently
00775 * executing the hook might be called before this call returns, or at some
00776 * future time. The hook will continue to be called as each instruction
00777 * executes until cleared.
00778 */
00779 extern JSD_PUBLIC_API(JSBool)
00780 JSD_SetInterruptHook(JSDContext*           jsdc,
00781                      JSD_ExecutionHookProc hook,
00782                      void*                 callerdata);
00783 
00784 /*
00785 * Clear the current interrupt hook.
00786 */
00787 extern JSD_PUBLIC_API(JSBool)
00788 JSD_ClearInterruptHook(JSDContext* jsdc);
00789 
00790 /*
00791 * Set the hook that should be called whenever a JSD_ErrorReporter hook
00792 * returns JSD_ERROR_REPORTER_DEBUG.
00793 */
00794 extern JSD_PUBLIC_API(JSBool)
00795 JSD_SetDebugBreakHook(JSDContext*           jsdc,
00796                       JSD_ExecutionHookProc hook,
00797                       void*                 callerdata);
00798 
00799 /*
00800 * Clear the debug break hook
00801 */
00802 extern JSD_PUBLIC_API(JSBool)
00803 JSD_ClearDebugBreakHook(JSDContext* jsdc);
00804 
00805 /*
00806 * Set the hook that should be called when the 'debugger' keyword is
00807 * encountered by the JavaScript interpreter during execution.
00808 */
00809 extern JSD_PUBLIC_API(JSBool)
00810 JSD_SetDebuggerHook(JSDContext*           jsdc,
00811                     JSD_ExecutionHookProc hook,
00812                     void*                 callerdata);
00813 
00814 /*
00815 * Clear the 'debugger' keyword hook
00816 */
00817 extern JSD_PUBLIC_API(JSBool)
00818 JSD_ClearDebuggerHook(JSDContext* jsdc);
00819 
00820 /*
00821 * Set the hook that should be called when a JS exception is thrown.
00822 * NOTE: the 'do default' return value is: JSD_HOOK_RETURN_CONTINUE_THROW
00823 */
00824 extern JSD_PUBLIC_API(JSBool)
00825 JSD_SetThrowHook(JSDContext*           jsdc,
00826                  JSD_ExecutionHookProc hook,
00827                  void*                 callerdata);
00828 /*
00829 * Clear the throw hook
00830 */
00831 extern JSD_PUBLIC_API(JSBool)
00832 JSD_ClearThrowHook(JSDContext* jsdc);
00833 
00834 /*
00835 * Set the hook that should be called when a toplevel script begins or completes.
00836 */
00837 extern JSD_PUBLIC_API(JSBool)
00838 JSD_SetTopLevelHook(JSDContext*      jsdc,
00839                     JSD_CallHookProc hook,
00840                     void*            callerdata);
00841 /*
00842 * Clear the toplevel call hook
00843 */
00844 extern JSD_PUBLIC_API(JSBool)
00845 JSD_ClearTopLevelHook(JSDContext* jsdc);
00846 
00847 /*
00848 * Set the hook that should be called when a function call or return happens.
00849 */
00850 extern JSD_PUBLIC_API(JSBool)
00851 JSD_SetFunctionHook(JSDContext*      jsdc,
00852                     JSD_CallHookProc hook,
00853                     void*            callerdata);
00854 /*
00855 * Clear the function call hook
00856 */
00857 extern JSD_PUBLIC_API(JSBool)
00858 JSD_ClearFunctionHook(JSDContext* jsdc);
00859 
00860 /***************************************************************************/
00861 /* Stack Frame functions */
00862 
00863 /*
00864 * Get the count of call stack frames for the given JSDThreadState
00865 */
00866 extern JSD_PUBLIC_API(uintN)
00867 JSD_GetCountOfStackFrames(JSDContext* jsdc, JSDThreadState* jsdthreadstate);
00868 
00869 /*
00870 * Get the 'current' call stack frame for the given JSDThreadState
00871 */
00872 extern JSD_PUBLIC_API(JSDStackFrameInfo*)
00873 JSD_GetStackFrame(JSDContext* jsdc, JSDThreadState* jsdthreadstate);
00874 
00875 /*
00876 * Get the JSContext for the given JSDThreadState
00877 */
00878 extern JSD_PUBLIC_API(JSContext*)
00879 JSD_GetJSContext(JSDContext* jsdc, JSDThreadState* jsdthreadstate);
00880 
00881 /*
00882 * Get the calling call stack frame for the given frame
00883 */
00884 extern JSD_PUBLIC_API(JSDStackFrameInfo*)
00885 JSD_GetCallingStackFrame(JSDContext* jsdc,
00886                          JSDThreadState* jsdthreadstate,
00887                          JSDStackFrameInfo* jsdframe);
00888 
00889 /*
00890 * Get the script for the given call stack frame
00891 */
00892 extern JSD_PUBLIC_API(JSDScript*)
00893 JSD_GetScriptForStackFrame(JSDContext* jsdc,
00894                            JSDThreadState* jsdthreadstate,
00895                            JSDStackFrameInfo* jsdframe);
00896 
00897 /*
00898 * Get the 'Program Counter' for the given call stack frame
00899 */
00900 extern JSD_PUBLIC_API(jsuword)
00901 JSD_GetPCForStackFrame(JSDContext* jsdc,
00902                        JSDThreadState* jsdthreadstate,
00903                        JSDStackFrameInfo* jsdframe);
00904 
00905 /*
00906 * Get the JavaScript Call Object for the given call stack frame.
00907 * *** new for version 1.1 ****
00908 */
00909 extern JSD_PUBLIC_API(JSDValue*)
00910 JSD_GetCallObjectForStackFrame(JSDContext* jsdc,
00911                                JSDThreadState* jsdthreadstate,
00912                                JSDStackFrameInfo* jsdframe);
00913 
00914 /*
00915 * Get the head of the scope chain for the given call stack frame.
00916 * the chain can be traversed using JSD_GetValueParent.
00917 * *** new for version 1.1 ****
00918 */
00919 extern JSD_PUBLIC_API(JSDValue*)
00920 JSD_GetScopeChainForStackFrame(JSDContext* jsdc,
00921                                JSDThreadState* jsdthreadstate,
00922                                JSDStackFrameInfo* jsdframe);
00923 
00924 /*
00925 * Get the 'this' Object for the given call stack frame.
00926 * *** new for version 1.1 ****
00927 */
00928 extern JSD_PUBLIC_API(JSDValue*)
00929 JSD_GetThisForStackFrame(JSDContext* jsdc,
00930                          JSDThreadState* jsdthreadstate,
00931                          JSDStackFrameInfo* jsdframe);
00932 
00933 /*
00934 * Get the name of the function executing in this stack frame.  Especially useful
00935 * for native frames (without script objects.)
00936 */
00937 extern JSD_PUBLIC_API(const char*)
00938 JSD_GetNameForStackFrame(JSDContext* jsdc,
00939                          JSDThreadState* jsdthreadstate,
00940                          JSDStackFrameInfo* jsdframe);
00941 
00942 /*
00943 * True if stack frame represents a native frame.
00944 */
00945 extern JSD_PUBLIC_API(JSBool)
00946 JSD_IsStackFrameNative(JSDContext* jsdc,
00947                        JSDThreadState* jsdthreadstate,
00948                        JSDStackFrameInfo* jsdframe);
00949 
00950 /*
00951 * True if stack frame represents a frame created as a result of a debugger
00952 * evaluation.
00953 */
00954 extern JSD_PUBLIC_API(JSBool)
00955 JSD_IsStackFrameDebugger(JSDContext* jsdc,
00956                          JSDThreadState* jsdthreadstate,
00957                          JSDStackFrameInfo* jsdframe);
00958 
00959 /*
00960 * True if stack frame is constructing a new object.
00961 */
00962 extern JSD_PUBLIC_API(JSBool)
00963 JSD_IsStackFrameConstructing(JSDContext* jsdc,
00964                              JSDThreadState* jsdthreadstate,
00965                              JSDStackFrameInfo* jsdframe);
00966 
00967 /*
00968 * Evaluate the given unicode source code in the context of the given stack frame.
00969 * returns JS_TRUE and puts result in rval on success, JS_FALSE on failure.
00970 * NOTE: The ErrorReporter hook might be called if this fails.
00971 */
00972 extern JSD_PUBLIC_API(JSBool)
00973 JSD_EvaluateUCScriptInStackFrame(JSDContext* jsdc,
00974                                  JSDThreadState* jsdthreadstate,
00975                                  JSDStackFrameInfo* jsdframe,
00976                                  const jschar *bytes, uintN length,
00977                                  const char *filename, uintN lineno,
00978                                  jsval *rval);
00979 
00980 /*
00981 * Same as above, but does not eat exceptions.
00982 */
00983 extern JSD_PUBLIC_API(JSBool)
00984 JSD_AttemptUCScriptInStackFrame(JSDContext* jsdc,
00985                                 JSDThreadState* jsdthreadstate,
00986                                 JSDStackFrameInfo* jsdframe,
00987                                 const jschar *bytes, uintN length,
00988                                 const char *filename, uintN lineno,
00989                                 jsval *rval);
00990 
00991 /* single byte character version of JSD_EvaluateUCScriptInStackFrame */
00992 extern JSD_PUBLIC_API(JSBool)
00993 JSD_EvaluateScriptInStackFrame(JSDContext* jsdc,
00994                                JSDThreadState* jsdthreadstate,
00995                                JSDStackFrameInfo* jsdframe,
00996                                const char *bytes, uintN length,
00997                                const char *filename, uintN lineno, jsval *rval);
00998 
00999 /*
01000 * Same as above, but does not eat exceptions.
01001 */
01002 extern JSD_PUBLIC_API(JSBool)
01003 JSD_AttemptScriptInStackFrame(JSDContext* jsdc,
01004                               JSDThreadState* jsdthreadstate,
01005                               JSDStackFrameInfo* jsdframe,
01006                               const char *bytes, uintN length,
01007                               const char *filename, uintN lineno, jsval *rval);
01008 
01009 /*
01010 * Convert the given jsval to a string
01011 * NOTE: The ErrorReporter hook might be called if this fails.
01012 */
01013 extern JSD_PUBLIC_API(JSString*)
01014 JSD_ValToStringInStackFrame(JSDContext* jsdc,
01015                             JSDThreadState* jsdthreadstate,
01016                             JSDStackFrameInfo* jsdframe,
01017                             jsval val);
01018 
01019 /*
01020 * Get the JSDValue currently being thrown as an exception (may be NULL).
01021 * NOTE: must eventually release by calling JSD_DropValue (if not NULL)
01022 * *** new for version 1.1 ****
01023 */
01024 extern JSD_PUBLIC_API(JSDValue*)
01025 JSD_GetException(JSDContext* jsdc, JSDThreadState* jsdthreadstate);
01026 
01027 /*
01028 * Set the JSDValue currently being thrown as an exception.
01029 * *** new for version 1.1 ****
01030 */
01031 extern JSD_PUBLIC_API(JSBool)
01032 JSD_SetException(JSDContext* jsdc, JSDThreadState* jsdthreadstate, 
01033                  JSDValue* jsdval);
01034 
01035 /***************************************************************************/
01036 /* Error Reporter functions */
01037 
01038 /*
01039 * XXX The ErrorReporter Hook scheme is going to change soon to more
01040 *     Fully support exceptions.
01041 */
01042 
01043 /* legal return values for JSD_ErrorReporter */
01044 #define JSD_ERROR_REPORTER_PASS_ALONG   0 /* pass along to regular reporter */
01045 #define JSD_ERROR_REPORTER_RETURN       1 /* don't pass to error reporter */
01046 #define JSD_ERROR_REPORTER_DEBUG        2 /* force call to DebugBreakHook */
01047 #define JSD_ERROR_REPORTER_CLEAR_RETURN 3 /* clear exception and don't pass */
01048 
01049 /*
01050 * Implement a callback of this form in order to hook the ErrorReporter
01051 */
01052 typedef uintN
01053 (* JS_DLL_CALLBACK JSD_ErrorReporter)(JSDContext*     jsdc,
01054                                       JSContext*      cx,
01055                                       const char*     message,
01056                                       JSErrorReport*  report,
01057                                       void*           callerdata);
01058 
01059 /* Set ErrorReporter hook */
01060 extern JSD_PUBLIC_API(JSBool)
01061 JSD_SetErrorReporter(JSDContext*       jsdc,
01062                      JSD_ErrorReporter reporter,
01063                      void*             callerdata);
01064 
01065 /* Get Current ErrorReporter hook */
01066 extern JSD_PUBLIC_API(JSBool)
01067 JSD_GetErrorReporter(JSDContext*        jsdc,
01068                      JSD_ErrorReporter* reporter,
01069                      void**             callerdata);
01070 
01071 /***************************************************************************/
01072 /* Generic locks that callers can use for their own purposes */
01073 
01074 /*
01075 * Is Locking and GetThread supported in this build?
01076 */
01077 extern JSD_PUBLIC_API(JSBool)
01078 JSD_IsLockingAndThreadIdSupported();
01079 
01080 /*
01081 * Create a reentrant/nestable lock
01082 */
01083 extern JSD_PUBLIC_API(void*)
01084 JSD_CreateLock();
01085 
01086 /*
01087 * Aquire lock for this thread (or block until available). Increments a
01088 * counter if this thread already owns the lock.
01089 */
01090 extern JSD_PUBLIC_API(void)
01091 JSD_Lock(void* lock);
01092 
01093 /*
01094 * Release lock for this thread (or decrement the counter if JSD_Lock
01095 * was previous called more than once).
01096 */
01097 extern JSD_PUBLIC_API(void)
01098 JSD_Unlock(void* lock);
01099 
01100 /*
01101 * For debugging only if not (JS_THREADSAFE AND DEBUG) then returns JS_TRUE
01102 *    So JSD_IsLocked(lock) may not equal !JSD_IsUnlocked(lock)
01103 */
01104 extern JSD_PUBLIC_API(JSBool)
01105 JSD_IsLocked(void* lock);
01106 
01107 /*
01108 * See above...
01109 */
01110 extern JSD_PUBLIC_API(JSBool)
01111 JSD_IsUnlocked(void* lock);
01112 
01113 /*
01114 * return an ID uniquely identifying this thread.
01115 */
01116 extern JSD_PUBLIC_API(void*)
01117 JSD_CurrentThread();
01118 
01119 /***************************************************************************/
01120 /* Value and Property Functions  --- All NEW for 1.1 --- */
01121 
01122 /*
01123 * NOTE: JSDValue and JSDProperty objects are reference counted. This allows
01124 * for rooting these objects AND any underlying garbage collected jsvals.
01125 * ALL JSDValue and JSDProperty objects returned by the functions below
01126 * MUST eventually be released using the appropriate JSD_Dropxxx function.
01127 */
01128 
01129 /*
01130 * Create a new JSDValue to wrap the given jsval
01131 * NOTE: must eventually release by calling JSD_DropValue (if not NULL)
01132 * *** new for version 1.1 ****
01133 */
01134 extern JSD_PUBLIC_API(JSDValue*)
01135 JSD_NewValue(JSDContext* jsdc, jsval val);
01136 
01137 /*
01138 * Release the JSDValue. After this call the object MUST not be referenced again!
01139 * *** new for version 1.1 ****
01140 */
01141 extern JSD_PUBLIC_API(void)
01142 JSD_DropValue(JSDContext* jsdc, JSDValue* jsdval);
01143 
01144 /*
01145 * Get the jsval wrapped by this JSDValue
01146 * *** new for version 1.1 ****
01147 */
01148 extern JSD_PUBLIC_API(jsval)
01149 JSD_GetValueWrappedJSVal(JSDContext* jsdc, JSDValue* jsdval);
01150 
01151 /*
01152 * Clear all property and association information about the given JSDValue.
01153 * Such information will be lazily regenerated when later accessed. This
01154 * function must be called to make changes to the properties of an object
01155 * visible to the accessor functions below (if the properties et.al. have
01156 * changed since a previous call to those accessors).
01157 * *** new for version 1.1 ****
01158 */
01159 extern JSD_PUBLIC_API(void)
01160 JSD_RefreshValue(JSDContext* jsdc, JSDValue* jsdval);
01161 
01162 /**************************************************/
01163 
01164 /*
01165 * Does the JSDValue wrap a JSObject?
01166 * *** new for version 1.1 ****
01167 */
01168 extern JSD_PUBLIC_API(JSBool)
01169 JSD_IsValueObject(JSDContext* jsdc, JSDValue* jsdval);
01170 
01171 /*
01172 * Does the JSDValue wrap a number (int or double)?
01173 * *** new for version 1.1 ****
01174 */
01175 extern JSD_PUBLIC_API(JSBool)
01176 JSD_IsValueNumber(JSDContext* jsdc, JSDValue* jsdval);
01177 
01178 /*
01179 * Does the JSDValue wrap an int?
01180 * *** new for version 1.1 ****
01181 */
01182 extern JSD_PUBLIC_API(JSBool)
01183 JSD_IsValueInt(JSDContext* jsdc, JSDValue* jsdval);
01184 
01185 /*
01186 * Does the JSDValue wrap a double?
01187 * *** new for version 1.1 ****
01188 */
01189 extern JSD_PUBLIC_API(JSBool)
01190 JSD_IsValueDouble(JSDContext* jsdc, JSDValue* jsdval);
01191 
01192 /*
01193 * Does the JSDValue wrap a JSString?
01194 * *** new for version 1.1 ****
01195 */
01196 extern JSD_PUBLIC_API(JSBool)
01197 JSD_IsValueString(JSDContext* jsdc, JSDValue* jsdval);
01198 
01199 /*
01200 * Does the JSDValue wrap a JSBool?
01201 * *** new for version 1.1 ****
01202 */
01203 extern JSD_PUBLIC_API(JSBool)
01204 JSD_IsValueBoolean(JSDContext* jsdc, JSDValue* jsdval);
01205 
01206 /*
01207 * Does the JSDValue wrap a JSVAL_NULL?
01208 * *** new for version 1.1 ****
01209 */
01210 extern JSD_PUBLIC_API(JSBool)
01211 JSD_IsValueNull(JSDContext* jsdc, JSDValue* jsdval);
01212 
01213 /*
01214 * Does the JSDValue wrap a JSVAL_VOID?
01215 * *** new for version 1.1 ****
01216 */
01217 extern JSD_PUBLIC_API(JSBool)
01218 JSD_IsValueVoid(JSDContext* jsdc, JSDValue* jsdval);
01219 
01220 /*
01221 * Does the JSDValue wrap a primative (not a JSObject)?
01222 * *** new for version 1.1 ****
01223 */
01224 extern JSD_PUBLIC_API(JSBool)
01225 JSD_IsValuePrimitive(JSDContext* jsdc, JSDValue* jsdval);
01226 
01227 /*
01228 * Does the JSDValue wrap a function?
01229 * *** new for version 1.1 ****
01230 */
01231 extern JSD_PUBLIC_API(JSBool)
01232 JSD_IsValueFunction(JSDContext* jsdc, JSDValue* jsdval);
01233 
01234 /*
01235 * Does the JSDValue wrap a native function?
01236 * *** new for version 1.1 ****
01237 */
01238 extern JSD_PUBLIC_API(JSBool)
01239 JSD_IsValueNative(JSDContext* jsdc, JSDValue* jsdval);
01240 
01241 /**************************************************/
01242 
01243 /*
01244 * Return JSBool value (does NOT do conversion).
01245 * *** new for version 1.1 ****
01246 */
01247 extern JSD_PUBLIC_API(JSBool)
01248 JSD_GetValueBoolean(JSDContext* jsdc, JSDValue* jsdval);
01249 
01250 /*
01251 * Return int32 value (does NOT do conversion).
01252 * *** new for version 1.1 ****
01253 */
01254 extern JSD_PUBLIC_API(int32)
01255 JSD_GetValueInt(JSDContext* jsdc, JSDValue* jsdval);
01256 
01257 /*
01258 * Return double value (does NOT do conversion).
01259 * *** new for version 1.1 ****
01260 */
01261 extern JSD_PUBLIC_API(jsdouble*)
01262 JSD_GetValueDouble(JSDContext* jsdc, JSDValue* jsdval);
01263 
01264 /*
01265 * Return JSString value (DOES do conversion if necessary).
01266 * NOTE that the JSString returned is not protected from garbage
01267 * collection. It should be immediately read or wrapped using
01268 * JSD_NewValue(jsdc,STRING_TO_JSVAL(str)) if necessary.
01269 * *** new for version 1.1 ****
01270 */
01271 extern JSD_PUBLIC_API(JSString*)
01272 JSD_GetValueString(JSDContext* jsdc, JSDValue* jsdval);
01273 
01274 /*
01275 * Return name of function IFF JSDValue represents a function.
01276 * *** new for version 1.1 ****
01277 */
01278 extern JSD_PUBLIC_API(const char*)
01279 JSD_GetValueFunctionName(JSDContext* jsdc, JSDValue* jsdval);
01280 
01281 /**************************************************/
01282 
01283 /*
01284 * Return the number of properties for the JSDValue.
01285 * *** new for version 1.1 ****
01286 */
01287 extern JSD_PUBLIC_API(uintN)
01288 JSD_GetCountOfProperties(JSDContext* jsdc, JSDValue* jsdval);
01289 
01290 /*
01291 * Iterate through the properties of the JSDValue.
01292 * Use form similar to that shown for JSD_IterateScripts (no locking required).
01293 * NOTE: each JSDProperty returned must eventually be released by calling
01294 * JSD_DropProperty.
01295 * *** new for version 1.1 ****
01296 */
01297 extern JSD_PUBLIC_API(JSDProperty*)
01298 JSD_IterateProperties(JSDContext* jsdc, JSDValue* jsdval, JSDProperty **iterp);
01299 
01300 /* 
01301 * Get the JSDProperty for the property of this JSDVal with this name.
01302 * NOTE: must eventually release by calling JSD_DropProperty (if not NULL)
01303 * *** new for version 1.1 ****
01304 */
01305 extern JSD_PUBLIC_API(JSDProperty*)
01306 JSD_GetValueProperty(JSDContext* jsdc, JSDValue* jsdval, JSString* name);
01307 
01308 /*
01309 * Get the prototype object for this JSDValue.
01310 * NOTE: must eventually release by calling JSD_DropValue (if not NULL)
01311 * *** new for version 1.1 ****
01312 */
01313 extern JSD_PUBLIC_API(JSDValue*)
01314 JSD_GetValuePrototype(JSDContext* jsdc, JSDValue* jsdval);
01315 
01316 /*
01317 * Get the parent object for this JSDValue.
01318 * NOTE: must eventually release by calling JSD_DropValue (if not NULL)
01319 * *** new for version 1.1 ****
01320 */
01321 extern JSD_PUBLIC_API(JSDValue*)
01322 JSD_GetValueParent(JSDContext* jsdc, JSDValue* jsdval);
01323 
01324 /*
01325 * Get the ctor object for this JSDValue (or likely its prototype's ctor).
01326 * NOTE: must eventually release by calling JSD_DropValue (if not NULL)
01327 * *** new for version 1.1 ****
01328 */
01329 extern JSD_PUBLIC_API(JSDValue*)
01330 JSD_GetValueConstructor(JSDContext* jsdc, JSDValue* jsdval);
01331 
01332 /*
01333 * Get the name of the class for this object.
01334 * *** new for version 1.1 ****
01335 */
01336 extern JSD_PUBLIC_API(const char*)
01337 JSD_GetValueClassName(JSDContext* jsdc, JSDValue* jsdval);
01338 
01339 /**************************************************/
01340 
01341 /* possible or'd together bitflags returned by JSD_GetPropertyFlags
01342  *
01343  * XXX these must stay the same as the JSPD_ flags in jsdbgapi.h
01344  */
01345 #define JSDPD_ENUMERATE  JSPD_ENUMERATE    /* visible to for/in loop */
01346 #define JSDPD_READONLY   JSPD_READONLY     /* assignment is error */
01347 #define JSDPD_PERMANENT  JSPD_PERMANENT    /* property cannot be deleted */
01348 #define JSDPD_ALIAS      JSPD_ALIAS        /* property has an alias id */
01349 #define JSDPD_ARGUMENT   JSPD_ARGUMENT     /* argument to function */
01350 #define JSDPD_VARIABLE   JSPD_VARIABLE     /* local variable in function */
01351 #define JSDPD_EXCEPTION  JSPD_EXCEPTION    /* exception occurred looking up */
01352                                            /* proprety, value is exception  */
01353 #define JSDPD_ERROR      JSPD_ERROR        /* native getter returned JS_FALSE */
01354                                            /* without throwing an exception */
01355 /* this is not one of the JSPD_ flags in jsdbgapi.h  - careful not to overlap*/
01356 #define JSDPD_HINTED     0x800             /* found via explicit lookup */
01357 
01358 /*
01359 * Release this JSDProperty
01360 * *** new for version 1.1 ****
01361 */
01362 extern JSD_PUBLIC_API(void)
01363 JSD_DropProperty(JSDContext* jsdc, JSDProperty* jsdprop);
01364 
01365 /*
01366 * Get the JSDValue represeting the name of this property (int or string)
01367 * NOTE: must eventually release by calling JSD_DropValue
01368 * *** new for version 1.1 ****
01369 */
01370 extern JSD_PUBLIC_API(JSDValue*)
01371 JSD_GetPropertyName(JSDContext* jsdc, JSDProperty* jsdprop);
01372 
01373 /*
01374 * Get the JSDValue represeting the current value of this property
01375 * NOTE: must eventually release by calling JSD_DropValue (if not NULL)
01376 * *** new for version 1.1 ****
01377 */
01378 extern JSD_PUBLIC_API(JSDValue*)
01379 JSD_GetPropertyValue(JSDContext* jsdc, JSDProperty* jsdprop);
01380 
01381 /*
01382 * Get the JSDValue represeting the alias of this property (if JSDPD_ALIAS set)
01383 * NOTE: must eventually release by calling JSD_DropValue (if not NULL)
01384 * *** new for version 1.1 ****
01385 */
01386 extern JSD_PUBLIC_API(JSDValue*)
01387 JSD_GetPropertyAlias(JSDContext* jsdc, JSDProperty* jsdprop);
01388 
01389 /*
01390 * Get the flags for this property
01391 * *** new for version 1.1 ****
01392 */
01393 extern JSD_PUBLIC_API(uintN)
01394 JSD_GetPropertyFlags(JSDContext* jsdc, JSDProperty* jsdprop);
01395 
01396 /*
01397 * Get Variable or Argument slot number (if JSDPD_ARGUMENT or JSDPD_VARIABLE set)
01398 * *** new for version 1.1 ****
01399 */
01400 extern JSD_PUBLIC_API(uintN)
01401 JSD_GetPropertyVarArgSlot(JSDContext* jsdc, JSDProperty* jsdprop);
01402 
01403 /***************************************************************************/
01404 /* Object Functions  --- All NEW for 1.1 --- */
01405 
01406 /*
01407 * JSDObjects exist to allow a means of iterating through all JSObjects in the
01408 * engine. They are created and destroyed as the wrapped JSObjects are created
01409 * and destroyed in the engine. JSDObjects additionally track the location in
01410 * the JavaScript source where their wrapped JSObjects were created and the name
01411 * and location of the (non-native) constructor used.
01412 *
01413 * NOTE: JSDObjects are NOT reference counted. The have only weak links to
01414 * jsObjects - thus they do not inhibit garbage collection of JSObjects. If
01415 * you need a JSDObject to safely persist then wrap it in a JSDValue (using
01416 * jsd_GetValueForObject).
01417 */
01418 
01419 /*
01420 * Lock the entire Object subsystem -- see JSD_UnlockObjectSubsystem
01421 * *** new for version 1.1 ****
01422 */
01423 extern JSD_PUBLIC_API(void)
01424 JSD_LockObjectSubsystem(JSDContext* jsdc);
01425 
01426 /*
01427 * Unlock the entire Object subsystem -- see JSD_LockObjectSubsystem
01428 * *** new for version 1.1 ****
01429 */
01430 extern JSD_PUBLIC_API(void)
01431 JSD_UnlockObjectSubsystem(JSDContext* jsdc);
01432 
01433 /*
01434 * Iterate through the known objects
01435 * Use form similar to that shown for JSD_IterateScripts.
01436 * NOTE: the ObjectSubsystem must be locked before and unlocked after iterating.
01437 * *** new for version 1.1 ****
01438 */
01439 extern JSD_PUBLIC_API(JSDObject*)
01440 JSD_IterateObjects(JSDContext* jsdc, JSDObject** iterp);
01441 
01442 /*
01443 * Get the JSObject represented by this JSDObject
01444 * *** new for version 1.1 ****
01445 */
01446 extern JSD_PUBLIC_API(JSObject*)
01447 JSD_GetWrappedObject(JSDContext* jsdc, JSDObject* jsdobj);
01448 
01449 /*
01450 * Get the URL of the line of source that caused this object to be created.
01451 * May be NULL.
01452 * *** new for version 1.1 ****
01453 */
01454 extern JSD_PUBLIC_API(const char*)
01455 JSD_GetObjectNewURL(JSDContext* jsdc, JSDObject* jsdobj);
01456 
01457 /*
01458 * Get the line number of the line of source that caused this object to be
01459 * created. May be 0 indicating that the line number is unknown.
01460 * *** new for version 1.1 ****
01461 */
01462 extern JSD_PUBLIC_API(uintN)
01463 JSD_GetObjectNewLineNumber(JSDContext* jsdc, JSDObject* jsdobj);
01464 
01465 /*
01466 * Get the URL of the line of source of the constructor for this object.
01467 * May be NULL.
01468 * *** new for version 1.1 ****
01469 */
01470 extern JSD_PUBLIC_API(const char*)
01471 JSD_GetObjectConstructorURL(JSDContext* jsdc, JSDObject* jsdobj);
01472 
01473 /*
01474 * Get the line number of the line of source of the constuctor for this object.
01475 * created. May be 0 indicating that the line number is unknown.
01476 * *** new for version 1.1 ****
01477 */
01478 extern JSD_PUBLIC_API(uintN)
01479 JSD_GetObjectConstructorLineNumber(JSDContext* jsdc, JSDObject* jsdobj);
01480 
01481 /*
01482 * Get the name of the constructor for this object.
01483 * May be NULL.
01484 * *** new for version 1.1 ****
01485 */
01486 extern JSD_PUBLIC_API(const char*)
01487 JSD_GetObjectConstructorName(JSDContext* jsdc, JSDObject* jsdobj);
01488 
01489 /*
01490 * Get JSDObject representing this JSObject.
01491 * May return NULL.
01492 * *** new for version 1.1 ****
01493 */
01494 extern JSD_PUBLIC_API(JSDObject*)
01495 JSD_GetJSDObjectForJSObject(JSDContext* jsdc, JSObject* jsobj);
01496 
01497 /*
01498 * Get JSDObject representing this JSDValue.
01499 * May return NULL.
01500 * *** new for version 1.1 ****
01501 */
01502 extern JSD_PUBLIC_API(JSDObject*)
01503 JSD_GetObjectForValue(JSDContext* jsdc, JSDValue* jsdval);
01504 
01505 /*
01506 * Create a JSDValue to wrap (and root) this JSDObject.
01507 * NOTE: must eventually release by calling JSD_DropValue (if not NULL)
01508 * *** new for version 1.1 ****
01509 */
01510 extern JSD_PUBLIC_API(JSDValue*)
01511 JSD_GetValueForObject(JSDContext* jsdc, JSDObject* jsdobj);
01512 
01513 /***************************************************************************/
01514 /* Livewire specific API */
01515 #ifdef LIVEWIRE
01516 
01517 extern JSD_PUBLIC_API(LWDBGScript*)
01518 JSDLW_GetLWScript(JSDContext* jsdc, JSDScript* jsdscript);
01519 
01520 extern JSD_PUBLIC_API(JSDSourceText*)
01521 JSDLW_PreLoadSource(JSDContext* jsdc, LWDBGApp* app,
01522                     const char* filename, JSBool clear);
01523 
01524 extern JSD_PUBLIC_API(JSDSourceText*)
01525 JSDLW_ForceLoadSource(JSDContext* jsdc, JSDSourceText* jsdsrc);
01526 
01527 extern JSD_PUBLIC_API(JSBool)
01528 JSDLW_RawToProcessedLineNumber(JSDContext* jsdc, JSDScript* jsdscript,
01529                                uintN lineIn, uintN* lineOut);
01530 
01531 extern JSD_PUBLIC_API(JSBool)
01532 JSDLW_ProcessedToRawLineNumber(JSDContext* jsdc, JSDScript* jsdscript,
01533                                uintN lineIn, uintN* lineOut);
01534 
01535 #endif
01536 /***************************************************************************/
01537 
01538 JS_END_EXTERN_C
01539 
01540 #endif /* jsdebug_h___ */