home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 2 / Apprentice-Release2.iso / Source Code / C / Frameworks / Extension Shell 1.3 / Extension Shell 1.3 (Source) / Extension Shell #includes / ParamBlock.h < prev    next >
Encoding:
C/C++ Source or Header  |  1994-04-07  |  7.0 KB  |  206 lines  |  [TEXT/R*ch]
  1. /*    NAME:
  2.         ParamBlock.h
  3.  
  4.     WRITTEN BY:
  5.         Dair Grant
  6.                 
  7.     DESCRIPTION:
  8.         Definition of the ParamBlock that Extension Shell uses for communication
  9.         with your code.
  10.  
  11.     ***************************************************************
  12.     IMPORTANT
  13.     ***************************************************************
  14.         This file is probably *the* most important file for Extension Shell. Read
  15.         it carefully - it defines *exactly* how your ES Handler communicates with
  16.         Extension Shell, and how it describes the code resources it wants
  17.         Extension Shell to load.
  18.  
  19.         Read this file through, and print it out.
  20.         
  21.  
  22.     ___________________________________________________________________________
  23. */
  24. #ifndef __ESPARAMBLOCK__
  25. #define __ESPARAMBLOCK__
  26. //=============================================================================
  27. //        Include files                                                                     
  28. //-----------------------------------------------------------------------------
  29. #include <Retrace.h>
  30. #include <Shutdown.h>
  31. #include "ESConstants.h"
  32.  
  33.  
  34.  
  35.  
  36.  
  37. //=============================================================================
  38. //        Structures                                                                 
  39. //-----------------------------------------------------------------------------
  40. // Six types of code resources are supported right now. Defines to pick them out
  41. // of the union are defined here, with their structures.
  42. #define kTrapPatchType                1                        // A Trap Patch
  43. #define kGestaltSelectorType        2                        // A Gestalt Selector
  44. #define kShutdownTaskType            3                        // A Shutdown Task
  45. #define kVBLTaskType                4                        // A VBL Task
  46. #define kLowMemFilterType            5                        // A low-mem filter
  47. #define kCodeBlockType                6                        // A block of code
  48. #define kTimeManagerTaskType        7                        // A Time Manager Task
  49.  
  50.  
  51.  
  52.  
  53. // TrapPatch information. Trap Patches need to hold the number of the
  54. // trap to patch. Your ES Handler is responsible for ensuring that the
  55. // trap is implemented. If you're patching something really new, you
  56. // need to be aware of this. The IsTrapAvailable routine is provided
  57. // for you to test for the presence of a trap.
  58. typedef struct {
  59.     int                trapNum;
  60. } ATrapPatch;
  61.  
  62.  
  63.  
  64. // Gestalt selectors may want to override existing selectors. Then again,
  65. // they may not - set the OverwriteExistingSelector field accordingly.
  66. // theSelector is the Gestalt type for the selector.
  67. typedef struct {
  68.     OSType            theSelector;
  69.     Boolean            overwriteExistingSelector;
  70. } AGestaltSelector;
  71.  
  72.  
  73.  
  74. // Shutdown tasks can pass in some flags - defined in Shutdown.h
  75. typedef struct {
  76.     short            theFlags;
  77. } AShutdownTask;
  78.  
  79.  
  80.  
  81. // Information for a VBL task.
  82. typedef struct {
  83.     short            vblCount;
  84.     short            vblPhase;
  85. } AVBLTask;
  86.  
  87.  
  88.  
  89. // Information for a low-mem filter. We need to hold the address of the
  90. // filter to hook ourselves into.
  91. typedef struct {
  92.     long            theEntryPoint;
  93. } ALowMemFilter;
  94.  
  95.  
  96.  
  97. // Information for a block of code. We don't actually need anything,
  98. // but we can't compile it without allocating some members.
  99. typedef struct {
  100.     short            reserved;
  101. } ACodeBlock;
  102.  
  103.  
  104.  
  105. // Information for a Time Manager task. We need to hold the time (in
  106. // milliseconds) before the task is first executed.
  107. typedef struct {
  108.     long            theDelay;
  109. } ATimeManagerTask;
  110.  
  111.  
  112.  
  113.  
  114. // Each installable 'thing' is specified via a CodeInfo structure. This holds
  115. // the resource type and id of the code resource (e.g. 'CODE', and 1000),
  116. // as well as a CodeType field. To save space, the code-specific details are
  117. // merged in a union type, with the CodeType field being used to specify the
  118. // contents of TheCodeThing. TheAddress is an internal Extension Shell field,
  119. // used to hold the address of the thing installed/the thing it replaced.
  120. // This field is reserved for use by Extension Shell.
  121. typedef struct {
  122.     OSType            resType;                                    // Resource type of thing
  123.     int                resID;                                        // Resource ID of thing
  124.     int                codeType;                                    // Type of this thing
  125.     union            {
  126.                     ATrapPatch            theTrapPatch;
  127.                     AGestaltSelector    theGestaltSelector;
  128.                     AShutdownTask        theShutdownTask;
  129.                     AVBLTask            theVBLTask;
  130.                     ALowMemFilter        theLowMemFilter;
  131.                     ACodeBlock            theCodeBlock;
  132.                     ATimeManagerTask    theTimeManagerTask;
  133.                     } theCodeThing;                                // Specific details for this thing
  134.     Ptr                theAddress;                                    // RESERVED for Extension Shell
  135. } CodeInfo;
  136.  
  137.  
  138.  
  139.  
  140. // The ParamBlock. All communication between your code and Extension Shell is done
  141. // through a pointer to one of these structures. Relevent sections are grouped
  142. // together.
  143. typedef struct {
  144.     // General variables. The System Version holds 7.0.0 as 0x0700, 7.0.1 as 0x0701,
  145.     // etc. IsTrapAvailable is provided so that you can test for the presence of
  146.     // traps before attempting to patch them out. UserForcedDisable returns true if
  147.     // the key corresponding to KeyCode (0x38 for Shift, etc) is pressed. If CheckMouse
  148.     // is true, it will also return true if the mouse button is being held down.
  149.     long            systemVersion;
  150.     pascal Boolean    (*IsTrapAvailable)(int trapNum);
  151.     pascal Boolean    (*UserForcedDisable)(short keyCode, Boolean checkMouse);
  152.     
  153.     
  154.     
  155.     // NumIcons contains the amount of valid entries in TheIcons. Set it to 0 if
  156.     // there are no icons, and a value from 1..kMaxNumIcons otherwise. The value
  157.     // in the array corresponds to the resource ID of an Icon Family ('ICN#',
  158.     // 'icl8', and 'icl4'). If the icon can't be found, it won't be plotted.
  159.     // AnimationDelay is the number of Ticks to delay between showing each
  160.     // icon. If you are only showing one icon, set this to 0. By default,
  161.     // Extension Shell initialises NumIcons to 0 and AnimationDelay to 3.
  162.     int                numIcons;
  163.     int                animationDelay;
  164.     int                theIcons[kMaxNumIcons+1];
  165.     
  166.     
  167.     
  168.     // The code that is to be installed is described in TheCodeResources.
  169.     // NumCodeResources contains the amount of valid entries in TheCodeResources,
  170.     // as in NumIcons and TheIcons[]. If an AddressTable is to be installed, set
  171.     // InstallAddressTable to true, and provide the desired Gestalt Selector
  172.     // in AddressTableSelector. In the event of an error, ErrorIndex will contain
  173.     // the entry in TheCodeResources that could not be installed. TheErr will be
  174.     // set to the reason why. By default, Extension Shell initialises
  175.     // numCodeResources to 0.
  176.     Boolean            installAddressTable;
  177.     OSType            addressTableSelector;
  178.     int                numCodeResources;
  179.     CodeInfo        theCodeResources[kMaxNumCodeResources+1];
  180.     int                errorIndex;
  181.     OSErr            theErr;
  182.     
  183.     
  184.     
  185.     // In the event of an error, these variables are used to handle things. If
  186.     // RemoveInstalledCode is set to true, ExtensionShell will attempt to uninstall
  187.     // the code it has already installed. No gaurantee is made that all, if any,
  188.     // of your code will be removed.
  189.     //
  190.     // Setting BeepNow to true will cause ExtensionShell to call SysBeep(30).
  191.     // If PostError is true, a Notification Manager note will be posted.
  192.     // ErrorStringsID  should be set to the id of the 'STR#' resource containing
  193.     // your error strings, and ErrorStringIndex the specific string within this
  194.     // 'STR#' that is to be displayed. The user will get to see the message when
  195.     // the Finder starts handling events.
  196.     Boolean            removeInstalledCode;
  197.     Boolean            beepNow;
  198.     Boolean            postError;
  199.     int                errorStringsID;
  200.     int                errorStringIndex;
  201.     
  202. } ESParamBlock;
  203.  
  204.  
  205. #endif
  206.