OS/2 Shareware BBS: 11 Util/11-Util.zip/MKHOOK1.ZIP/HOOK_KB.DOC

Internet Message Format | 1992-09-05 | 17KB

From : Morton F. Kaplon  CIS : 73457,437
       1047 Johnston Drive
       Bethlehem PA 18017
       [phone]

To   : Those Concerned

Sat  09-05-1992

Subject : Hooking the Keyboard in OS/2 2.0  (Revised)

REVISION NOTE

  This revision uses the hook HK_INPUT instead of HK_SENDMSG and hooks WM_CHAR
  rather than WM_TRANSLATEACCEL. The conflicts that existed with KWIKINF no
  longer exists and the kludge that was used is no longer required.


INTRODUCTION

  Hook_kb works in conjunction with hook_dll, a dynamic link module. hook_dll
  captures Key Strokes (via sampling the systen nessage queue) from all
  Windows BUT OS/2 or DOS Full Screen. To capture from these would require an
  additional program but since my principal purpose was to create a program
  that would allow me to assign the calling of programs to Alt-# or Ctrl-#
  keystrokes independent of where I was working and since not using Full
  Screen has advantages in flexibility, I decided to go without it.


OVERVIEW

  FILES REQUIRED TO CREATE hook_kb.EXE AND hook_dll.DLL
  doswin32.mac  Macros and Equates used by Programs

  hook_kb.asm   Source for Executable, Assembled and Linked by mlc-w386.cmd

  hook_dll.def  Define file needed by IMPLIB and linker for hook_dll.asm

  hook_dll.asm  Source for hook_dll.dll, Assembled and linked by dll-w386.cmd

  dll-w386.cmd  IMPLIB with hook_dll.def creates c:\toolkt20\os2lib\hook_dll.lib
  (a CMD File)  MASM then assembles hook_dll.asm, LINK386 produces hook_dll.dll
                and hook_dll.dll is copied to c:\os2\dll

  mlc-w386.cmd  MASM assembles hook_kb.asm and LINK386 produces hook_kb.exe
  (a CMD File)

  To ASSEMBLE and LINK use the directory holding the above files as default
  and the commands below to produce the necessary files.
     dll-w386  hook_dll
     mlc-w386  hook_kb

  FILES REQUIRED TO EXECUTE hook_kb.EXE
  hook_kb.dat   Text File assigning programs to key strokes-read by hook_kb.
                The user creates this file according to structure outlined in
                the sample. MUST BE LOCATED IN C:\OS2. Edit the sample to
                fit your needs.

  hook_kb.exe   Exec file created above

  hook_dll.dll  Dynamic Load File Created Above - must be in c:\os2\dll

  DO NOT RENAME hook_dll.* or hook_kb.DAT as those names are coded into
  hook_kb.ASM .

  The assembler used is MASM 6.0 including its built in MACROS for control
  structures and segment definitions.


  PROGRAM METHOD

  The system message queue is hooked using the HK_INPUT parameter. The
  function which samples the message queue is in hook_dll.DLL. In the section
  "Input Hook", p. 30-2 in the Programming Guide, Vol. II, it states : "The
  system calls an input_hook function whenever the WinGetMsg or WinPeekMsg
  functions is about to return a message." The installed function tests for
  WM_CHAR and when detected POSTS the mp1 and mp2 parameters of the message to
  HOOK_KB which tests for the following set of Key Strokes: Alt-Del (NumPad),
  Alt-0 to Alt-9 and Ctrl-0 to Ctrl-9. (The restriction is mine since I did
  not want to interfere with keystrokes used by my editor and OS/2 uses a lot
  of the Function Keys). The Alt-Del key-stroke is assigned to removing the
  DLL from memory and closing the program, equivalent to unloading a TSR in
  DOS.

  The main program, hook_kb.exe, a PM program, sets up the hook, receives the
  message indicated above and takes the appropriate action depending on the
  Key Stroke. The program is established as Invisible and Not listed in the
  Window List. The program should be launched from an OS/2 window with the
  START command, i.e. "START hook_kb". That command can be placed in a
  STARTUP.CMD for automatic loading.

  The flow of hook_kb is delineated below. The same headings are listed in
  the source code in hook_kb.ASM.


  PROGRAM FLOW : hook_kb

  PRELIMINARIES
    Define Model and Calling Protocol
    Equates for Using Macros in .DATA
    Equates for INC files
    Include file listings
    Prototype definitions for MASM
    Structure definition for storing info on Program Assignment to Keys

  .STACK   defines an 8KB stack

  .DATA    contains variables,parameters and strings required for .CODE section

  .CODE    outlined below

  ESTABLISH WINDOW
    WinInitialize            ;Initialize
    WinCreateMessageQueue    ;Create a Message Queue
    WinRegisterClass         ;Registers and identifies MainWinProc as name
                             ;of Procedure for messages
    WinCreateStdWindow       ;Creates window - here it is made Invisible,etc.

  IS hook_dll.DLL LOADED ?   ;If yes, display message and exit

  ALLOCATE SHARED MEM AND STORE HANDLE Returned by WinCreateStdWindow
    This is required in order to pass the Handle to hook_dll

 IS DATA FILE AVAILABLE AND VALID ?  ;for custom use may not be required
    Load c:\os2\hook_kb.dat  ;If it does not exist, exit with Error Message
    Get hook_kb.dat FileSize ;Required by program for subsequent use
    AllocateMemoryBuffer     ;Buffer for User Key assignments from DataFile
    Copy hook_kb.dat->Buffer ;Read File into Buffer
    Close hook_kb.dat        ;No longer needed
    Process Data in Buffer   ;If Format Not Correct, EXIT with  Message

  ESTABLISH THE HOOK
    DosLoadModule            ;Loads hook_dll.dll
    DosQueryProcAddr         ;Get the address of the function in the DLL
    WinSetHook               ;Uses the Address above and HK_INPUT to set HOOK

  CREATE MAIN MESSAGE LOOP   ;Standard PM requirement but EXIT TEST is
                             ;commented out - a WM_QUIT message has no
                             ;impact here

  EXIT ROUTINE               ;Note this is commented out but is included
                             ;to demonstrate the overall structure of
                             ;setting up a PM program

  PROCESS MESSAGE QUEUE      ;The heart of a PM program

    MainWinProc              ;Processes message queue
      TEST SYSTEM QUEUE FOR MESSAGES FROM
        WM_CREATE
        WM_PAINT
        WM_CHAR
        WM_USER+200h             ;dispatched from hook_dll.dll
        IF msg = WM_USER+200h
         FILTER KEYSTROKES      ;Can be customized and code below replaces
         IF Alt-Del struck
              Release DLL,Memory, Close Queues and Windows and Exit
          ELSE
              Test for keystrokes ALt-0 to Alt-9 and Ctrl-0 to Ctrl-9.If
              assigned in hook_kb.dat then call DosStartSession with
              parameters to start desired programs. The programs that may be
              started are OS/2 or DOS Windows, CMD or BAT files, or any OS/2
              or DOS executables (EXE or COM).
          ENDIF
        ENDIF

  The flow of hook_dll is delineated below. The same headings are listed in
  hook_kb.DLL.

  PROGRAM FLOW : hook_dll

  PRELIMINARIES
    Define Model and Calling Protocol
    Equates for INC files
    Include file listings

  .STACK   defines a 2KB stack

  .DATA    contains variables,parameters and strings required for .CODE section

  .CODE    delineated below

  ESTABLISH InputHook

  GET ADDRESS OF SHARED MEMORY

  GET HANDLE OF hook_kb AND RELEASE SHARED MEMORY

  IF WM_CHAR MESSAGE DETECTED
       WinPostMessage to hook_kb
  ENDIF


