home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 9 / FreshFishVol9-CD2.bin / bbs / util / snoopdos-3.0.lha / SnoopDos / Source / SnoopDos.Roadmap < prev    next >
Text File  |  1994-09-17  |  18KB  |  385 lines
  1.  
  2.                         SnoopDos 3.0 -- Source Code Roadmap
  3.  
  4.            Copyright © Eddy Carroll, September 1994. Freely distributable.
  5.  
  6.  
  7. INTRODUCTION
  8.  
  9.     SnoopDos was written using SAS/C 6.51. The Amiga programming community
  10.     owe a large debt of thanks to Doug Walker, Steve Krueger, Jim Cooper,
  11.     and everyone else at SAS Institute for providing such a useful and
  12.     stable development environment. Without SAS/C, development of SnoopDos
  13.     would have taken significantly longer.
  14.  
  15.     If you have SAS/C, then you should be able to recompile SnoopDos with
  16.     no problems by simply typing "smake" in this directory. You might want
  17.     to turn off optimisation in the SCOPTIONS file if you are experimenting;
  18.     otherwise, prepare for a long wait.
  19.  
  20.     If you are using DICE or another compiler, you will need to ensure that
  21.     you are using similar compiler options to those listed in SCOPTIONS. You
  22.     will also need to change the function prototypes in patches.h and perhaps
  23.     in patches.c. A future release may detect DICE automatically and do the
  24.     right thing.
  25.  
  26.     In general, most files have an initialisation function and all have a
  27.     cleanup function. The initialisation function should be called at the
  28.     beginning of the code and the cleanup function at the end. All cleanup
  29.     functions are safe to call multiple times if necessary.
  30.  
  31.     Note that all the source code has been formatted with a tab setting of
  32.     4 spaces. If your editor uses tabs set to some other width, then it is
  33.     strongly recommended that you run the code through Detab or a similar
  34.     utility, otherwise it will look a mess.
  35.  
  36.  
  37. MODULE OVERVIEW
  38. ---------------
  39. Here's a summary of the different files and what they are used for:
  40.  
  41.        system.h   Master include file for all system headers
  42.        system.c   Includes system.h -- used to create the GST file
  43.      snoopdos.h   Defines all program globals, structures, constants, protos
  44.      snoopdos.c   Top level module. Initialises and cleans up other modules
  45.        buffer.c   Allocates and formats events in the event buffer
  46.      language.c   Makes localised text strings available to other modules
  47.     snooptext.h   Master message include file used by all modules
  48.       patches.c   All the patch code inserted into system libraries
  49.       patches.h   Header file that prototypes all the patched functions
  50.     patchcode.s   Low-level assembly code used by patch mechanism
  51.      settings.c   Handles the command line interface to SnoopDos
  52.           gui.h   Constants which define the exact appearance of the GUI
  53.       mainwin.c   All functions relating to the main window
  54.        subwin.c   All functions relating to the other three windows
  55.       miscwin.c   Miscellaneous window and screen functions used everywhere
  56.        hotkey.c   Handles commodity interface + Workbench AppIcon/Toolmenu
  57.          icon.h   Image data for custom SnoopDos icon (from IconEdit)
  58.     snooptext.cd  SnoopDos catalog description file, for localisation
  59.     snooptext.ct  Example SnoopDos translation file, for localisation
  60.     testcalls.c   Separate utility to stress test the SnoopDos patch code.
  61.  
  62.  
  63. MODULE GUIDE
  64. ------------
  65. Here's a more detailed look at the contents of each module. See the module
  66. itself for full details.
  67.  
  68.  
  69. SYSTEM.H
  70. SYSTEM.C
  71.  
  72.     System.h is the master include file for all Amiga system includes. Any
  73.     system include used by any module is placed in here. The entire set of
  74.     includes is then precompiled into a SAS/C GST file, which greatly speeds
  75.     up compilation.
  76.  
  77.     System.c is the file used to generate the GST -- it simply includes
  78.     the System.h header file.
  79.  
  80.  
  81. SNOOPDOS.H
  82.  
  83.     SnoopDos.h is included by all other modules. It defines all the global
  84.     variables, structures, and prototypes used by SnoopDos. It also includes
  85.     the default program settings. Global variables with initial values are
  86.     defined when this file is included by SnoopDos.c, and declared when it's
  87.     included by other modules. Thus, if you change the initial value of
  88.     any global variables, SnoopDos.c must be recompiled (the makefile does
  89.     this automatically).
  90.  
  91.  
  92. SNOOPDOS.C
  93.  
  94.     SnoopDos.c is the top level module. It opens all the necessary libraries,
  95.     and calls the initialisation routines of most of the other modules. It is
  96.     also responsible for keeping the global program settings up to date. The
  97.     most important functions are:
  98.  
  99.               Cleanup()  Calls cleanup function of each module and exits
  100.              OpenLibs()  Opens all libraries needed by SnoopDos
  101.             mysprintf()  Re-entrant version of sprintf() library function
  102.       InstallSettings()  Updates subset of global settings with new values
  103.              MainLoop()  Waits for incoming events and dispatches them
  104.                  main()  Entry point for whole program.
  105.  
  106.  
  107. BUFFER.C
  108.  
  109.     Buffer.c contains all the functions that deal directly with the SnoopDos
  110.     event buffer. An "event" contains all the information needed to create a
  111.     single line of output in the SnoopDos window. Here are the most important
  112.     functions:
  113.     
  114.               InitBuffer()  Must be called at start of program
  115.           CleanupBuffers()  Called when program exits
  116.       SetTotalBufferSize()  Changes buffer size (allocating one if needed)
  117.              ClearBuffer()  Empties buffer contents
  118.              GetNewEvent()  Allocates space for a new event
  119.        ParseFormatString()  Converts "%d %s %p" into an internal format
  120.        BuildFormatString()  Converts internal format back to ascii string
  121.              FormatEvent()  Creates a formatted output line from an event
  122.          UnderlineTitles()  Creates an underline string for current titles
  123.          CheckSegTracker()  Called regularly to see if SegTracker is loaded
  124.  
  125.  
  126. LANGUAGE.C
  127. SNOOPTEXT.H
  128.  
  129.     Language.c deals with all the text strings used by SnoopDos. Specifically,
  130.     it identifies the users locale and decides whether to use the strings
  131.     hard-coded in the executable, or to read them from an external catalog
  132.     file instead. The main functions are:
  133.  
  134.         InitTextTable()  Called first. Creates default (english) string table
  135.            InitLocale()  Checks for external catalog files
  136.         CleanupLocale()  Frees any resources used by localisation
  137.  
  138.     Snooptext.h is generated automatically from SnoopText.cd by Commodore's
  139.     CATCOMP utility. It defines a unique numeric identifier for each string,
  140.     and (when included by language.c) the strings themselves. It should never
  141.     be edited by hand. It's included in the archive for the convenience of
  142.     those who don't have CatComp.
  143.  
  144.  
  145. PATCHES.C
  146. PATCHES.H
  147. PATCHCODE.S
  148.  
  149.     Patches.c is the backbone of SnoopDos -- it contains all the patch
  150.     routines that intercept calls made by other programs to various system
  151.     functions. Most of the functions in this file must be completely
  152.     re-entrant, since they can be called by many processes simultaneously.
  153.     The most important functions are:
  154.  
  155.             InitPatches()  Initialises the memory-resident patch code
  156.           UpdatePatches()  Attempts to install or remove all patches as needed
  157.        LoadFuncSettings()  Updates patches to reflect function settings
  158.          CleanupPatches()  Removes all patches (waiting until it's safe)
  159.        UpdateDeviceList()  Builds list of currently mounted DOS devices
  160.         InitRamLibPatch()  Fixes a bug in ramlib that can crash SnoopDos
  161.      BackgroundProcCode()  Background task for pattern matching/name expansion
  162.              SetPattern()  Parses the current AmigaDOS task match pattern
  163.         CreateEvent()  Creates a new event, filling in various fields
  164.        HandlePaused()  Puts a task to sleep when Pause is enabled
  165.        JumpOrigFunc()  A macro that exits by calling the original function
  166.  
  167.     Patches.h contains the prototypes for all the functions that are patched.
  168.     Each prototype defines the registers passed, along with a base register
  169.     in A6. The LVO offsets for each function are also defined here.
  170.  
  171.     Patchcode.s contains the low-level assembly language patch code which is
  172.     used for each function. The same piece of code is copied multiple times
  173.     to create a unique patch for each function. Whenever any cha