WinAPI 鉤子回調：DebugProc 詳細解析

DebugProc 回調函數

DebugProc 配合 WH_DEBUG 鉤子類型，是一種特殊的診斷用鉤子。它在其他任何鉤子回調被呼叫之前先行執行，允許除錯器監控、記錄、甚至修改鉤子鏈的行為。

函數原型

function DebugProc(
  nCode: Integer;    // 鉤子代碼
  wParam: WPARAM;    // 即將被呼叫的鉤子類型 (idHook)
  lParam: LPARAM     // 指向該鉤子回調參數的結構體
): LRESULT; stdcall;

參數深度解析

• nCode：HC_ACTION (0) 表示即將呼叫下一個鉤子；負值直接傳遞。
• wParam：下一個將被執行的鉤子類型常數 (如 WH_KEYBOARD=2, WH_MOUSE=7 等)。
• lParam：指向該鉤子回調函數原始參數的結構體指標。例如下一個是 WH_KEYBOARD，則 lParam 指向包含 nCode, wParam, lParam 的結構。

核心用途

1. 鉤子鏈監控/記錄：記錄系統呼叫了哪些鉤子、順序、參數，診斷鉤子衝突、死結、效能問題。
2. 條件式攔截：根據鉤子類型或參數決定是否允許繼續執行 (返回非零阻止)。
3. 除錯器實現：Visual Studio、Delphi IDE 內部除錯器即利用此機制實現「中斷在鉤子」功能。

部署限制

• 系統級 (dwThreadId=0) 必須在 DLL，且需管理員權限。
• 線程級 (dwThreadId>0) 可在 EXE，僅監控該線程的鉤子鏈。
• 極高權限要求：安裝 WH_DEBUG 需 SE_DEBUG_PRIVILEGE，普通應用通常無法安裝系統級 Debug 鉤子。

效能與風險警示

• 嚴重效能影響：每個鉤子呼叫前都會先經過 DebugProc，系統級安裝會使全系統鉤子開銷倍增。
• 遞歸風險：DebugProc 內若觸發其他鉤子 (如 OutputDebugString 可能觸發 WH_DEBUG 又觸發 WH_GETMESSAGE)，極易造成堆疊溢位。
• 生產環境禁用：僅限開發/測試/除錯工具使用，正式發布產品絕不可 安裝此鉤子。

簡易監控範例 (線程級，僅供學習)

unit DebugHookDemo;
interface
uses Windows;
var hDebugHook: HHOOK = 0;

function DebugProc(nCode: Integer; wParam: WPARAM; lParam: LPARAM): LRESULT; stdcall;
var HookName: string;
begin
  if nCode = HC_ACTION then
  begin
    // 將鉤子類型常數轉為可讀名稱
    case wParam of
      WH_MSGFILTER: HookName := 'WH_MSGFILTER';
      WH_JOURNALRECORD: HookName := 'WH_JOURNALRECORD';
      WH_JOURNALPLAYBACK: HookName := 'WH_JOURNALPLAYBACK';
      WH_KEYBOARD: HookName := 'WH_KEYBOARD';
      WH_GETMESSAGE: HookName := 'WH_GETMESSAGE';
      WH_CALLWNDPROC: HookName := 'WH_CALLWNDPROC';
      WH_CBT: HookName := 'WH_CBT';
      WH_SYSMSGFILTER: HookName := 'WH_SYSMSGFILTER';
      WH_MOUSE: HookName := 'WH_MOUSE';
      WH_HARDWARE: HookName := 'WH_HARDWARE';
      WH_DEBUG: HookName := 'WH_DEBUG (recursive!)';
      WH_SHELL: HookName := 'WH_SHELL';
      WH_FOREGROUNDIDLE: HookName := 'WH_FOREGROUNDIDLE';
      WH_CALLWNDPROCRET: HookName := 'WH_CALLWNDPROCRET';
    else HookName := Format('Unknown(%d)', [wParam]);
    end;
    OutputDebugString(PChar(Format('[DebugHook] Next hook: %s', [HookName])));
  end;
  Result := CallNextHookEx(hDebugHook, nCode, wParam, lParam);
end;

procedure InstallDebugHook(ThreadId: DWORD);
begin
  hDebugHook := SetWindowsHookEx(WH_DEBUG, @DebugProc, HInstance, ThreadId);
end;

procedure UninstallDebugHook;
begin
  if hDebugHook <> 0 then UnhookWindowsHookEx(hDebugHook);
end;
implementation
end.

現代除錯替代方案

• Event Tracing for Windows (ETW)：系統級高效能追蹤，可捕獲鉤子相關事件
• Windows Performance Recorder (WPR) / Analyzer (WPA)：視覺化分析鉤子開銷
• Application Verifier：偵測鉤子濫用、洩漏、死結
• Delphi IDE 斷點/事件日誌：應用層除錯無需核心鉤子

總結

WH_DEBUG 是「鉤子的鉤子」，極其強大但極其危險。僅供專業除錯工具、系統監控代理、安全軟體在受控環境使用。應用開發者應完全避開，改用上層框架提供的診斷機制。