diff options
Diffstat (limited to 'common/quicktime_win32/Debugging.h')
| -rw-r--r-- | common/quicktime_win32/Debugging.h | 1073 |
1 files changed, 1073 insertions, 0 deletions
diff --git a/common/quicktime_win32/Debugging.h b/common/quicktime_win32/Debugging.h new file mode 100644 index 0000000..d106df2 --- /dev/null +++ b/common/quicktime_win32/Debugging.h @@ -0,0 +1,1073 @@ +/* + File: Debugging.h + + Contains: Macros to handle exceptions and assertions. + + Version: QuickTime 7.3 + + Copyright: (c) 2007 (c) 1989-2001 by Apple Computer, Inc., all rights reserved. + + Bugs?: For bug reports, consult the following page on + the World Wide Web: + + http://developer.apple.com/bugreporter/ + +*/ +#ifndef __DEBUGGING__ +#define __DEBUGGING__ + +#ifndef __MACTYPES__ +#include <MacTypes.h> +#endif + +#ifndef __MIXEDMODE__ +#include <MixedMode.h> +#endif + +#ifndef __MACERRORS__ +#include <MacErrors.h> +#endif + +#include <Events.h> +#ifndef __GESTALT__ +#include <Gestalt.h> +#endif + + + +#if PRAGMA_ONCE +#pragma once +#endif + +#ifdef __cplusplus +extern "C" { +#endif + +#if PRAGMA_IMPORT +#pragma import on +#endif + +/* + This file supplies standard debugging routines and macros to Carbon and + Classic Mac OS programs. Other C programs which wish to use the + exception handling and assertion macros should include AssertMacros.h + instead of this file. + + To activate debugger breaks, #define DEBUG to 1 (one) before including this + file. Five further levels of debugging are available, selected by #defining + one of the following conditionals to 1 after DEBUG is defined to 1. + + DEBUG_INTERNAL the default; asserts include file and line number + information + + DEBUG_EXTERNAL used for code which must ship to developers outside + your organization; no file or line number + information is included in asserts + + DEBUG_BREAK_ONLY where an assertion string would normally be sent to + the debugger; call Debugger() instead. + + PRODUCTION used for shipping code; no debugger breaks are + emitted + + PERFORMANCE same as PRODUCTION + + #defining DEBUG to 0 is equivalent to #defining PRODUCTION 1 when + DEBUG is 1. (No code for debugger breaks is emitted in either case.) + + #defining DEBUG to 1 without specifying a level is equivalent to #defining + DEBUG_INTERNAL 1. + + In addition, these macros should also be #defined (they are described in detail below): + kComponentSignatureString + COMPONENT_SIGNATURE +*/ +/* + * Before including this file, #define kComponentSignatureString to a C-string + * containing the name of your client and #define COMPONENT_SIGNATURE to your + * client's unique signature (i.e., your program's registered creator type). + * For example: + * + * #define kComponentSignatureString "SurfWriter" + * #define COMPONENT_SIGNATURE 'WAVE' + * + * If you don't define kComponentSignatureString and COMPONENT_SIGNATURE, the + * default kComponentSignatureString and COMPONENT_SIGNATURE values will be + * used by the DEBUGASSERTMSG macros below. + */ + +#ifndef kComponentSignatureString + #define kComponentSignatureString "Third Party Client" +#endif +#ifndef COMPONENT_SIGNATURE + #define COMPONENT_SIGNATURE '?*?*' +#endif +#define QuoteExceptionString(x) #x + + +/* + * The DEBUGLEVEL's + */ +#define DEBUG_LEVEL_PRODUCTION 0 +#define DEBUG_LEVEL_BREAK_ONLY 1 +#define DEBUG_LEVEL_EXTERNAL 3 +#define DEBUG_LEVEL_INTERNAL 4 +#define DEBUGFULL DEBUG_LEVEL_INTERNAL + +/* + * define DEBUGLEVEL + */ +#if DEBUG + #if PRODUCTION + #define DEBUGLEVEL DEBUG_LEVEL_PRODUCTION + #elif PERFORMANCE + #define DEBUGLEVEL DEBUG_LEVEL_PRODUCTION + #elif DEBUG_BREAK_ONLY + #define DEBUGLEVEL DEBUG_LEVEL_BREAK_ONLY + #elif DEBUG_EXTERNAL + #define DEBUGLEVEL DEBUG_LEVEL_EXTERNAL + #elif DEBUG_INTERNAL + #define DEBUGLEVEL DEBUG_LEVEL_INTERNAL + #else + /* default to DEBUG_LEVEL_INTERNAL */ + #define DEBUGLEVEL DEBUG_LEVEL_INTERNAL + #endif +#endif +#ifndef DEBUGLEVEL +#define DEBUGLEVEL DEBUG_LEVEL_PRODUCTION +#endif + + + +/* + * The options parameter to DebugAssert and DEBUGASSERTMSG is currently reserved (must be zero). + */ +#define DEBUG_NO_OPTIONS 0 + +/* + * DEBUGASSERTMSG() + * + * Summary: + * All error reporting is routed through this macro, which calls the system + * routine DebugAssert(). If you wish to use your own assertion break + * routine, you can override DEBUGASSERTMSG by defining it before including + * this file. + * + * Parameters: + * + * componentSignature: + * The unique signature of component causing the assertion. + * + * options: + * reserved. + * + * assertionString: + * A pointer to a string constant containing the assertion. + * This must be a string constant (and not a string variable or + * NULL) because the Proeprocessor concatenates it with other + * string constants + * + * exceptionLabelString: + * A pointer to a string containing the exceptionLabel, or NULL. + * + * errorString: + * A pointer to the error string, or NULL. DEBUGASSERTMSG macros + * must not attempt to concatenate this string with constant + * character strings. + * + * fileName: + * A pointer to the fileName or pathname (generated by the + * preprocessor __FILE__ identifier), or NULL. + * + * lineNumber: + * The line number in the file (generated by the preprocessor + * __LINE__ identifier), or 0 (zero). + * + * value: + * A value associated with the assertion, or NULL. + */ + +#ifndef DEBUGASSERTMSG + #if DEBUGLEVEL == DEBUG_LEVEL_PRODUCTION + /* no debugger message */ + #define DEBUGASSERTMSG(componentSignature, options, assertionString, exceptionLabelString, errorString, fileName, lineNumber, value) + #elif DEBUGLEVEL == DEBUG_LEVEL_BREAK_ONLY + /* call Debugger() if it is available */ + #define DEBUGASSERTMSG(componentSignature, options, assertionString, exceptionLabelString, errorString, fileName, lineNumber, value) \ + Debugger() + #elif DEBUGLEVEL == DEBUG_LEVEL_EXTERNAL + /* exclude fileName and lineNumber */ + #define DEBUGASSERTMSG(componentSignature, options, assertionString, exceptionLabelString, errorString, fileName, lineNumber, value) \ + DebugAssert(componentSignature, options, assertionString, exceptionLabelString, errorString, 0, 0, (void*)value) + #else + /* include all info */ + #define DEBUGASSERTMSG(componentSignature, options, assertionString, exceptionLabelString, errorString, fileName, lineNumber, value) \ + DebugAssert(componentSignature, options, assertionString, exceptionLabelString, errorString, fileName, lineNumber, (void*)value) + #endif +#endif + +/* + * Define the three inputs to AssertMacros.h + */ + +#ifndef DEBUG_ASSERT_COMPONENT_NAME_STRING + #define DEBUG_ASSERT_COMPONENT_NAME_STRING kComponentSignatureString +#endif +#ifndef DEBUG_ASSERT_PRODUCTION_CODE + #define DEBUG_ASSERT_PRODUCTION_CODE (DEBUGLEVEL==0) +#endif +#ifndef DEBUG_ASSERT_MESSAGE + #define DEBUG_ASSERT_MESSAGE(componentNameString, assertionString, exceptionLabelString, errorString, fileName, lineNumber, value) \ + DEBUGASSERTMSG(COMPONENT_SIGNATURE, DEBUG_NO_OPTIONS, componentNameString ": " assertionString, exceptionLabelString, errorString, fileName, lineNumber, value) +#endif + +/* + * Include AssertMacros.h where all of the check, verify, and require macros are defined + */ +#include <AssertMacros.h> +/* + * The following check, verify, and require macros assert that TaskLevel is 0. + */ + +#define ATTASKLEVEL0() \ + (TaskLevel() == 0) + + +#define check_tasklevel0() \ + check(ATTASKLEVEL0()) + + +#define check_tasklevel0_string(cstring) \ + check_string(ATTASKLEVEL0(), cstring) + + +#define verify_tasklevel0() \ + verify(ATTASKLEVEL0()) + + +#define verify_tasklevel0_string(cstring) \ + verify_string(ATTASKLEVEL0(), cstring) + + +#define require_tasklevel0(exceptionLabel) \ + require(ATTASKLEVEL0(), exceptionLabel) + + +#define require_tasklevel0_action(exceptionLabel, action) \ + require_action(ATTASKLEVEL0(), exceptionLabel, action) + + +#define require_tasklevel0_quiet(exceptionLabel) \ + require_quiet(ATTASKLEVEL0(), exceptionLabel) + + +#define require_tasklevel0_action_quiet(exceptionLabel, action) \ + require_action_quiet(ATTASKLEVEL0(), exceptionLabel, action) + + +#define require_tasklevel0_string(exceptionLabel, cstring) \ + require_string(ATTASKLEVEL0(), exceptionLabel, cstring) + + +#define require_tasklevel0_action_string(exceptionLabel, action, cstring) \ + require_action_string(ATTASKLEVEL0(), exceptionLabel, action, cstring) + +/* + * SafeDebugger and SafeDebugStr work like Debugger and DebugStr in both + * production and non-preduction builds, but only call the debugger + * if the debugger is installed. + */ + +#if CALL_NOT_IN_CARBON + /* Make sure a low level debugger is installed on Mac OS 8 or 9 */ + #define SafeDebugger() \ + do \ + { \ + if ( ((*((UInt8 *)0x0BFF)) != (UInt8)0xff) && \ + (((*((UInt8 *)0x0BFF)) & (UInt8)0xe0) == (UInt8)0x60) && \ + ((*((unsigned long *)0x0120)) != 0) && \ + ((*((unsigned long *)0x0120)) != (unsigned long)0xffffffff) ) \ + { \ + Debugger(); \ + } \ + } while ( false ) +#else + /* Debugger() is always safe on Carbon under Mac OS X */ + /* Otherwise we must make sure a low level debugger is installed */ + #define SafeDebugger() \ + do \ + { \ + long response; \ + if ( (Gestalt(gestaltSystemVersion, &response) == noErr) && \ + (response >= 0x1000) ) \ + { \ + Debugger(); \ + } \ + else \ + { \ + if ( ((*((UInt8 *)0x0BFF)) != (UInt8)0xff) && \ + (((*((UInt8 *)0x0BFF)) & (UInt8)0xe0) == (UInt8)0x60) && \ + ((*((unsigned long *)0x0120)) != 0) && \ + ((*((unsigned long *)0x0120)) != (unsigned long)0xffffffff) ) \ + { \ + Debugger(); \ + } \ + } \ + } while ( false ) +#endif + + +#if CALL_NOT_IN_CARBON + /* Make sure low level debugger is installed on Mac OS 8 or 9 */ + #define SafeDebugStr(str) \ + do \ + { \ + if ( ((*((UInt8 *)0x0BFF)) != (UInt8)0xff) && \ + (((*((UInt8 *)0x0BFF)) & (UInt8)0xe0) == (UInt8)0x60) && \ + ((*((unsigned long *)0x0120)) != 0) && \ + ((*((unsigned long *)0x0120)) != (unsigned long)0xffffffff) ) \ + { \ + DebugStr(str); \ + } \ + } while ( false ) +#else + /* DebugStr() is always safe on Carbon under Mac OS X */ + /* Otherwise we must make sure a low level debugger is installed */ + #define SafeDebugStr(str) \ + do \ + { \ + long response; \ + if ( (Gestalt(gestaltSystemVersion, &response) == noErr) && \ + (response >= 0x1000) ) \ + { \ + DebugStr(str); \ + } \ + else \ + { \ + if ( ((*((UInt8 *)0x0BFF)) != (UInt8)0xff) && \ + (((*((UInt8 *)0x0BFF)) & (UInt8)0xe0) == (UInt8)0x60) && \ + ((*((unsigned long *)0x0120)) != 0) && \ + ((*((unsigned long *)0x0120)) != (unsigned long)0xffffffff) ) \ + { \ + DebugStr(str); \ + } \ + } \ + } while ( false ) +#endif + +/* + * DEBUGGER and DEBUGSTR call SafeDebugger and SafeDebugStr only + * in DEBUG builds. + * + * DEBUGGER and DEBUGSTR are defined only if they are not already defined to + * prevent conflicts with developer code. + */ + +#ifndef DEBUGGER + #if DEBUG + #define DEBUGGER() \ + SafeDebugger() + #else + #define DEBUGGER() + #endif +#endif + +#ifndef DEBUGSTR + #if DEBUG + #define DEBUGSTR(str) \ + SafeDebugStr(str) + #else + #define DEBUGSTR(str) + #endif +#endif + +/* + * CapsLockDebugger and CapsLockDebugStr call SafeDebugger and SafeDebugStr + * only if the Caps Lock key is down. + */ + +#define CapsLockDebugger() \ + do \ + { \ + KeyMap theKeys; \ + GetKeys(theKeys); \ + if ( ((theKeys[1] >> 1) & 0x01) != 0 ) \ + { \ + SafeDebugger(); \ + } \ + } while ( false ) + + +#define CapsLockDebugStr(str) \ + do \ + { \ + KeyMap theKeys; \ + GetKeys(theKeys); \ + if ( ((theKeys[1] >> 1) & 0x01) != 0 ) \ + { \ + SafeDebugStr(str); \ + } \ + } while ( false ) + +/* + * ISCAPSLOCKKEYDOWN and ISLOWLEVELDEBUGGERCALLABLE are convenience macros + * which are only defined for non-Carbon builds because they access + * low memory addresses directly. They have been left in this file for + * use by existing non-Carbon code. + * + * ISCAPSLOCKKEYDOWN and ISLOWLEVELDEBUGGERCALLABLE are defined only + * if they are not already defined to prevent conflicts with developer code. + */ + +#if CALL_NOT_IN_CARBON + #ifndef ISCAPSLOCKKEYDOWN + #define ISCAPSLOCKKEYDOWN() \ + ((((UInt16 *)(0x0174))[3] & 0x0002) == 0x0002) + #endif + + #ifndef ISLOWLEVELDEBUGGERCALLABLE + #define ISLOWLEVELDEBUGGERCALLABLE() \ + ( ((*((UInt8 *)0x0BFF)) != (UInt8)0xff) && \ + (((*((UInt8 *)0x0BFF)) & (UInt8)0xe0) == (UInt8)0x60) && \ + ((*((unsigned long *)0x0120)) != 0) && \ + ((*((unsigned long *)0x0120)) != (unsigned long)0xffffffff) ) + #endif +#endif + +/* + * You can use DPRINTF as a dprintf which goes away in production builds. + * DPRINTF is not supported by Carbon because dprintf + * is not supported by Carbon. + * + * To use it, double-parenthesize the argument - i.e., use: + * + * DPRINTF(("formatString %d", 5 )); + * + * This is sadly necessary because a macro can not have a variable number + * of arguments. + * + * DPRINTF is defined only if it is not already defined to + * prevent conflicts with developer code. + */ + +#if DEBUG + #define DPRINTF(x) dprintf x +#else + #define DPRINTF(x) { } +#endif + + +/* + * kBlessedBusErrorBait is an address that will never be mapped by + * Mac OS 8 or 9. It is close to the middle of the 64K range from 0x68F10000 + * to 0x68F1FFFF that is unmapped and cannot be accessed without causing an + * exception. Thus, it's a good value to use for filling uninitialized + * pointers, etc. + * + * Mac OS X programs should NOT use kBlessedBusErrorBait and should use + * zero (0) instead, since by default, page 0 is read and write protected + * for user code. + */ +enum { + kBlessedBusErrorBait = 0x68F168F1 +}; + +/* + * DebugAssert() + * + * Summary: + * DebugAssert is the system routine that the DEBUGASSERTMSG macro + * calls (by default) to display assertion messsages. The output + * from DebugAssert can be redirected by installing a + * DebugAssertOutputHandler with InstallDebugAssertOutputHandler. + * + * Parameters: + * + * componentSignature: + * The unique signature of component causing the assertion. + * + * options: + * reserved. + * + * assertionString: + * A pointer to a string containing the assertion, or NULL. + * + * exceptionLabelString: + * A pointer to a string containing the exceptionLabel, or NULL. + * + * errorString: + * A pointer to the error string, or NULL. + * + * fileName: + * A pointer to the fileName or pathname (generated by the + * preprocessor __FILE__ identifier), or NULL. + * + * lineNumber: + * The line number in the file (generated by the preprocessor + * __LINE__ identifier), or 0 (zero). + * + * value: + * A value associated with the assertion, or NULL. + * + * Availability: + * Non-Carbon CFM: in DebugLib 1.0 and later + * CarbonLib: in CarbonLib 1.0 and later + * Mac OS X: in version 10.0 and later + */ +EXTERN_API( void ) +DebugAssert( + OSType componentSignature, + UInt32 options, + const char * assertionString, + const char * exceptionLabelString, + const char * errorString, + const char * fileName, + long lineNumber, + void * value) TWOWORDINLINE(0x7000, 0xAA7E); + + +/* + * TaskLevel masks + */ +enum { + k68kInterruptLevelMask = 0x00000007, /* 68K interrupt levels 0 through 7 */ + kInVBLTaskMask = 0x00000010, /* VBLs are executing */ + kInDeferredTaskMask = 0x00000020, /* Deferred tasks are executing */ + kInSecondaryIntHandlerMask = 0x00000040, /* Secondary interrupt handlers are executing */ + kInNestedInterruptMask = 0x00000080 /* The system is handling an interrupt */ +}; + +/* + * TaskLevel() + * + * Summary: + * TaskLevel returns 0 if we're (probably) running at non-interrupt + * time. There's no way to make this perfect, but this is as close + * as we can get. If TaskLevel doesn't return 0, then one of the + * TaskLevel masks can be used to learn more. + * + * Result: + * The current task level. + * + * Availability: + * Non-Carbon CFM: in DebugLib 1.0 and later + * CarbonLib: in CarbonLib 1.0 and later + * Mac OS X: in version 10.0 and later + */ +EXTERN_API( UInt32 ) +TaskLevel(void) TWOWORDINLINE(0x7001, 0xAA7E); + + +/* + * Constants used by the DebugComponent functions + */ +enum { + kComponentDebugOption = 0 /* optionSelectorNum to turn breaks for component On or Off*/ +}; + +enum { + kGetDebugOption = 1, /* get current debug option setting*/ + kSetDebugOption = 2 /* set debug option*/ +}; + + +/* + * DebugComponentCallbackProcPtr + * + * Discussion: + * DebugComponentCallback is the callback into a component that + * registers with DebugLib. It is called to get the debug option + * setting, or to turn a debug option on or off. + * + * Parameters: + * + * optionSelectorNum: + * The component debug option to set. + * + * command: + * The command the DebugComponentCallbackProc must handle: + * kGetDebugOption - get current debug option setting + * kSetDebugOption - set debug option + * + * optionSetting: + * A pointer to a Boolean where the DebugComponentCallbackProc + * must return the option setting: the current setting if command + * is kGetDebugOption; the new debug option if command is + * kSetDebugOption + */ +typedef CALLBACK_API( void , DebugComponentCallbackProcPtr )(SInt32 optionSelectorNum, UInt32 command, Boolean *optionSetting); +typedef STACK_UPP_TYPE(DebugComponentCallbackProcPtr) DebugComponentCallbackUPP; +/* + * NewDebugComponent() + * + * Summary: + * NewDebugComponent registers a component with DebugLib. + * + * Parameters: + * + * componentSignature: + * The unique signature of component. + * + * componentName: + * The displayable string naming the component. + * + * componentCallback: + * The callback into component for working with options. + * + * Result: + * An operating system result code: noErr, memFullErr, + * debuggingExecutionContextErr, debuggingDuplicateSignatureErr, or + * debuggingInvalidNameErr. + * + * Availability: + * Non-Carbon CFM: in DebugLib 1.0 and later + * CarbonLib: in CarbonLib 1.0 and later + * Mac OS X: in version 10.0 and later + */ +EXTERN_API( OSStatus ) +NewDebugComponent( + OSType componentSignature, + ConstStr255Param componentName, + DebugComponentCallbackUPP componentCallback) TWOWORDINLINE(0x7002, 0xAA7E); + + +/* + * NewDebugOption() + * + * Summary: + * NewDebugOption registers a debug option with DebugLib. + * + * Parameters: + * + * componentSignature: + * The signature of component to register a debug option for. + * + * optionSelectorNum: + * The selector number of this debug option. + * + * optionName: + * The displayable string naming this debug option. + * + * Result: + * An operating system result code: noErr, memFullErr, + * debuggingExecutionContextErr, debuggingDuplicateOptionErr, + * debuggingInvalidSignatureErr, debuggingInvalidNameErr, or + * debuggingNoCallbackErr. + * + * Availability: + * Non-Carbon CFM: in DebugLib 1.0 and later + * CarbonLib: in CarbonLib 1.0 and later + * Mac OS X: in version 10.0 and later + */ +EXTERN_API( OSStatus ) +NewDebugOption( + OSType componentSignature, + SInt32 optionSelectorNum, + ConstStr255Param optionName) TWOWORDINLINE(0x7003, 0xAA7E); + + +/* + * DisposeDebugComponent() + * + * Summary: + * DisposeDebugComponent removes a component registration and all + * related debug options from DebugLib. + * + * Parameters: + * + * componentSignature: + * The unique signature of a component. + * + * Result: + * An operating system result code: noErr, + * debuggingExecutionContextErr, or debuggingInvalidSignatureErr. + * + * Availability: + * Non-Carbon CFM: in DebugLib 1.0 and later + * CarbonLib: in CarbonLib 1.0 and later + * Mac OS X: in version 10.0 and later + */ +EXTERN_API( OSStatus ) +DisposeDebugComponent(OSType componentSignature) TWOWORDINLINE(0x7004, 0xAA7E); + + +/* + * GetDebugComponentInfo() + * + * Summary: + * GetDebugComponentInfo returns a component registered with + * DebugLib. + * + * Parameters: + * + * index: + * The index into the list of registered components (1-based). + * + * componentSignature: + * A pointer to an OSType where the unique signature of a + * component is returned. + * + * componentName: + * A pointer to an Str255 where the displayable string naming a + * component is returned. + * + * Result: + * An operating system result code: noErr or debuggingNoMatchErr. + * + * Availability: + * Non-Carbon CFM: in DebugLib 1.0 and later + * CarbonLib: in CarbonLib 1.0 and later + * Mac OS X: in version 10.0 and later + */ +EXTERN_API( OSStatus ) +GetDebugComponentInfo( + UInt32 index, + OSType * componentSignature, + Str255 componentName) TWOWORDINLINE(0x7005, 0xAA7E); + + +/* + * GetDebugOptionInfo() + * + * Summary: + * GetDebugOptionInfo returns a debug option registered with + * DebugLib. + * + * Parameters: + * + * index: + * The index into the list of registered debug options (0-based); + * 0 = kComponentDebugOption. + * + * componentSignature: + * The unique signature of a component. + * + * optionSelectorNum: + * A pointer to an SInt32 where the selector number of this debug + * option is returned. + * + * optionName: + * A pointer to an Str255 where the displayable string naming this + * debug option is returned. + * + * optionSetting: + * A pointer to an Boolean where the current debug option setting + * is returned. + * + * Result: + * An operating system result code: noErr, + * debuggingInvalidSignatureErr, or debuggingNoMatchErr. + * + * Availability: + * Non-Carbon CFM: in DebugLib 1.0 and later + * CarbonLib: in CarbonLib 1.0 and later + * Mac OS X: in version 10.0 and later + */ +EXTERN_API( OSStatus ) +GetDebugOptionInfo( + UInt32 index, + OSType componentSignature, + SInt32 * optionSelectorNum, + Str255 optionName, + Boolean * optionSetting) TWOWORDINLINE(0x7006, 0xAA7E); + + +/* + * SetDebugOptionValue() + * + * Summary: + * SetDebugOptionValue sets a debug option registered with DebugLib. + * + * Parameters: + * + * componentSignature: + * The unique signature of a component. + * + * optionSelectorNum: + * The selector number of this debug option. + * + * newOptionSetting: + * The new debug option setting. + * + * Result: + * An operating system result code: noErr, + * debuggingInvalidSignatureErr, or debuggingInvalidOptionErr. + * + * Availability: + * Non-Carbon CFM: in DebugLib 1.0 and later + * CarbonLib: in CarbonLib 1.0 and later + * Mac OS X: in version 10.0 and later + */ +EXTERN_API( OSStatus ) +SetDebugOptionValue( + OSType componentSignature, + SInt32 optionSelectorNum, + Boolean newOptionSetting) TWOWORDINLINE(0x7007, 0xAA7E); + + + +/* + * DebugAssertOutputHandlerProcPtr + * + * Discussion: + * DebugAssertOutputHandler is the callback that registers with + * DebugLib to handle the output from DebugAssert. The + * "componentSignature" through "value" parameters are the raw + * values passed to DebugAssert when an exception occurs. + * + * Parameters: + * + * componentSignature: + * The unique signature of component causing the assertion. + * + * options: + * reserved. + * + * assertionString: + * A pointer to a string containing the assertion, or NULL. + * + * exceptionLabelString: + * A pointer to a string containing the exceptionLabel, or NULL. + * + * errorString: + * A pointer to the error string, or NULL. + * + * fileName: + * A pointer to the fileName or pathname (generated by the + * preprocessor __FILE__ identifier), or NULL. + * + * lineNumber: + * The line number in the file (generated by the preprocessor + * __LINE__ identifier), or 0 (zero). + * + * value: + * A value associated with the assertion, or NULL. + * + * outputMsg: + * The string DebugAssert build which would normally be passed to + * DebugStr if a DebugAssertOutputHandler isn't installed. + */ +typedef CALLBACK_API( void , DebugAssertOutputHandlerProcPtr )(OSType componentSignature, UInt32 options, const char *assertionString, const char *exceptionLabelString, const char *errorString, const char *fileName, long lineNumber, void *value, ConstStr255Param outputMsg); +typedef STACK_UPP_TYPE(DebugAssertOutputHandlerProcPtr) DebugAssertOutputHandlerUPP; +/* + * InstallDebugAssertOutputHandler() + * + * Summary: + * InstallDebugAssertOutputHandler installs a + * DebugAssertOutputHandler which DebugAssert calls instead of + * DebugStr. + * + * Parameters: + * + * handler: + * The DebugAssertOutputHandler to install or NULL to switch back + * to the default handler (DebugStr). + * + * Availability: + * Non-Carbon CFM: in DebugLib 1.0 and later + * CarbonLib: in CarbonLib 1.0 and later + * Mac OS X: in version 10.0 and later + */ +EXTERN_API( void ) +InstallDebugAssertOutputHandler(DebugAssertOutputHandlerUPP handler) TWOWORDINLINE(0x7008, 0xAA7E); + + +#if CALL_NOT_IN_CARBON +/* + * dprintf() + * + * Summary: + * printf takes a variable argument list and 'prints' that to the + * debugging output handler. Calling dprintf() from anything but C + * or C++ is tricky. + * + * Parameters: + * + * format: + * The format string. + * + * ...: + * The arguments to the format string. + * + * Availability: + * Non-Carbon CFM: in DebugLib 1.1 and later + * CarbonLib: not available + * Mac OS X: not available + */ +EXTERN_API_C( void ) +dprintf(const char * format, ...) SIXWORDINLINE(0x2057, 0x43EF, 0x0004, 0x303C, 0x000A, 0xAA7E); + + +/* + * vdprintf() + * + * Summary: + * vdprintf takes a va_args list and 'prints' that to the debugging + * output handler. + * + * Parameters: + * + * format: + * The format string. + * + * va_args_list: + * The va_args list. + * + * Availability: + * Non-Carbon CFM: in DebugLib 1.1 and later + * CarbonLib: not available + * Mac OS X: not available + */ +EXTERN_API( void ) +vdprintf( + const char * format, + char * va_args_list) TWOWORDINLINE(0x7009, 0xAA7E); + + +#endif /* CALL_NOT_IN_CARBON */ + +/* + * NewDebugComponentCallbackUPP() + * + * Availability: + * Non-Carbon CFM: available as macro/inline + * CarbonLib: in CarbonLib 1.0 and later + * Mac OS X: in version 10.0 and later + */ +EXTERN_API_C( DebugComponentCallbackUPP ) +NewDebugComponentCallbackUPP(DebugComponentCallbackProcPtr userRoutine); +#if !OPAQUE_UPP_TYPES + enum { uppDebugComponentCallbackProcInfo = 0x00000FC0 }; /* pascal no_return_value Func(4_bytes, 4_bytes, 4_bytes) */ + #ifdef __cplusplus + inline DEFINE_API_C(DebugComponentCallbackUPP) NewDebugComponentCallbackUPP(DebugComponentCallbackProcPtr userRoutine) { return (DebugComponentCallbackUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppDebugComponentCallbackProcInfo, GetCurrentArchitecture()); } + #else + #define NewDebugComponentCallbackUPP(userRoutine) (DebugComponentCallbackUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppDebugComponentCallbackProcInfo, GetCurrentArchitecture()) + #endif +#endif + +/* + * NewDebugAssertOutputHandlerUPP() + * + * Availability: + * Non-Carbon CFM: available as macro/inline + * CarbonLib: in CarbonLib 1.0 and later + * Mac OS X: in version 10.0 and later + */ +EXTERN_API_C( DebugAssertOutputHandlerUPP ) +NewDebugAssertOutputHandlerUPP(DebugAssertOutputHandlerProcPtr userRoutine); +#if !OPAQUE_UPP_TYPES + enum { uppDebugAssertOutputHandlerProcInfo = 0x00FFFFC0 }; /* pascal no_return_value Func(4_bytes, 4_bytes, 4_bytes, 4_bytes, 4_bytes, 4_bytes, 4_bytes, 4_bytes, 4_bytes) */ + #ifdef __cplusplus + inline DEFINE_API_C(DebugAssertOutputHandlerUPP) NewDebugAssertOutputHandlerUPP(DebugAssertOutputHandlerProcPtr userRoutine) { return (DebugAssertOutputHandlerUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppDebugAssertOutputHandlerProcInfo, GetCurrentArchitecture()); } + #else + #define NewDebugAssertOutputHandlerUPP(userRoutine) (DebugAssertOutputHandlerUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppDebugAssertOutputHandlerProcInfo, GetCurrentArchitecture()) + #endif +#endif + +/* + * DisposeDebugComponentCallbackUPP() + * + * Availability: + * Non-Carbon CFM: available as macro/inline + * CarbonLib: in CarbonLib 1.0 and later + * Mac OS X: in version 10.0 and later + */ +EXTERN_API_C( void ) +DisposeDebugComponentCallbackUPP(DebugComponentCallbackUPP userUPP); +#if !OPAQUE_UPP_TYPES + #ifdef __cplusplus + inline DEFINE_API_C(void) DisposeDebugComponentCallbackUPP(DebugComponentCallbackUPP userUPP) { DisposeRoutineDescriptor((UniversalProcPtr)userUPP); } + #else + #define DisposeDebugComponentCallbackUPP(userUPP) DisposeRoutineDescriptor(userUPP) + #endif +#endif + +/* + * DisposeDebugAssertOutputHandlerUPP() + * + * Availability: + * Non-Carbon CFM: available as macro/inline + * CarbonLib: in CarbonLib 1.0 and later + * Mac OS X: in version 10.0 and later + */ +EXTERN_API_C( void ) +DisposeDebugAssertOutputHandlerUPP(DebugAssertOutputHandlerUPP userUPP); +#if !OPAQUE_UPP_TYPES + #ifdef __cplusplus + inline DEFINE_API_C(void) DisposeDebugAssertOutputHandlerUPP(DebugAssertOutputHandlerUPP userUPP) { DisposeRoutineDescriptor((UniversalProcPtr)userUPP); } + #else + #define DisposeDebugAssertOutputHandlerUPP(userUPP) DisposeRoutineDescriptor(userUPP) + #endif +#endif + +/* + * InvokeDebugComponentCallbackUPP() + * + * Availability: + * Non-Carbon CFM: available as macro/inline + * CarbonLib: in CarbonLib 1.0 and later + * Mac OS X: in version 10.0 and later + */ +EXTERN_API_C( void ) +InvokeDebugComponentCallbackUPP( + SInt32 optionSelectorNum, + UInt32 command, + Boolean * optionSetting, + DebugComponentCallbackUPP userUPP); +#if !OPAQUE_UPP_TYPES + #ifdef __cplusplus + inline DEFINE_API_C(void) InvokeDebugComponentCallbackUPP(SInt32 optionSelectorNum, UInt32 command, Boolean * optionSetting, DebugComponentCallbackUPP userUPP) { CALL_THREE_PARAMETER_UPP(userUPP, uppDebugComponentCallbackProcInfo, optionSelectorNum, command, optionSetting); } + #else + #define InvokeDebugComponentCallbackUPP(optionSelectorNum, command, optionSetting, userUPP) CALL_THREE_PARAMETER_UPP((userUPP), uppDebugComponentCallbackProcInfo, (optionSelectorNum), (command), (optionSetting)) + #endif +#endif + +/* + * InvokeDebugAssertOutputHandlerUPP() + * + * Availability: + * Non-Carbon CFM: available as macro/inline + * CarbonLib: in CarbonLib 1.0 and later + * Mac OS X: in version 10.0 and later + */ +EXTERN_API_C( void ) +InvokeDebugAssertOutputHandlerUPP( + OSType componentSignature, + UInt32 options, + const char * assertionString, + const char * exceptionLabelString, + const char * errorString, + const char * fileName, + long lineNumber, + void * value, + ConstStr255Param outputMsg, + DebugAssertOutputHandlerUPP userUPP); +#if !OPAQUE_UPP_TYPES + #ifdef __cplusplus + inline DEFINE_API_C(void) InvokeDebugAssertOutputHandlerUPP(OSType componentSignature, UInt32 options, const char * assertionString, const char * exceptionLabelString, const char * errorString, const char * fileName, long lineNumber, void * value, ConstStr255Param outputMsg, DebugAssertOutputHandlerUPP userUPP) { CALL_NINE_PARAMETER_UPP(userUPP, uppDebugAssertOutputHandlerProcInfo, componentSignature, options, assertionString, exceptionLabelString, errorString, fileName, lineNumber, value, outputMsg); } + #else + #define InvokeDebugAssertOutputHandlerUPP(componentSignature, options, assertionString, exceptionLabelString, errorString, fileName, lineNumber, value, outputMsg, userUPP) CALL_NINE_PARAMETER_UPP((userUPP), uppDebugAssertOutputHandlerProcInfo, (componentSignature), (options), (assertionString), (exceptionLabelString), (errorString), (fileName), (lineNumber), (value), (outputMsg)) + #endif +#endif + +#if CALL_NOT_IN_CARBON || OLDROUTINENAMES + /* support for pre-Carbon UPP routines: New...Proc and Call...Proc */ + #define NewDebugComponentCallbackProc(userRoutine) NewDebugComponentCallbackUPP(userRoutine) + #define NewDebugAssertOutputHandlerProc(userRoutine) NewDebugAssertOutputHandlerUPP(userRoutine) + #define CallDebugComponentCallbackProc(userRoutine, optionSelectorNum, command, optionSetting) InvokeDebugComponentCallbackUPP(optionSelectorNum, command, optionSetting, userRoutine) + #define CallDebugAssertOutputHandlerProc(userRoutine, componentSignature, options, assertionString, exceptionLabelString, errorString, fileName, lineNumber, value, outputMsg) InvokeDebugAssertOutputHandlerUPP(componentSignature, options, assertionString, exceptionLabelString, errorString, fileName, lineNumber, value, outputMsg, userRoutine) +#endif /* CALL_NOT_IN_CARBON */ + + +#ifdef PRAGMA_IMPORT_OFF +#pragma import off +#elif PRAGMA_IMPORT +#pragma import reset +#endif + +#ifdef __cplusplus +} +#endif + +#endif /* __DEBUGGING__ */ + |