Low-level Windows API hooks from C# to stop unwanted keystrokes

• Download source files - 3.37 Kb
• Download demo project (VS 2005) - 19.7 Kb
• Download demo project (VS 2003) - 12.5 KB

Introduction

Cats and babies have a lot in common. They both like eating the house plants, and share the same hatred of closed doors. They also love using keyboards, with the result that the important email you were sending to your boss is dispatched in mid-sentence, your accounts in Excel are embellished with four rows of gobbledygook, and your failure to notice that Windows Explorer was open results in several files moving to the Recycle Bin.

The solution is an application which you can switch to as soon as the keyboard is under threat, and which will ensure that any keyboard activity is harmless. This article illustrates how the keyboard can be neutralized in a C# application using a low-level Windows API hook.

Background

There are a number of articles and code samples regarding hooks in Windows, and some of them are listed at the end of this article. Neutralizing the keyboard when children are around must be a common need -- someone here wrote almost exactly the same thing in C++[^]! However, when I was looking for source code to create my application, I found very few .NET examples, and none that involved a self-contained class in C#.

The .NET framework gives managed access to the keyboard events you'll need for most ordinary uses through KeyPress, KeyUp and KeyDown. Unfortunately, these events can't be used to stop Windows from processing key combinations like Alt+Tab or the Windows Start key, which allow users to navigate away from an application. The conveniently placed Windows key in particular was irresistible to my baby son!

The solution is to catch the keyboard events at the operating system level rather than through the framework. To do this, the application needs to use Windows API functions to add itself to the "hook chain" of applications listening for keyboard messages from the operating system. When it receives this type of message, the application can selectively pass the message on, as it normally should, or suppress it so that no further applications -- including Windows -- can act on it. This article explains how.

Please note, however, that this code only applies to NT-based versions of Windows (NT, 2000 and XP), and that it isn't possible to use this method to disable Ctrl+Alt+Delete (suggestions on how to do that can be found in this MSDN Magazine Q&A[^]).

Using the code

For ease of use, I have attached three separate zip files to this article. One contains only the KeyboardHook class which is the main focus of this article. The others are complete projects for an application called "Baby Keyboard Bash" which displays the keys' names or coloured shapes in response to keystrokes. For ease of use, I have included two projects, one for Microsoft Visual C# 2005 Express Edition and one for Visual Studio 2003.

Instantiating the class

The keyboard hook is set up and handled by the KeyboardHook class in keyboard.cs. This class implements IDisposable, so the simplest way to instantiate it is to use the using keyword in the application's Main() method, to enclose the Application.Run() call. This will ensure that the hook is set up as soon as the application starts and, more importantly, is disabled as the application shuts down.

