  KeyHand.Asm v1.3.3, Keyboard Data Ready ISR (18 January 1995)
  Copyright (C)1994-1995 Robert Rothenburg Walking-Owl
  
  The author can be contacted via e-mail at <rrothenb@ic.sunysb.edu>
  or surface mail at P.O.Box 1327, Stony Brook, NY, 11790 USA.

  License and (Non)Warranty:
  ==========================
  
  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or 
  (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

  Quick-and-Dirty Documentation:
  ==============================
  
  This is only a prototype handler. It has not been tested for enhanced
  keyboards, since I have no access to one. Nor does it handle keyboard
  errors, nor special keys such as Cntl-Break, Pause, System-Request,
  etc., so you'd have to either add that code yourself or wait until a
  new version is released.

  The interface routines included in this release are for Turbo Pascal,
  although the assembly code should easily work with most C compilers
  (though some tweaking may be necessary).

  The InstallKbdISR(), UnInstallKbdISR() and CheckForInstall() functions
  work as would be expeted, returning a non-zero value if the operation
  goes as expected, zero if something does not work.

  If __HOOKINT16 is defined then normal keyboard reads should work, or
  yor would use the OurReadKey(), OurCheckKey() and GetKeybdFlags()
  functions to read and check scan codes/flags (which is advantageous
  for applications which require some isolation from the rest of the
  system: my original motivation for writing this was for crypto and
  communications packages that could be immune from keyboard-trapping
  trojans.

  If RandPoolSize is set to a non-zero value the handler will fill a
  (small) random noise pool based on timings between keystrokes. The
  address of this pool is returned by GetRandPoolAddr() [this function
  may need to be modified depending on the memory model used]. Another
  function NumBitsInPool() returns the number of "random" bits in the
  pool since installation.

  If simultaneous keypresses are needed (as with many games), you can
  define __MULTIKEYMAP: a map of the scan codes is returned bu the
  GetKeyPrMapAddr() function.

  Future versions of this software will include handling for enhanced
  (and hopefuly 120-key keyboards), as well as processing of Cntl-Break,
  SysReq, PrtSc, Cntl-Alt-Reset et cetera., among other things. A brief
  note on bugs and needed-fixes is in the beginning of the KeyHand.Asm
  file.

  Before releasing any modifications or porting this software, please
  contact me first so as to not duplicate work someone else has done.

  Notes on Conditional Defines:
  =============================
  
  __FOR286              Enabling this targets the code for 80286 machines.
                        Saves a few bytes of code, and if you're writing
                        a program for newer machines you may as well have
                        it enabled.

  __SUPERKEY            Enables "SuperKey" <Alt>-Num combinations, which 
                        means a program can check for <Alt><Gray +> or 
                        <Alt><4>, etc.  Note that <Alt>-nnn ASCII combin-
                        ations require <Alt><LShift>-nnn.

  __CNTLNUMPAD          Enables <Cntl>-Num combinations.  This appears to
                        be "standard" but is not documented in many books.

  __STRICT              Some key combinations (such as <Alt><Tab>) do not
                        generate a scan code.  If this is enabled, no scan
                        code will be generated for such keys.

  __ENHANCED            Support for enhanced keyboards.  [Note that full
                        support is not fully implemented in this version,
                        since I do not have access to an enhanced keyboard
                        at this time.]

  __MULTIKEYMAP         Enabled, keeps a "map" of scan codes for the keys.
                        This allows programs which require multiple key-
                        presses (such as games) to check the map (the
                        address is returned by the GetKeyPrMapAddr func.)

  __DONTDECODE          Meant to be used with __MULTIKEYMAP. Scan codes
                        will not be decoded and posted on the queue.
                        
  __USERNDBITS          If enabled when RandPoolSize<>0, each keypress
                        will samples bits instead of bytes for the random
                        noise pool.

  __TSR                 Tells the CheckForInstall routine to use a TSR-
                        checking method to see if a previous version of
                        the program is loaded.  Default is to check the
                        addresses.

  __HOOKINT16           If enabled tells the handler to add an Int 0x16
                        handler for the keyboard.
                        
                        Default is to use isolated keyboard functions 
                        (which allows for some immunity from keyboard
                        sniffers).

  __USEBIOS             Not yet implemented. In future versions this will
                        have the handler use the normal BIOS Data Area's
                        keyboard data buffers and registers.

  KeyQueueSize          Defines the number of key-strokes in the queue.
                        Default is 16. [Note that in this implementation
                        only KeyQueueSize-1 keystrokes are queued.]

  RandPoolSize          If not set to zero, a random-noise pool based on 
                        timings between keystrokes is kept. Note that the 
                        buffer holds one less than the defined size (until
                        that bug is fixed, anyway).

  __INITRANDPOOL        Fills the random-noise pool which samples from the
                        system timer upon installation.
  
  History of Changes:
  ===================
  
  1.3.0 29 Dec 1994    Limited release of beta-test versions.
  1.3.2  13 Jan 1995    First public release.
  1.3.3                 Added "beep" when keyboard buffer full; added the
                        __INITRANDPOOL conditional-define; modified the
                        SampleNoise routine so that duplicate bytes would
                        not occur.