DISCUSSION


  DOSWIN32.MAC  (Macros and Equates used by Program)

  This file contains the equates, EXTRN declarations, MACROS and Procedures
  used in the ASM files. The EXTRN declarations include many more than those
  used in the program but represent the accrued list of those used so far in
  my OS/2 assembler programming. (As I use a new one, I just add it).

  Included are two defines used in the .DATA section of hook_kb.asm. The
  single most important MACRO is $CALL. This allows one to list parameters
  after the function name in the same order as they are listed in the OS/2 2.0
  Technical Manuals. The macro pushes them on the stack in the correct order
  and resets the stack pointer after the call. It could clearly easily be
  extended to accomodate a longer parameter list. Following that are several
  useful macros and three others defined via equates.

  For displaying error messages and rudimentary inline debugging, there are
  three macros named $DosErrMsg, $WinErrMsg and $WinDebugMessage . The first
  two are meant to be called after an API function call to display the error
  number for the function used. Information on the success of the call is
  returned in EAX and this must be tested. Note EAX returns differently for
  DOS than for WIN calls. The user passes the text string for the Function
  used on the parameter line for the $XXXErrMsg. $DosErrMsg can only be used
  in Text Windows while $WinErrMsg only in PM windows.

  Finally there are several macros and procedures used for Binary <-> ASCII
  conversion for both Decimal and Hex, and also for displaying numerical
  results in Binary form. Not all of these are used but are included as a part
  of the overall package. Note that in 32 bit mode, it is most convenient to
  do all these conversion as DWORDS. These are required for numerical to ASCII
  conversion for the error messages.

  hook_dll.DEF

  This file is required by both IMPLIB and LINK386 in the creation of
  hook_dll.dll. It identifies the function(s) exported from the DLL.

  hook_dll.ASM

  This file represents the dynamic link code. It contains one function, named
  InputHook whose syntax is defined by OS/2 on page 30-2 of the Programming
  Guide, Vol II of the OS/2 Technical Library. This DLL monitors the system
  message queue and looks for the message WM_CHAR.

  Since I decided to use WinPostMsg to return information to hook_kb, its
  handle is required in this program. The simplest way seemed to be to pass it
  in a shared memory region established by hook_kb. Thus the first task done
  by the function InputHook, after setting itself up, is to get the address of
  the shared memory region and to obtain the handle of hook_kb that was placed
  there by hook_kb. After that is done, the shared memory is released.

  The program then waits for a message WM_CHAR and when that is detected it is
  posted to hook_kb using WinPostMsg with the message ID of WM_USER+200h and
  sending the parameters mp1 and mp2 that were contained in message WM_CHAR.
  This DLL is released from memory when hook_kb is closed.

  hook_kb

  The first four WIN... function calls are a standard calling sequence in
  setting up a PM program. Since a PM program cannot display text using DOS
  write calls, error messages cannot be displayed with Window Message Calls
  until the Window is initialized with the first call.

  After the window is established a test is done to see if HOOK_DLL is loaded.
  If it is a message is given and the program terminates. A Shared Memory area
  is then established. Its sole use in this program is to furnish a method of
  passing hook_kb's handle to hook_dll. This is done following the call to
  DosAllocSharedMem. Note that eax is now tested for a non-zero value
  indicating an error, as contrasted to Win calls where a 0 returned in eax
  indicates an error.

  Next the program attempts to load the data file c:\os2\hook_kb.dat. If it
  does not exist, an error message is displayed and the program terminates. If
  it loads, its size is obtained (note the calls are rather similar to what
  you would do in DOS) and that value is used to create a buffer to hold the
  file in memory. The file is read into the buffer and then closed. The big
  .WHILE loop reads the buffer and assigns the Addresses of the Executable
  program name and Command Line parameters and the Session type to the
  appropriate member of the Structure ExecOnKb and places a 0 at the end of
  strings in order that they meet the requirement of being ASCIIZ strings. If
  the count of characters read in the buffer does not equal the file size or
  if the data file was not properly formatted, an error message is displayed
  and the program terminated; the error message displays the number of bytes
  of the buffer processed when the program terminated.

  If everything is in order, the HOOK is now established with the next three
  calls to DosLoadModule, DosQueryProcAddr and WinSetHook.

  The Main Message Loop is next established. Normally this loop is exited when
  WM_QUIT is received and the exit code is executed to gracefully terminate
  the program. However, in this program, to ensure that it is terminated only
  by the Key Combination Alt-Del, the Main Message Loop is not exitable (I
  have commented out the normal tests) and I have included the Exit code only
  for purposes of demonstration of what a more normal program would look like.

  The procedure MainWinProc examines the message queue. It first sets up to
  get the parameters passed on the stack and goes through a series of tests
  for specific messages. In a C program this would usually be a Case
  statement. There is no requirement for these tests to do anything in this
  case since the window is invisible but they are required to respond to
  certain system calls.

  The heart of the program is the test for WM_USER+200h . WM_USER defines a
  lower limit for message IDs that is (presumably) guaranteed not to conflict
  with any system messages. I have arbitrarily used WM_USER + 200h. HOOK_DLL
  uses this message ID in posting its information to this programs message
  queue. First a test is done to see whether Alt-Del was struck and if so, the
  system is closed and exited. If not, tests are done to see whether the Alt
  or Ctrl Key was down along with one of the keys 1,2,,,0. If so, the Scan
  Code of the keys 1,2,...,0 is then decremented by two so that ScanCode*10
  acts as an index into either of the structures based on ExecOnKB where
  information from the file hook_kb.dat is stored.

  Depending on the key combination struck, the address of the program, address
  of the command line parameters and the Session Type for the Key Combination
  identified in the message is obtained and inserted into the StartData
  structure required for the function. DosStartSession is then called with
  appropriate parameters.

  Note that WinSetFocus is called before DosStartSession. The programs started
  by DosStartSession will not be in the foreground unless the program calling
  DosStartSession is in the foreground and it seems reasonable that programs
  called with a "HotKey" want to be in the foreground.

  The four procedures at the very end are just routines used by parts of the
  code in the program.

  It should be noted that hook_kb can be adopted to other uses. Hook_dll can
  be used unchanged but by making appropriate changes to hook_kb.asm, you can
  tailor it to your needs. In the listing of the program flow, comments
  indicate code sections that are optional for customization for other
  requirements.

  I have found this program very useful, particularly with respect to programs
  using COM ports. Since OS/2 will not allow you to have two programs open at
  the same time that use the same COM port, this affords a rapid means of
  serially accessing programs sharing a common COM port. Another use I have
  found effective is to assign MENUS to some of the Hot Keys. In my sample
  hook_kb.dat file, the assignment to Alt-5, "loadq", is a CMD file that
  displays a menu for editing a variety of different files. You can readily
  assign any program assigned to an ICON to a hot key, presuming the program
  has an executable form or can be called as a parameter to another program.
  But by far I have found it an efficient expediter for rapidly accessing
  programs without changing anything on your DeskTop.

  As it was with TSR's in DOS, you must be careful of your assignments so that
  required keys in programs are not made unavailable. That stricture was
  reflected in my choice of keys to assign and reflects my particular
  concerns. A natural question to ask is - are there any problems with other
  programs that may be sampling the system message queue? Two such programs
  that I am aware of are CMDLINE and KWIKINF. CMDLINE is a commercial program
  that hooks the Keyboard and KWIKINF which also hooks the Keyboard is a
  program included with IBM's Toolkit - it offers a quick search facility.

  I have observed no problems with HOOK_KB loaded and both CMDLINE and KWIKINF
  also loaded.