home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS - Coast to Coast / simteldosarchivecoasttocoast2.iso / cpluspls / tsr100je.zip / TSR.H < prev    next >
C/C++ Source or Header  |  1993-03-22  |  12KB  |  230 lines
  1. //--------------------------------------------------------------------------
  2. //
  3. //      TSR.H: header file for DOS TSR class.
  4. //      Copyright (c) J.English 1993.
  5. //      Author's address: je@unix.brighton.ac.uk
  6. //
  7. //      Permission is granted to use copy and distribute the
  8. //      information contained in this file provided that this
  9. //      copyright notice is retained intact and that any software
  10. //      or other document incorporating this file or parts thereof
  11. //      makes the source code for the TSR class of which this file
  12. //      is a part freely available.
  13. //
  14. //--------------------------------------------------------------------------
  15. //
  16. //      Note: this class is highly DOS specific and hence non-portable.
  17. //      It also involves the use of assembly language and interrupt
  18. //      functions, so it is also very compiler-specific and will need
  19. //      modification for use with compilers other than Borland C++ 3.0
  20. //      or later.
  21. //
  22. //      Revision history:
  23. //      1.0     March 1993      Initial coding
  24. //
  25. //--------------------------------------------------------------------------
  26.  
  27. #ifndef __TSR_H
  28. #define __TSR_H
  29.  
  30. //--------------------------------------------------------------------------
  31. //
  32. //      Class TSR: abstract base class for DOS resident programs.
  33. //      ---------------------------------------------------------
  34. //
  35. //      TSRs written using this class will require a PC/AT compatible
  36. //      machine running DOS version 3 or higher.  See the file TSR.DOC
  37. //      for detailed documentation.
  38. //
  39. //      Public interface:
  40. //      -----------------
  41. //      TSR (const char* name,
  42. //           unsigned stacksize = 1024);
  43. //                      -- Class constructor.  "Name" is a unique name
  44. //                         for the TSR instance, and "stacksize" is the
  45. //                         number of bytes of stack space to allocate.
  46. //      virtual ~TSR ();
  47. //                      -- Class destructor.  This is only invoked when
  48. //                         the TSR is NOT made resident.
  49. //      void run (int hotkey,
  50. //                unsigned timeslice = 0);
  51. //                      -- Make the TSR resident.  "Hotkey" is the hotkey
  52. //                         to be used to wake up the TSR and "timeslice"
  53. //                         is the number of timer ticks between timed
  54. //                         activations.  Use value from the enumeration
  55. //                         TSR::hotkey_code to specify the hotkey value.
  56. //                         A timeslice of 0 means that timeslicing is not
  57. //                         required.  This function only returns if there
  58. //                         is an error preventing the TSR from loading.
  59. //      int unload ();
  60. //                      -- Unload a previously-loaded copy of the TSR from
  61. //                         memory.  Returns zero if the TSR is successfully
  62. //                         unloaded, or a non-zero error code if it could
  63. //                         not be unloaded.
  64. //      int loaded ();
  65. //                      -- Returns non-zero if a copy of the TSR has already
  66. //                         been loaded.
  67. //      int request (int& fn, int& p1, int& p2);
  68. //                      -- This function allows a foreground copy of the
  69. //                         program to communicate with a resident copy.
  70. //                         "Fn" is an application-specific function code
  71. //                         (00 - 7F) and "p1" and "p2" are function-specific
  72. //                         parameters.  Returns zero if there is no resident
  73. //                         copy of the TSR; otherwise the virtual function
  74. //                         "respond" will be called in the resident copy to
  75. //                         process the function.  "Respond" can update the
  76. //                         values of the three parameters to return a result
  77. //                         to the foreground program.
  78. //      const char* name ();
  79. //                      -- Returns the TSR's identifying string.
  80. //      int status ();
  81. //                      -- Returns a status code showing if any errors have
  82. //                         occurred during TSR construction or loading (as
  83. //                         defined by the enumeration type TSR::status_code).
  84. //
  85. //      Protected interface:
  86. //      --------------------
  87. //      virtual void main (int hotkey) = 0;
  88. //                      -- The main body of the TSR, executed whenever it
  89. //                         is woken up.  "Hotkey" will be non-zero if the
  90. //                         TSR was woken up by the hotkey, and zero if it
  91. //                         was woken up by a timeslice interrupt.  This is
  92. //                         a pure virtual function and must be defined by
  93. //                         all derived TSR classes.
  94. //
  95. //      Functions for use by "main".
  96. //      ----------------------------
  97. //      void pause ();
  98. //                      -- allow other TSRs to run if lengthy processing
  99. //                         is being performed by "main".
  100. //      void sync ();
  101. //                      -- resynchronise the timer.  Timeslice interrupts
  102. //                         occur every N timer ticks after "run" is executed.
  103. //                         This function resets the clock so that the next
  104. //                         interrupt will occur N timer ticks from the time
  105. //                         it is called.
  106. //      int userbreak ();
  107. //                      -- returns non-zero if Ctrl-Break has been pressed
  108. //                         since the last time this function was called.
  109. //
  110. //      Virtual functions:
  111. //      ------------------
  112. //      (Note: these functions should not be called directly; they will be
  113. //       called automatically when necessary.)
  114. //
  115. //      virtual int startup ();
  116. //                      -- Performs initialisation (like a constructor) when
  117. //                         the TSR is being made resident.  Returns non-zero
  118. //                         if an error occurs.
  119. //      virtual int shutdown ();
  120. //                      -- Performs finalisation (like a destructor) when
  121. //                         the TSR is being unloaded from memory.  Returns
  122. //                         non-zero if an error occurs.
  123. //      virtual int respond (int fn, int& p1, int& p2);
  124. //                      -- Respond to a call to "request" in a foreground
  125. //                         copy of the program.  "Fn" is a function code
  126. //                         between 00 and 7F, and "p1" and "p2" are function
  127. //                         specific parameters.  The return value will be
  128. //                         stored in the caller's function code (the first
  129. //                         parameter to "request") and any changes to "p1"
  130. //                         or "p2" will be reflected in the corresponding
  131. //                         parameters of the foreground program's call to
  132. //                         "request".
  133. //      virtual critical_code critical_error (int n);
  134. //                      -- Called when a critical errors occurs during
  135. //                         execution of "main".  "N" is the critical error
  136. //                         code; the result is a value from the enumeration
  137. //                         TSR::critical_code (indicating how DOS should
  138. //                         proceed).
  139. //      virtual void dos_error (int fn, int ce, int cs, int ip);
  140. //                      -- Called if an invalid DOS function is called by
  141. //                         "main" or "critical_error".  The default action
  142. //                         is to clear the screen and print an error message.
  143. //                         Parameter "fn" is the function code from register
  144. //                         AH; "ce" is non-zero if the error occurred while
  145. //                         handling a critical error; "cs" and "ip" are the
  146. //                         segment and offset of the return address from the
  147. //                         offending interrupt.  Do not attempt to use any
  148. //                         DOS services from within this function!
  149. //
  150. //--------------------------------------------------------------------------
  151.  
  152.  
  153.  
  154. class TSR
  155. {
  156.     friend void activate ();
  157.  
  158.   public:
  159.     enum hotkey_code {
  160.         NONE   = 0x0000,
  161.         ALT    = 0x0800,  CTRL   = 0x0400,  LSHIFT = 0x0200,  RSHIFT = 0x0100,
  162.         KEY_A  = 0x001E,  KEY_B  = 0x0030,  KEY_C  = 0x002E,  KEY_D  = 0x0020,
  163.         KEY_E  = 0x0012,  KEY_F  = 0x0021,  KEY_G  = 0x0022,  KEY_H  = 0x0023,
  164.         KEY_I  = 0x0017,  KEY_J  = 0x0024,  KEY_K  = 0x0025,  KEY_L  = 0x0026,
  165.         KEY_M  = 0x0032,  KEY_N  = 0x0031,  KEY_O  = 0x0018,  KEY_P  = 0x0019,
  166.         KEY_Q  = 0x0010,  KEY_R  = 0x0013,  KEY_S  = 0x001F,  KEY_T  = 0x0014,
  167.         KEY_U  = 0x0016,  KEY_V  = 0x002F,  KEY_W  = 0x0011,  KEY_X  = 0x002D,
  168.         KEY_Y  = 0x0015,  KEY_Z  = 0x002C,  KEY_0  = 0x0078,  KEY_1  = 0x0079,
  169.         KEY_2  = 0x007A,  KEY_3  = 0x007B,  KEY_4  = 0x007C,  KEY_5  = 0x007D,
  170.         KEY_6  = 0x007E,  KEY_7  = 0x007F,  KEY_8  = 0x0080,  KEY_9  = 0x0081,
  171.         F1     = 0x003B,  F2     = 0x003C,  F3     = 0x003D,  F4     = 0x003E,
  172.         F5     = 0x003F,  F6     = 0x0040,  F7     = 0x0041,  F8     = 0x0042,
  173.         F9     = 0x0043,  F10    = 0x0044,  SPACE  = 0x0039,  ENTER  = 0x001C
  174.     };
  175.     enum status_code {
  176.         SUCCESS     = 0,                                        // general
  177.         DOS_VERSION = 1,  MULTI_COPIES = 2,  STACK_FAIL = 3,    // run/c'tor
  178.         NO_MUX_FUNC = 4,  RELOAD_FAIL  = 5,  LOAD_FAIL  = 6,
  179.         STARTUP_ERR = 7,
  180.         NOT_LOADED  = 1,  UNHOOK_FAIL  = 2,  MEM_FROZEN = 3,    // unload
  181.         ENV_FROZEN  = 4
  182.     };
  183.     enum critical_code { IGNORE = 0, RETRY = 1, FAIL = 3 };
  184.  
  185.     TSR (const char* name,                  // TSR identifier
  186.          unsigned stacksize = 1024);        // stack size in bytes
  187.     virtual ~TSR ();
  188.  
  189.     void run (int hotkey,                   // hotkey used to wake up TSR
  190.               unsigned timeslice = 0);      // length of timeslice in ticks
  191.     int unload ();                          // unload TSR from memory
  192.     int loaded ();                          // is TSR already loaded?
  193.     const char* name ();                    // get TSR identifier
  194.     int status ();                          // current TSR status
  195.  
  196.     virtual int startup ();                 // TSR startup code
  197.     virtual int shutdown ();                // TSR shutdown code
  198.     int request (int&, int&, int&);         // request to TSR resident copy
  199.     virtual int respond (int, int far&, int far&);
  200.                                             // response from TSR resident copy
  201.     virtual critical_code critical_error (int n);
  202.                                             // critical error handler
  203.     virtual void dos_error (int fn, int ce, int cs, int ip);
  204.                                             // DOS error handler
  205.  
  206.   protected:
  207.     void pause ();                          // let other TSRs run
  208.     void sync ();                           // resychronise timer
  209.     int userbreak ();                       // has ctrl-break been pressed?
  210.     virtual void main (int hotkey) = 0;     // main body of TSR, called when
  211.                                             // hotkey pressed or timesliced
  212.   private:
  213.     int stat;
  214. };
  215.  
  216.  
  217.  
  218. //--------------------------------------------------------------------------
  219. //
  220. //      Inline functions
  221. //
  222. inline TSR::~TSR ()                                     { }
  223. inline int TSR::startup  ()                             { return 0; }
  224. inline int TSR::shutdown ()                             { return 0; }
  225. inline int TSR::status   ()                             { return stat; }
  226. inline int TSR::respond (int, int far&, int far&)       { return 0; }
  227. inline TSR::critical_code TSR::critical_error (int n)   { return TSR::FAIL; }
  228.  
  229. #endif
  230.