home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 19 / AACD19.BIN / AACD / System / SnoopDos / SnoopDos_Src / SnoopDos_Source / SnoopDos.Roadmap < prev    next >
Text File  |  2000-03-05  |  21KB  |  459 lines
  1.  
  2.                         SnoopDos 3.2 -- Source Code Roadmap
  3.  
  4.            Copyright © Eddy Carroll, September 1994. Freely distributable.
  5.  
  6.            Updated by Luca Longone and Massimo Tantignone in January 2000.
  7.  
  8.        Updated again by Grzegorz Chmie and Thomas Richter in March 2000.
  9.  
  10.  
  11. NOTE ABOUT THE 3.1 UPDATE
  12.  
  13.            References to PGP in the following text are not applicable to
  14.            SnoopDos versions greater than 3.0. If you need authentication,
  15.            please write to one of the following e-mail addresses:
  16.  
  17.            llong@tin.it, hexaae@tiscalinet.it (Luca Longone)
  18.            tanti@intercom.it (Massimo Tantignone)
  19.            ecarroll@iol.ie (Eddy Carroll)
  20.  
  21.            What follows is the original roadmap text for SnoopDos 3.0,
  22.            which is also valid for the 3.1 update.
  23.  
  24. NOTE ABOUT THE 3.2 UPDATE
  25.  
  26.        The SnoopDos 3.1 release has been reworked again, you may
  27.        contact thor@math.tu-berlin.de (Thomas Richter) for additional 
  28.        informations or authentication.
  29.        
  30.        The SnoopDos AppIcon fix was proposed by Grzegorz Chmiel 
  31.        <gchmiel@pnet.pl> and has been integrated into the sources.
  32.        Thanks!
  33.        
  34.        Thank goes to Eddy Carroll for allowing me to redistribute the
  35.        program.
  36.  
  37.  
  38. 3.2 UPDATE NOTES FOR THE PROGRAMMER
  39.  
  40.        The sources remained greatly unmodified except some minor fixes.
  41.  
  42.        - The patch codes check now explicitly whether the main window
  43.        layer is available as some gfx calls temporarely set 
  44.        RastPort->Layer to NULL before proceeding. This caused some
  45.        frequent enforcer hits in the past.
  46.  
  47.        - The AppIcon code copied the gadget data manually from the
  48.        disk icon to a temporarly dummy icon. This does not work for
  49.        "newicons" because they store the image in the tooltypes.
  50.        (Wierd stuff anyhow...) Thanks, Grzegorz!
  51.  
  52.        - DeleteExtIO() and CreateExtIO() have been replaced by
  53.        DeleteIORequest() and CreateIORequest().
  54.  
  55.        - The header snoopdos.h was enhanced to include all the prototypes
  56.        of functions exported amongst modules. This was necessary for
  57.        the next step.
  58.  
  59.        - The program was recompiled using SAS/C 6.58, and using
  60.        registerized parameters, making the binary shorter and decreasing
  61.        stack usage.
  62.  
  63.        - I decided to replace the SAS/C startup code by my own code
  64.        which is a bit smarter and shorter. The makefile still includes
  65.        the old LIB:c.o startup, though. It should be possible to 
  66.        compile the program right away with the new makefile, just
  67.        setup an assign "SD:" for a backup directory where the final
  68.        files should be copied to.
  69.     
  70.        - Replaced one bogus call to KPrintf() by the DB() macro.
  71.  
  72.        - Linking with amiga.lib and debug.lib is no longer required for
  73.        the final clean version.
  74.  
  75.        - Added a "make clean" rule for the makefile.
  76.  
  77.        - Added a "Project-Startup" file which will build a project
  78.        directory, copy the file from a backup location to a working 
  79.        directory and sets up all the assigns used in the makefile.
  80.  
  81. INTRODUCTION
  82.  
  83.     SnoopDos was written using SAS/C 6.51. The Amiga programming community
  84.     owe a large debt of thanks to Doug Walker, Steve Krueger, Jim Cooper,
  85.     and everyone else at SAS Institute for providing such a useful and
  86.     stable development environment. Without SAS/C, development of SnoopDos
  87.     would have taken significantly longer.
  88.  
  89.     If you have SAS/C, then you should be able to recompile SnoopDos with
  90.     no problems by simply typing "smake" in this directory. You might want
  91.     to turn off optimisation in the SCOPTIONS file if you are experimenting;
  92.     otherwise, prepare for a long wait.
  93.  
  94.     If you are using DICE or another compiler, you will need to ensure that
  95.     you are using similar compiler options to those listed in SCOPTIONS. You
  96.     will also need to change the function prototypes in patches.h and perhaps
  97.     in patches.c. A future release may detect DICE automatically and do the
  98.     right thing.
  99.  
  100.     In general, most files have an initialisation function and all have a
  101.     cleanup function. The initialisation function should be called at the
  102.     beginning of the code and the cleanup function at the end. All cleanup
  103.     functions are safe to call multiple times if necessary.
  104.  
  105.     Note that all the source code has been formatted with a tab setting of
  106.     4 spaces. If your editor uses tabs set to some other width, then it is
  107.     strongly recommended that you run the code through Detab or a similar
  108.     utility, otherwise it will look a mess.
  109.  
  110.  
  111. MODULE OVERVIEW
  112. ---------------
  113. Here's a summary of the different files and what they are used for:
  114.  
  115.        system.h   Master include file for all system headers
  116.        system.c   Includes system.h -- used to create the GST file
  117.      snoopdos.h   Defines all program globals, structures, constants, protos
  118.      snoopdos.c   Top level module. Initialises and cleans up other modules
  119.        buffer.c   Allocates and formats events in the event buffer
  120.      language.c   Makes localised text strings available to other modules
  121.     snooptext.h   Master message include file used by all modules
  122.       patches.c   All the patch code inserted into system libraries
  123.       patches.h   Header file that prototypes all the patched functions
  124.     patchcode.s   Low-level assembly code used by patch mechanism
  125.      settings.c   Handles the command line interface to SnoopDos
  126.           gui.h   Constants which define the exact appearance of the GUI
  127.       mainwin.c   All functions relating to the main window
  128.        subwin.c   All functions relating to the other three windows
  129.       miscwin.c   Miscellaneous window and screen functions used everywhere
  130.        hotkey.c   Handles commodity interface + Workbench AppIcon/Toolmenu
  131.          icon.h   Image data for custom SnoopDos icon (from IconEdit)
  132.     snooptext.cd  SnoopDos catalog description file, for localisation
  133.     snooptext.ct  Example SnoopDos translation file, for localisation
  134.     testcalls.c   Separate utility to stress test the SnoopDos patch code.
  135.  
  136.  
  137. MODULE GUIDE
  138. ------------
  139. Here's a more detailed look at the contents of each module. See the module
  140. itself for full details.
  141.  
  142.  
  143. SYSTEM.H
  144. SYSTEM.C
  145.  
  146.     System.h is the master include file for all Amiga system includes. Any
  147.     system include used by any module is placed in here. The entire set of
  148.     includes is then precompiled into a SAS/C GST file, which greatly speeds
  149.     up compilation.
  150.  
  151.    System.c is the file used to generate the GST -- it simply includes
  152.    the System.h header file.
  153.  
  154.  
  155. SNOOPDOS.H
  156.  
  157.     SnoopDos.h is included by all other modules. It defines all the global
  158.     variables, structures, and prototypes used by SnoopDos. It also includes
  159.     the default program settings. Global variables with initial values are
  160.     defined when this file is included by SnoopDos.c, and declared when it's
  161.     included by other modules. Thus, if you change the initial value of
  162.     any global variables, SnoopDos.c must be recompiled (the makefile does
  163.     this automatically).
  164.  
  165.  
  166. SNOOPDOS.C
  167.  
  168.     SnoopDos.c is the top level module. It opens all the necessary libraries,
  169.     and calls the initialisation routines of most of the other modules. It is
  170.     also responsible for keeping the global program settings up to date. The
  171.     most important functions are:
  172.  
  173.               Cleanup()  Calls cleanup function of each module and exits
  174.              OpenLibs()  Opens all libraries needed by SnoopDos
  175.             mysprintf()  Re-entrant version of sprintf() library function
  176.       InstallSettings()  Updates subset of global settings with new values
  177.              MainLoop()  Waits for incoming events and dispatches them
  178.                  main()  Entry point for whole program.
  179.  
  180.  
  181. BUFFER.C
  182.  
  183.     Buffer.c contains all the functions that deal directly with the SnoopDos
  184.     event buffer. An "event" contains all the information needed to create a
  185.     single line of output in the SnoopDos window. Here are the most important
  186.     functions:
  187.  
  188.               InitBuffer()  Must be called at start of program
  189.           CleanupBuffers()  Called when program exits
  190.       SetTotalBufferSize()  Changes buffer size (allocating one if needed)
  191.              ClearBuffer()  Empties buffer contents
  192.              GetNewEvent()  Allocates space for a new event
  193.        ParseFormatString()  Converts "%d %s %p" into an internal format
  194.        BuildFormatString()  Converts internal format back to ascii string
  195.              FormatEvent()  Creates a formatted output line from an event
  196.          UnderlineTitles()  Creates an underline string for current titles
  197.          CheckSegTracker()  Called regularly to see if SegTracker is loaded
  198.  
  199.  
  200. LANGUAGE.C
  201. SNOOPTEXT.H
  202.  
  203.     Language.c deals with all the text strings used by SnoopDos. Specifically,
  204.     it identifies the users locale and decides whether to use the strings
  205.     hard-coded in the executable, or to read them from an external catalog
  206.     file instead. The main functions are:
  207.  
  208.         InitTextTable()  Called first. Creates default (english) string table
  209.            InitLocale()  Checks for external catalog files
  210.         CleanupLocale()  Frees any resources used by localisation
  211.  
  212.     Snooptext.h is generated automatically from SnoopText.cd by Commodore's
  213.     CATCOMP utility. It defines a unique numeric identifier for each string,
  214.     and (when included by language.c) the strings themselves. It should never
  215.     be edited by hand. It's included in the archive for the convenience of
  216.     those who don't have CatComp.
  217.  
  218.  
  219. PATCHES.C
  220. PATCHES.H
  221. PATCHCODE.S
  222.  
  223.     Patches.c is the backbone of SnoopDos -- it contains all the patch
  224.     routines that intercept calls made by other programs to various system
  225.     functions. Most of the functions in this file must be completely
  226.     re-entrant, since they can be called by many processes simultaneously.
  227.     The most important functions are:
  228.  
  229.             InitPatches()  Initialises the memory-resident patch code
  230.           UpdatePatches()  Attempts to install or remove all patches as needed
  231.        LoadFuncSettings()  Updates patches to reflect function settings
  232.          CleanupPatches()  Removes all patches (waiting until it's safe)
  233.        UpdateDeviceList()  Builds list of currently mounted DOS devices
  234.         InitRamLibPatch()  Fixes a bug in ramlib that can crash SnoopDos
  235.      BackgroundProcCode()  Background task for pattern matching/name expansion
  236.              SetPattern()  Parses the current AmigaDOS task match pattern
  237.        CreateEvent()  Creates a new event, filling in various fields
  238.       HandlePaused()  Puts a task to sleep when Pause is enabled
  239.       JumpOrigFunc()  A macro that exits by calling the original function
  240.  
  241.     Patches.h contains the prototypes for all the functions that are patched.
  242.     Each prototype defines the registers passed, along with a base register
  243.     in A6. The LVO offsets for each function are also defined here.
  244.  
  245.     Patchcode.s contains the low-level assembly language patch code which is
  246.     used for each function. The same piece of code is copied multiple times
  247.     to create a unique patch for each function. Whenever any changes are
  248.     made to this code, or to the Patch structure which contains the code and
  249.     associated data, then the corresponding structure in Patches.c must be
  250.     updated. In addition, if the stack alignment on entry to the C patches
  251.     changes, the JumpOrigFunc() and MarkCallAddr macros must be adjusted.
  252.  
  253.  
  254. SETTINGS.C
  255.  
  256.     Settings.c controls all the program settings. This includes loading and
  257.     saving settings files to disk, parsing the Workbench and CLI startup
  258.     options, and handling the ARexx interface. The important functions are:
  259.  
  260.          InitSettings()  Initialises command name table
  261.          ParseCommand()  Syntax checks a SnoopDos command line
  262.           ExecCommand()  Executes a SnoopDos command line
  263.            SaveConfig()  Writes current settings to a command file
  264.            LoadConfig()  Executes all the commands in a command file
  265.            SendRemote()  Sends a command to a background copy of SnoopDos
  266.          ShowCommands()  Prints a formatted list of SnoopDos commands
  267.      ParseStartupOpts()  Parses Workbench and CLI startup options
  268.  
  269.          InitRexxPort()  Initialises ARexx port
  270.       CleanupRexxPort()  Frees ARexx port
  271.        HandleRexxMsgs()  Handles incoming ARexx messages
  272.  
  273.  
  274. GUI.H
  275.  
  276.     Gui.h file defines constants which relate to the SnoopDos GUI. These
  277.     are mainly used to finetune the gadget layout but also include a few
  278.     keyboard-related definitions. This file is included by MAINWIN.C,
  279.     SUBWIN.C and MISCWIN.C
  280.  
  281.  
  282. MAINWIN.C
  283.  
  284.     Mainwin.c handles everything associated with the main window. It has
  285.     grown too large and should really be subdivided (again). Here are the
  286.     most important functions in the file:
  287.  
  288.           CheckForScreen()  Locates current screen (locking if necessary)
  289.             ShowSnoopDos()  Opens SnoopDos window on the current screen
  290.             HideSnoopDos()  Closes main window, help and any other windows
  291.           OpenMainWindow()  Opens main window
  292.      CreateScrollGadgets()  Creates BOOPSI scroll gadgets for main window
  293.        CreateMainGadgets()  Creates gadtools gadgets for main window
  294.          CloseMainWindow()  Closes main window
  295.        CleanupMainWindow()  Frees all resources for main window
  296.         ReOpenMainWindow()  Closes and then opens main window
  297.        RecordWindowSizes()  Records sizes of all open windows
  298.         SetMainHideState()  Enables/disables Hide gadget and window title
  299.  
  300.                InitMenus()  Initialises shortcut keys for localised menus
  301.           SetMenuOptions()  Updates boolean menu options with current settings
  302.           HandleMainMsgs()  Handles menu, gadget and keypress input
  303.          HandleNewEvents()  Outputs any new events to the main window
  304.           SetMonitorMode()  Sets monitor mode to normal, Paused or Disabled
  305.  
  306.         RedrawMainWindow()  Draws everything in main window except gadgets
  307.           DrawHeaderLine()  Draws headerline at top of screen
  308.               ShowBuffer()  Redraws the main window buffer
  309.         DrawSelectedLine()  Highlights a single line in the buffer
  310.        ClearWindowBuffer()  Erases window buffer display
  311.         ScrollHorizontal()  Efficiently scrolls window contents to left/right
  312.        UpdateMainHScroll()  Updates horizontal scroll gadget to current offset
  313.        UpdateMainVScroll()  Updates vertical scroll gadget to current position
  314.               ShowStatus()  Displays a message in the status bar
  315.             UpdateStatus()  Displays status message reflecting current state
  316.  
  317.                  OpenLog()  Opens a new logfile
  318.                 WriteLog()  Writes some text to the logfile
  319.                 CloseLog()  Closes the current logfile
  320.               SaveBuffer()  Saves current buffer contents to file/clipboard
  321.             SetLogGadget()  Selects appropriate wording for log gadget
  322.  
  323. SUBWIN.C
  324.  
  325.     Subwin.c contains all the functions needed to manage the format editor,
  326.     settings window and function window. The most important functions are:
  327.  
  328.           CleanupSubWindow()  Closes all currently open windows
  329.  
  330.         OpenSettingsWindow()  Opens settings window
  331.        CloseSettingsWindow()  Closes the settings window
  332.      CreateSettingsGadgets()  Creates font-sensitive gadgets for window
  333.         HandleSettingsMsgs()  Handles keyboard and gadget input
  334.  
  335.         OpenFunctionWindow()  Opens function window and creates gagdets
  336.      CreateFunctionGadgets()  Creates font-sensitive gadgets for window
  337.        CloseFunctionWindow()  Closes the functions window
  338.             HandleFuncMsgs()  Handles keyboard and gadget input
  339.        ResetFuncToSelected()  Handles the "All/None/Selected" function gadgets
  340.               ShowFuncOpts()  Updates display of current function settings
  341.                GetFuncName()  Returns a name matching a function ID
  342.  
  343.           OpenFormatWindow()  Creates the format editor window and gadgets
  344.          CloseFormatWindow()  Closes the format editor window
  345.        CreateFormatGadgets()  Creates font-sensitive gadgets for window
  346.           HandleFormatMsgs()  Handles gadget and keyboard input
  347.      InstallNewFormat()  Updates all windows to reflect a new format
  348.             CreateBob()  Creates a new BOB (Blitter OBject)
  349.          FreeBob()  Frees a BOB created earlier
  350.                  PickupBob()  Copies a text line into a BOB for Drag & Drop
  351.          DropBob()  Drops the text line in a new position
  352.        UpdateBob()  Moves BOB to a new osition
  353.  
  354. MISCWIN.C
  355.  
  356.     Miscwin.c contains a variety of functions related to the GUI that don't
  357.     conveniently fit anywhere else. As well as general screen and window
  358.     functions, it also handles the AmigaGuide interface, and creates the
  359.     custom images used for the file/font gadgets in the settings window.
  360.  
  361.                 InitFonts()  Initialises fonts according to system preferences
  362.               SetupScreen()  Locates a screen for SnoopDos to open on
  363.             CleanupScreen()  Frees misc info related to current screen
  364.                 ShowError()  Displays an error requester
  365.               GetResponse()  Displays a requester with multiple choices
  366.                SelectFont()  Displays ASL font requester to get a font
  367.                SelectFile()  Displays ASL file requester to get a file name
  368.            AddKeyShortcut()  Update keyboard shortcuts array for a window
  369.                MyOpenFont()  Tries to open a font, from disk or from ROM
  370.         ConvertIMsgToChar()  Converts an IntuiMsg RAWKEY event to ascii
  371.  
  372.                ShowAGuide()  Loads AmigaGuide and displays a help page
  373.             CleanupAGuide()  Shuts down AmigaGuide
  374.          HandleAGuideMsgs()  Handles incoming messages from AmigaGuide
  375.  
  376.         CreateCustomImage()  Creates a new scaled file or font image
  377.           FreeCustomImage()  Frees an image allocated earlier
  378.                ShowGadget()  Presses or releases a button gadget
  379.  
  380.  
  381. HOTKEY.C
  382. ICON.H
  383.  
  384.     Hotkey.c contains functions to handle commodity support, and interfacing
  385.     with Workbench (for AppIcon and ToolMenu support). It also deals with
  386.     icons. The important functions are:
  387.  
  388.            InstallHotKey()  Installs commodity hotkey, initialising if needed
  389.            CleanupHotKey()  Shuts down commodity exchange support
  390.         HandleHotKeyMsgs()  Handles incoming msgs from commodity exchange
  391.  
  392.           GetProgramIcon()  Finds (or creates) the SnoopDos program icon
  393.                WriteIcon()  Writes current icon to disk
  394.             CleanupIcons()  Frees any icons allocated earlier
  395.  
  396.          AddProgramToWorkbench()  Creates an AppIcon or Tools menu entry
  397.     RemoveProgramFromWorkbench()  Removes any outstanding appicons/menu items
  398.            HandleWorkbenchMsgs()  Handles incoming msgs from Workbench
  399.  
  400.     Icon.h contains the image data for the image used when writing icons to
  401.     disk if no icon could be found for the SnoopDos executable. This is
  402.     generated directly from IconEdit (set the SRC=YES tooltype), and has a
  403.     30 line header that does a few #define's to isolate IconEdit-dependent
  404.     variable names from the rest of the program.
  405.  
  406.  
  407. SNOOPTEXT.CD
  408. SNOOPTEXT.CT
  409.  
  410.     SnoopText.cd is the localisation file for SnoopDos. It contains all the
  411.     messages used throughout the program. This file is compiled by Commodore's
  412.     CatComp utility to provide SNOOPTEXT.H which is then included by all
  413.     other modules. Thus, modifying SnoopText.cd requires that everything be
  414.     recompiled from scratch.
  415.  
  416.     SnoopText.ct is a ready-to-go translation file which can be used with
  417.     CatComp to produce an external catalog file for use with SnoopDos. It
  418.     was generated automatically from SnoopText.cd using CatEdit by Rafael
  419.     D'Halleweyn and is included for the convenience of those who don't have
  420.     CatEdit to hand.
  421.  
  422.  
  423. TESTCALLS.C
  424.  
  425.     This is a completely separate program. It was written to provide a means
  426.     of stress testing SnoopDos. It is not complete, hence it is not part
  427.     of the main SnoopDos program archive. Currently, it supports all of the
  428.     system functions and a few DOS functions.
  429.  
  430.     It can be instructed to continuously call one or more of the functions
  431.     monitored by SnoopDos. Many subtle bugs were uncovered by running this
  432.     multiple times simultaneously.
  433.  
  434.  
  435. DISTRIBUTION CONDITIONS
  436. -----------------------
  437.  
  438. You may freely use portions of the SnoopDos source code in your own programs
  439. if you wish. However, if you use two or more complete functions from the
  440. SnoopDos code, you must acknowledge the origin of those functions in your
  441. documentation and source code.
  442.  
  443. You may modify the SnoopDos source code to create new versions of SnoopDos
  444. for your own use only. You may not redistribute such new versions without my
  445. explicit permission.
  446.  
  447.  
  448. FURTHER INFORMATION
  449. -------------------
  450. For additional information about the source code or algorithms used, you
  451. can contact me at:
  452.  
  453.     ecarroll@maths.tcd.ie
  454.     ecarroll@cix.compulink.co.uk
  455.  
  456. To obtain a copy of my PGP public key (used to authenticate distribution
  457. copies of SnoopDos 3.0 and above) send a message to ecarroll@maths.tcd.ie
  458. with the subject line "PGPKEY".
  459.