Implementing a Windows Keyboard Hook in Python Using ctypes

We introduce the concept of Windows hooks (Hook) and explain how they can be used to monitor system events, focusing on low‑level keyboard input (WH_KEYBOARD_LL) as a demonstration case.

The required DLLs are user32.dll for user‑interface functions and kernel32.dll for memory management and I/O operations.

1. Register Hook

Using SetWindowsHookExA from user32.dll , we register a hook with parameters such as idHook , lpfn , hmod , and dwThreadId . The ctypes library allows Python to call this function.

<code>from ctypes import CDLL
user32 = CDLL("user32.dll")
kernel32 = CDLL("kernel32.dll")
user32.SetWindowsHookExA(13, handleProc, kernel32.GetModuleHandleW(), 0)</code>

2. Write Hook Function

The hook procedure processes keyboard messages; it checks wParam and lParam to detect key presses, handle Ctrl, CapsLock, and print characters.

<code>def hookProc(nCode, wParam, lParam):
    if nCode < 0:
        return user32.CallNextHookEx(hooked, nCode, wParam, lParam)
    else:
        if wParam == 256:
            if 162 == lParam.contents.value:
                print("Ctrl pressed, call Hook uninstall()")
                uninstallHookProc(hooked)
                sys.exit(-1)
            capsLock = user32.GetKeyState(20)
            if lParam.contents.value == 13:
                print("\n")
            elif capsLock:
                print(chr(lParam.contents.value), end="")
            else:
                print(chr(lParam.contents.value + 32), end="")
    return user32.CallNextHookEx(hooked, nCode, wParam, lParam)</code>

3. Delete Hook

When the program exits, UnhookWindowsHookEx from user32.dll removes the hook to avoid performance issues.

<code>def uninstallHookProc(hooked):
    if hooked is None:
        return
    user32.UnhookWindowsHookEx(hooked)
    hooked = None</code>

4. Declare Prototype

Using WINFUNCTYPE from ctypes , we declare the C‑style function prototype so Windows can call the Python hook.

<code># Create declaration, c_int is the return type
HOOKPROC = WINFUNCTYPE(c_int, c_int, c_int, POINTER(DWORD))
handleProc = HOOKPROC(hookProc)</code>

5. Full Example Code

The complete script (under 100 lines) imports sys and ctypes , defines structures, registers the hook, runs a message loop, and cleans up on interruption.

<code>import sys
from ctypes import *
from ctypes.wintypes import DWORD, HHOOK, HINSTANCE, MSG, WPARAM, LPARAM

user32 = CDLL("user32.dll")
kernel32 = CDLL("kernel32.dll")

class KBDLLHOOKSTRUCT(Structure):
    _fields_ = [
        ('vkCode', DWORD),
        ('scanCode', DWORD),
        ('flags', DWORD),
        ('time', DWORD),
        ('dwExtraInfo', DWORD)
    ]

# ... (functions uninstallHookProc, hookProc, startKeyLog, installHookProc as shown above) ...

HOOKPROC = WINFUNCTYPE(c_int, c_int, c_int, POINTER(DWORD))
pointer = HOOKPROC(hookProc)
hooked = None
if installHookProc(hooked, pointer):
    print("Hook installed")
    try:
        msg = MSG()
        user32.GetMessageA(byref(msg), 0, 0, 0)
    except KeyboardInterrupt:
        uninstallHookProc(hooked)
        print("Hook uninstall...")
else:
    print("Hook installed error")</code>

Running this script on a Windows machine will display captured keystrokes in the console; the hook is automatically removed when the program ends.