The class raises an event to warn the application that a key has been pressed, so it is important for the main form to have access to the instance of KeyboardHook created in the Main() method; the simplest solution is to store this instance in a public member variable. In a Visual Studio 2003 project, this will usually go in the Form1 class (or whatever the application's main class is called), and in Visual Studio 2005, in the Program class in Program.cs.

KeyboardHook has three constructors to enable or disable certain settings:

• KeyboardHook(): traps all keystrokes, passing nothing to Windows or other applications.
• KeyboardHook(string param): Converts the string to one of the values in the Parameters enum and then calls the following constructor:
• KeyboardHook(KeyboardHook.Parameters enum): Depending on the value selected from the Parameters enum, the following settings can be enabled:
  • Parameters.AllowAltTab: allows the user to switch to other applications using Alt+Tab.
  • Parameters.AllowWindowsKey: allows the user to access the taskbar and Start menu using Ctrl+Esc or one of the Windows keys.
  • Parameters.AllowAltTabAndWindows: enables Alt+Tab, Ctrl+Esc and the Windows keys.
  • Parameters.PassAllKeysToNextApp: if the parameter is true, all keystrokes will be passed to any other listening applications, including Windows.

Enabling Alt+Tab and/or the Windows keys allows the person who is actually using the computer to switch to another application and interact with it using the mouse while keystrokes continue to be trapped by the keyboard hook. The PassAllKeysToNextApp setting effectively disables the keystroke trapping; the class will still set up a low-level keyboard hook and raise its KeyIntercepted event, but it will also pass the keyboard events to other listening applications.

The simplest way to instantiate the class to trap all keystrokes is therefore:

public static KeyboardHook kh;

[STAThread]
static void Main()
{
  //Other code
  using (kh = new KeyboardHook())
  {
    Application.Run(new Form1());
  }

Handling the KeyIntercepted event

When a key is pressed, the KeyboardHook class raises a KeyIntercepted event containing some KeyboardHookEventArgs. This needs to be handled by a method of the type KeyboardHookEventHandler, which can be set up as follows:

kh.KeyIntercepted += new KeyboardHook.KeyboardHookEventHandler(kh_KeyIntercepted);

The KeyboardHookEventArgs returns the following information on the key that was pressed:

• KeyName: the key's name, obtained by casting the trapped key code to System.Windows.Forms.Keys.
• KeyCode: the original key code returned by the keyboard hook
• PassThrough: whether this instance of KeyboardHook is configured to allow this keystroke through to other applications. Checking this is useful if you want to allow a user to switch to another application using Alt+Tab or Ctrl+Esc/Windows keys.

A method with the appropriate signature can then be used to perform whatever tasks the keystroke calls for. Here is an example from the enclosed sample application:

void kh_KeyIntercepted(KeyboardHookEventArgs e)
{
  //Check if this key event is being passed to
  //other applications and disable TopMost in 
  //case they need to come to the front
  if (e.PassThrough)
  {
    this.TopMost = false;
  }
  ds.Draw(e.KeyName);
}

The rest of this article explains how the low-level keyboard hook is implemented in KeyboardHook.

Implementing a low-level Windows API keyboard hook

The Windows API contains three methods in user32.dll that are useful for this purpose:

• SetWindowsHookEx, which sets up the keyboard hook
• UnhookWindowsHookEx, which removes the keyboard hook
• CallNextHookEx, which passes the keystroke information to the next application listening for keyboard events

The key to creating an application which can hijack the keyboard is to implement the first two methods, and forgo the third. The result is that any keys pressed go no further than the application.

In order to achieve this, the first step is to include the System.Runtime.InteropServices namespace and import the API methods, starting with SetWindowsHookEx:

using System.Runtime.InteropServices
...
//Inside class:

[DllImport("user32.dll", CharSet = CharSet.Auto, SetLastError = true)]
private static extern IntPtr SetWindowsHookEx(int idHook,
  LowLevelKeyboardProc lpfn, IntPtr hMod, uint dwThreadId);

The code to import UnhookWindowsHookEx and CallNextHookEx is listed in the sections concerning those methods further in this article.

The next step is to call SetWindowsHookEx to set up the hook, passing the following four parameters:

• idHook: This number determines the type of hook to be set up. For example, SetWindowsHookEx can also be used to hook into mouse events; a complete list can be found on MSDN[^]. In this case, we're only interested in number 13, which is the keyboard hook's id. To make the code more legible, this has been assigned to the constant WH_KEYBOARD_LL.
• lpfn: A long pointer to the function that will handle the keyboard events. In C#, the "pointer" is achieved by passing an instance of a delegate type, referring to the appropriate method. This is the method that will be called every time the hook is used.
  An important point to note here is that the delegate instance needs to be stored in a member variable in the class. This is to prevent it being garbage collected as soon as the first method call ends.
• hMod: An instance handle for the application which is setting up the hook. Most of the samples I found simply set this to IntPtr.Zero, on the grounds that it is unlikely that there will be more than one instance of the application. However, this code uses GetModuleHandle from kernel32.dll to identify the exact instance to make the class potentially more flexible.
• dwThreadId: The ID of the current thread. Setting this to 0 makes the hook global, which is the appropriate setting for a low-level keyboard hook.

SetWindowsHookEx returns a hook ID which will be used to unhook the application when it shuts down, so this needs to be stored in a member variable for future use. The relevant code from the KeyboardHook class is as follows:

private HookHandlerDelegate proc;
private IntPtr hookID = IntPtr.Zero;
private const int WH_KEYBOARD_LL = 13;


public KeyboardHook()
{
  proc = new HookHandlerDelegate(HookCallback);
  using (Process curProcess = Process.GetCurrentProcess())
  using (ProcessModule curModule = curProcess.MainModule)
  {
     hookID = SetWindowsHookEx(WH_KEYBOARD_LL, proc,
                    GetModuleHandle(curModule.ModuleName), 0);
  }
}

Processing keyboard events

As mentioned above, SetWindowsHookEx requires a pointer to the callback function that will be used to process the keyboard events. It expects a function with the following signature:

LRESULT CALLBACK LowLevelKeyboardProc
(   int nCode,
    WPARAM wParam,
    LPARAM lParam
);

The C# method for setting up a "pointer to a function" is to use a delegate, so the first step in giving SetWindowsHookEx what it needs is to declare a delegate with the right signature:

    private delegate IntPtr HookHandlerDelegate(
        int nCode, IntPtr wParam, ref KBDLLHOOKSTRUCT lParam);

And then write a callback method with the same signature; this method will contain all the code that actually processes the keyboard event. In the case of KeyboardHook, it checks whether the keystroke should be passed to other applications and then raises the KeyIntercepted event. Here is a simplified version without the keystroke handling code:

private const int WM_KEYUP = 0x0101;
private const int WM_SYSKEYUP = 0x0105;

private IntPtr HookCallback(int nCode, IntPtr wParam, ref KBDLLHOOKSTRUCT lParam)
{
  //Filter wParam for KeyUp events only - otherwise this code
  //will execute twice for each keystroke (ie: on KeyDown and KeyUp)
  //WM_SYSKEYUP is necessary to trap Alt-key combinations
  if (nCode >= 0)
  { 
      if (wParam == (IntPtr)WM_KEYUP || wParam == (IntPtr)WM_SYSKEYUP)
      {
        //Raise the event
        OnKeyIntercepted(new KeyboardHookEventArgs(lParam.vkCode, AllowKey));
      }
      //Return a dummy value to trap the keystroke
      return (System.IntPtr)1;
  }
  //The event wasn't handled, pass it to next application
  return CallNextHookEx(hookID, nCode, wParam, ref lParam);
}

A reference to HookCallback is then assigned to an instance of HookHandlerDelegate and passed in the call to SetWindowsHookEx, as illustrated in the previous section.

Whenever a keyboard event occurs, the following parameters will be passed to HookCallBack:

• nCode: According to the MSDN documentation[^], the callback function should return the result of CallNextHookEx if this value is less than zero. Normal keyboard events will return an nCode of 0 or more.

• wParam: This value indicates what type of event occurred: key up or key down, and whether the key pressed was a system key (left or right-hand Alt keys).

• lParam: A structure to store precise information on the keystroke, such as the code of the key which was pressed. The structure declared in KeyboardHook is as follows:

private struct KBDLLHOOKSTRUCT
{ 
  public int vkCode;
  int scanCode;
  public int flags;
  int time;
  int dwExtraInfo;
}

The two public parameters are the only ones used by the callback method in KeyboardHook. vkCoke returns the virtual key code, which can be cast to System.Windows.Forms.Keys to obtain the key's name, while flags indicates if this is an extended key (the Windows Start key, for instance) or if the Alt key was pressed at the same time. The complete code for the HookCallback method illustrates which flags values to check for in each case.

If the information provided by flags and the other components of the KBDLLHOOKSTRUCT are not needed, the signature of the callback method and delegate can be changed as follows:

private delegate IntPtr HookHandlerDelegate(
        int nCode, IntPtr wParam, IntPtr lParam);

In this case, lParam will return only the vkCode.

Passing keystrokes to the next application

A well-behaved keyboard hook callback method should end by calling the CallNextHookEx function and returning its result. This ensures that other applications get a chance to handle the keystrokes destined for them.

However, the key functionality of the KeyboardHook class is preventing keystrokes from being propagated to any further applications. So whenever it processes a keystroke, HookCallback returns a dummy value instead:

return (System.IntPtr)1;

On the other hand, it does call CallNextHookEx if it didn't handle the event, or if the parameter passed with KeyboardHook's overloaded constructor allows certain key combinations through.

CallNextHookEx is enabled by importing the function from user32.dll as shown in the following code:

[DllImport("user32.dll", CharSet = CharSet.Auto, SetLastError = true)]
private static extern IntPtr CallNextHookEx(IntPtr hhk, int nCode,
  IntPtr wParam, ref KeyInfoStruct lParam);

The imported method is then called by this line in the HookCallback method, which ensures that all the parameters received through the hook are passed on to the next application:

CallNextHookEx(hookID, nCode, wParam, ref lParam);

As mentioned before, if the flags in lParam are not relevant, the signature for the imported CallNextHookEx can be changed to define lParam as System.IntPtr.

Removing the hook

The last step in processing the hook is to remove it when the instance of the KeyboardHook class is destroyed, using the UnhookWindowsHookEx function imported from user32.dll as follows.

[DllImport("user32.dll", CharSet = CharSet.Auto, SetLastError = true)]
[return: MarshalAs(UnmanagedType.Bool)]
private static extern bool UnhookWindowsHookEx(IntPtr hhk);

Since KeyboardHook implements IDisposable, this can be done in the Dispose method.

public void Dispose()
{
  UnhookWindowsHookEx(hookID);
}

hookID is the id returned by the call to SetWindowsHookEx in the constructor. This removes the application from the hook chain.

Sources

Here are some good sources on Windows hooks in C# and in general:

• A good C# console application sample can be found in Stephen Toub's MSDN blog[^]
• For information on Windows API hooks in general, see MSDN's article on SetWindowsHookEx[^] and its related links
• A Code Project article[^] on a class for global hook in C#, which illustrates how to set up the other available hooks, including for mouse activity.

It seems that articles in any language seem to attract at least one response on the lines of "how do I do the same thing in (some other language)?", so here are some samples I found:

• A keyboard hook sample in VB6[^]
• A sample and article on the same thing in VB.NET[^]
• And again in C++[^] as part of a project with exactly the same aim as this one!

And nothing to do with Windows API hooks or C#, but I would like to recommend Mike Ellison's excellent Word 2003 template if you're ever planning to write an article for Code Project!

History

• 1.4 (23 Mar 07) - Fixed a bug which made Alt key appear stuck when the program exited:
  • Changed
    if (nCode >= 0 && (wParam == (IntPtr)WM_KEYUP || wParam == (IntPtr)WM_SYSKEYUP))
    to
    

    if (nCode >= 0)<br />
    {<br />
      if (wParam == (IntPtr)WM_KEYUP || wParam == (IntPtr)WM_SYSKEYUP)

    
    Many thanks to "Scottie Numbnuts" for the solution.

• 1.3 (13 Feb 07) - Improved modifier key support:
  • Added CheckModifiers() method
  • Deleted LoWord/HiWord methods as they weren't necessary
  • Implemented Barry Dorman's suggestion to AND GetKeyState values with 0x8000 to get their result
• 1.2 (10 Jul 06) - Added support for modifier keys:
  • Changed filter in HookCallback to WM_KEYUP instead of WM_KEYDOWN
  • Imported GetKeyState from user32.dll
  • Moved native DLL imports to a separate internal class as this is a Good Idea according to Microsoft's guidelines
• 1.1 (18 Jun 06) - Modified proc assignment in constructor to make class backward compatible with 2003.
• 1.0 (17 Jun 06) - First version published on Code Project.