home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Mac Game Programming Gurus / TricksOfTheMacGameProgrammingGurus.iso / Demos / Tools / QC™ 1.1.3 / QCAPI / CLibraries / QCAPI.h
Encoding:
C/C++ Source or Header  |  1995-04-23  |  9.3 KB  |  228 lines  |  [TEXT/R*ch]
  1. /*________________________________________________________________________________
  2.     QCAPI.h
  3.     
  4.     Application Programmer Interface (API) to QC™ development tool.
  5.     
  6.     Copyright 1993-1995 Onyx Technology. All rights reserved worldwide.
  7.     
  8.     revis:    06/04/93    dth - Date created
  9.             02/10/95    dth - Added 'testTrapPC' to QCPBRec.
  10.                             - Added PPC mixed mode for QCInstallHandler().
  11.  
  12. ________________________________________________________________________________*/
  13.  
  14. #ifndef    _H_QCAPI
  15. #define    _H_QCAPI
  16.  
  17. #ifndef    THINK_C
  18.     #ifndef    __TYPES__
  19.     #include <Types.h>
  20.     #endif
  21.     #ifndef    __MEMORY__
  22.     #include <Memory.h>
  23.     #endif
  24.     #ifndef    __OSUTILS__
  25.     #include <OSUtils.h>
  26.     #endif
  27. #endif    //THINK_C
  28.  
  29. typedef long    QCErr;                            // QC error code type
  30. typedef    long    QCType;                            // QC type codes
  31. typedef    Handle    QCStateHandle;                    // QC save/restore state data
  32.  
  33. //    Parameter block for custom error handler
  34. struct QCPBRec {
  35.     QCType        testID;                            // the selector id of the test
  36.     QCErr        error;                            // error detected (see below)
  37.     long        data;                            // data/address from QCInstallHandler()
  38.     char        *errString;                        // error string being reported
  39.     long        lastTestedTrapPC;                // PC of last trap QC detected error at
  40.     long        lastTrapPC;                        // PC of last trap executed from user code
  41. };
  42. typedef struct QCPBRec QCPBRec;
  43. typedef    QCPBRec *QCPBPtr;
  44.  
  45. // Test list handle returned by QCGetTestList(). Delete with DisposeHandle().
  46. struct QCTestRec {
  47.     QCType        testID;
  48.     Str32        testName;
  49. };
  50. typedef struct QCTestRec QCTestRec;
  51. typedef QCTestRec *QCTestPtr, **QCTestHandle;
  52.  
  53. // Specific test option structs for use in QCGetTestOptions()/QCSetTestOptions
  54. struct QCAutoLaunchRec {
  55.     short        which;                            // 1 = _InitGraf; 2 = _Get1Resource;
  56.     short        id;                                // id for useGet1Resource
  57.     OSType        type;                            // type for useGet1Resource
  58. };
  59. typedef    struct QCAutoLaunchRec QCAutoLaunchRec;
  60.  
  61. struct QCReasonAllocRec {
  62.     short        which;                            // 1 = use app heap; 2 = use specified
  63.     long        size;                            // alloc size to break on >=
  64. };
  65. typedef    struct QCReasonAllocRec QCReasonAllocRec;
  66.  
  67. struct QCBlockBoundsRec {
  68.     short        tagSize;                        // block bounds size to tag blocks with
  69. };
  70. typedef    struct QCBlockBoundsRec QCBlockBoundsRec;
  71.  
  72. union QCOptionData {
  73.     QCAutoLaunchRec        autoLaunch;                // AutoLaunch information
  74.     QCReasonAllocRec    reasonableAlloc;        // Reasonable Allocation information
  75.     QCBlockBoundsRec    blockBounds;            // BlockBounds information
  76. };
  77. typedef    union QCOptionData QCOptionData;
  78.  
  79. struct    QCTestOptions {
  80.     QCType            testID;                        // the test this data belongs to
  81.     QCOptionData    optionData;                    // union specific data belongs here
  82. };
  83. typedef    struct QCTestOptions QCTestOptions;
  84. typedef    QCTestOptions *QCTestOptionsPtr;
  85.  
  86. enum {
  87.     //    API result codes
  88.     kQCNoErr            = 0,
  89.     kQCInternalErr        = 9,
  90.     kQCNotInstalled,                    // QC extension not installed
  91.     kQCNotActive,                        // QC is not testing; must be to complete
  92.     kQCInvalidParam,                    // invalid parameter passed to routine
  93.     kQCInvalidType,                        // invalid QCType given to a routine
  94.     kQCPBRecMismatch,                    // QCPBRec size mismatch.  QCAPI library in use
  95.                                         //    does not match API loaded extension needs.
  96.     kQCAPIMismatch,                        // The QCAPI and loaded extension API's don't match!
  97.     kQCErrHandlerNotFound,                // QCRemoveHandler result when given proc was not
  98.                                         //    installed.
  99.  
  100.     // API error detection result codes (given to DebugCallback routine (if installed)
  101.     kErrorBase    = 300,                    // base index of all errors
  102.     kBadBlockLenErr,                    // invalid physical block length
  103.     kBadRelHandErr,                        // Offset from zone start to masterPtr invalid
  104.     kLostMasterPtrErr,                    // master pointer is not in the heap
  105.     kBadMasterPtrErr,                    // MasterPtr does not point to data
  106.     kBadNonRelocErr,                    // Bad Non-reloc block: heap addr must follow physSize.
  107.     kBadBlockTypeErr,                    // invalid block type (not reloc, non-reloc, or free)
  108.     kBadLastBlockErr,                    // invalid physical block length (last block)
  109.     kWriteToZeroErr,                    // write to location zero detected
  110.     kNilHandleErr,                        // nil handle error
  111.     /*    10    */
  112.     kHandleInFreeErr,                    // handle is in a free block
  113.     kBadHandleErr,                        // handle is bad - not at start of relocatable block
  114.     kBadPtrErr,                            // Ptr does not point to non-relocatable block
  115.     kNilPointerErr,                        // nil pointer detected
  116.     kUnused,
  117.     kHeapStartEndErr,                    // bkLim of heap has heap end before it starts
  118.     kFreeByteHeapErr,                    // no. of free bytes exceeds heap size
  119.     kGrowZoneMismatchErr,                // grow zone function mistmatch!
  120.     kUnreasonableNewHandleErr,            // new handle size is questionable
  121.     kUnreasonableNewPtrErr,
  122.     /*    20    */
  123.     kUnreasonableSetHandleSizeErr,
  124.     kUnreasonableReallocHandleErr,
  125.     kUnreasonableSetPtrSizeErr,
  126.     kReleaseHandleErr,                    // called release resource on a handle
  127.     kDisposResourceErr,                    // Trying to perform a DisposHandle on a resource
  128.     kBlockMoveDestFree,                    // Destination ptr for BlockMove is in a free block
  129.     kBlockMoveDestMultiple,                // Destination ptr for BlockMove spans multiple blocks
  130.     kBlockMoveHeadOverwrite,            // Blockmove will overwrite a block header
  131.     kBlockMovePadOverwrite,                // Blockmove will overwrite padding in a block
  132.     /*    30    */
  133.     kUnreasonableBlockMoveSize,            // Blockmove attempting to move an unreasonable size
  134.     kMemErrDetected,                    // a MemErr value has been detected after a call
  135.     kEmptyHandleErr,                    // Empty handle used by routine that needs data
  136.     kPtrBoundsErr,                        // Write past end of non-relocatable block detected
  137.     kHandleBoundsErr,                    // Write past end of relocatable block detected
  138.     kFreeMemOverwrite,                    // Write has been made to a free block
  139.     kGrowLock,                            // App is growing a locked block
  140.     kGrowPtr,                            // App is growing a non-relocatable block
  141.     kBlockMoveNilSrc,                    // source pointer is NIL!
  142.     kBlockMoveNilDest,                    // destination pointer is NIL!
  143.     kErrorLimit                            // max error id place holder
  144. };
  145.  
  146. //    The following constants are valid QCType selectors:
  147.  
  148.     #define    qcAutoLaunch                'auto'            // auto launch this app/file
  149.     #define    qcCheckSystemHeap            'cksh'            // check system heap
  150.     #define    qcValidateMasterPointers    'vlmp'            // validate master pointers
  151.     #define    qcValidateHandlePointers    'vlhp'            // validate handles/pointers
  152.     #define    qcDetectWriteToZero            'dtwz'            // detect write to zero
  153.     #define    qcDerefZeroCheck            'drzc'            // detect deref zero
  154.     #define    qcReasonableAllocation        'rall'            // reasonable allocation checks
  155.     #define    qcCheckDisposeRelease        'dprl'            // check DisposeHandle/ReleaseResource
  156.     #define    qcScrambleHeap                'schp'            // scramble heap
  157.     #define    qcPurgeHeap                    'pghp'            // purge heap
  158.     #define    qcCheckHeap                    'ckhp'            // check heap
  159.     #define    qcInvalidateFreeMemory        'infm'            // trample (invalidate) free memory
  160.     #define    qcCheckSystemCode            'csys'            // check system code
  161.     #define    qcErrorReporting            'erpt'            // error reporting
  162.     #define    qcDebugBreaks                'dbrk'            // debugger breaks
  163.     #define    qcBeepNotify                'beep'            // beep on activate/deactivate
  164.     #define    qcIconNotify                'sicn'            // rotate small icon when active
  165.     #define qcBlockMoveChecking            'bkmv'            // check BlockMove calls
  166.     #define qcBlockBoundsChecking        'bbck'            // block bounds checking
  167.     #define    qcMemErrDetection            'merr'            // MemErr value checking
  168.     #define    qcGrowLockChecking            'grlk'            // grow locked block checking
  169.     #define    qcGrowNonRelocChecking        'gron'            // grow non-reloc block checking
  170.  
  171.     #define    qcAllTestsMask                'mask'            // all tests mask (activate/deactivate all)
  172.  
  173. //    PowerPC mixed mode support
  174. enum {
  175.     uppQCCallBackProcInfo = kCStackBased
  176.         | RESULT_SIZE(SIZE_CODE(sizeof(long)))
  177.         | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(QCPBPtr)))
  178. };
  179.  
  180. // QCCallBack routine descriptors
  181. #if GENERATINGCFM
  182. typedef UniversalProcPtr QCCallBackUPP;
  183. #define NewQCCallBackProc(userRoutine)        \
  184.         (QCCallBackUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppQCCallBackProcInfo, GetCurrentISA())
  185. #else
  186. typedef    ProcPtr    QCCallBackUPP;
  187. #define    NewQCCallBackProc(userRoutine)        \
  188.         ((QCCallBackUPP) (userRoutine))
  189. #endif
  190.  
  191. #ifdef __cplusplus
  192. extern "C" {
  193. #endif
  194. //    API Routines
  195.  
  196. QCErr        QCInstalled(void);                            // is QC extension loaded and usable?
  197. Boolean        QCIsActive(void);                            // is QC currently testing an application?
  198. QCErr        QCActivate(THz);                            // activate QC on a specific heap zone
  199.                                                         //    or current heap if 0L is specified
  200. QCErr        QCDeActivate(void);                            // deactivate QC testing
  201. THz            QCTestingHeap(void);                        // get the heap being tested
  202.  
  203. QCStateHandle     QCGetState(void);                        // get the current testing state
  204. QCErr        QCSetState(QCStateHandle);                    // restore the current testing state
  205. QCErr        QCDisposeState(QCStateHandle);                // dispose of state handle
  206. QCErr        QCGetTestState(QCType, long *);                // get state of a particular test
  207. QCErr        QCSetTestState(QCType, long);                // set state of a particular test
  208. QCErr         QCGetTestOptions(QCTestOptionsPtr);            // get specific test options
  209. QCErr         QCSetTestOptions(QCTestOptionsPtr);            // set specific test options
  210.  
  211. QCErr        QCInstallHandler(QCCallBackUPP, long);        // install a error handler routine
  212. QCErr        QCRemoveHandler(QCCallBackUPP);                // remove an error handler routine
  213. QCErr        QCGetErrorText(QCErr, StringPtr);            // get error text for a particular error
  214.  
  215. QCErr        QCHeapCheckNow(void);                        // check the active heap now
  216. QCErr        QCScrambleHeapNow(void);                    // scramble the active heap now
  217. QCErr        QCBlockBoundsCheckNow(void);                // perform a block bounds check now
  218. QCErr        QCVerifyHandle(Handle);                        // verify the given handle
  219. QCErr        QCVerifyPtr(Ptr);                            // verify the given pointer
  220.  
  221. QCTestHandle    QCGetTestList(long *);                    // Get a list of install/available tests
  222.                                                         //    return # of tests in long*
  223. #ifdef __cplusplus
  224. }
  225. #endif
  226.  
  227. #endif    // _H_QCAPI
  228.