SetWindowsHookEx

3.1

HHOOK SetWindowsHookEx(idHook, hkprc, hinst, htask)
int idHook;	/* type of hook to install	*/
HOOKPROC hkprc;	/* procedure-instance address of filter function	*/
HINSTANCE hinst;	/* handle of application instance	*/
HTASK htask;	/* task to install the hook for	*/

The SetWindowsHookEx function installs an application-defined hook function into a hook chain. This function is an extended version of the SetWindowsHook function.

Parameters

idHook

Specifies the type of hook to be installed. This parameter can be one of the following values:

Value

Meaning

WH_CALLWNDPROC	Installs a window-procedure filter. For more information, see the description of the CallWndProc callback function.
WH_CBT	Installs a computer-based training (CBT) filter. For more information, see the description of the CBTProc callback function.
WH_DEBUG	Installs a debugging filter. For more information, see the description of the DebugProc callback function.
WH_GETMESSAGE	Installs a message filter. For more information, see the description of the GetMsgProc callback function.
WH_HARDWARE	Installs a nonstandard hardware-message filter. For more information, see the description of the HardwareProc callback function.
WH_JOURNALPLAYBACK	Installs a journaling playback filter. For more information, see the description of the JournalPlaybackProc callback function.
WH_JOURNALRECORD	Installs a journaling record filter. For more information, see the description of the JournalRecordProc callback function.
WH_KEYBOARD	Installs a keyboard filter. For more information, see the description of the KeyboardProc callback function.
WH_MOUSE	Installs a mouse-message filter. For more information, see the description of the MouseProc callback function.
WH_MSGFILTER	Installs a message filter. For more information, see the description of the MessageProc callback function.
WH_SYSMSGFILTER	Installs a system-wide message filter. For more information, see the description of the SysMsgProc callback function.

hkprc

Specifies the procedure-instance address of the application-defined hook procedure to be installed.

hinst

Identifies the instance of the module containing the hook function.

htask

Identifies the task for which the hook is to be installed. If this parameter is NULL, the installed hook function has system scope and may be called in the context of any process or task in the system.

Return Value

The return value is a handle of the installed hook, if the function is successful. The application or library must use this handle to identify the hook when it calls the CallNextHookEx and UnhookWindowsHookEx functions. The return value is NULL if an error occurs.

Comments

An application or library can use the GetCurrentTask or GetWindowTask function to obtain task handles for use in hooking a particular task.

Hook procedures used with SetWindowsHookEx must be declared as follows:

DWORD CALLBACK HookProc(code, wParam, lParam)
int code;
WPARAM wParam;
LPARAM lParam;
{
    if (...)
        return CallNextHookEx(hhook, code, wParam, lParam);
}

Chaining to the next hook procedure (that is, calling the CallNextHookProc function) is optional. An application or library can call the next hook procedure either before or after any processing in its own hook procedure.

Before terminating, an application must call the UnhookWindowsHookEx function to free system resources associated with the hook.

Some hooks may be set with system scope only, and others may be set only for a specific task, as shown in the following list:

Hook

Scope

WH_CALLWNDPROC	Task or system
WH_CBT	Task or system
WH_DEBUG	Task or system
WH_GETMESSAGE	Task or system
WH_HARDWARE	Task or system
WH_JOURNALRECORD	System only
WH_JOURNALPLAYBACK	System only
WH_KEYBOARD	Task or system
WH_MOUSE	Task or system
WH_MSGFILTER	Task or system
WH_SYSMSGFILTER	System only

For a given hook type, task hooks are called first, then system hooks.

The WH_CALLWNDPROC hook affects system performance. It is supplied for debugging purposes only.

The system hooks are a shared resource. Installing one affects all applications. All system hook functions must be in libraries. System hooks should be restricted to special-purpose applications or to use as a development aid during debugging of an application. Libraries that no longer need the hook should remove the filter function.

It is a good idea for several reasons to use task hooks rather than system hooks: They do not incur a system-wide overhead in applications that are not affected by the call (or that ignore the call); they do not require packaging the hook-procedure implementation in a separate dynamic-link library; they will continue to work even when future versions of Windows prevent applications from installing system-wide hooks for security reasons.

To install a filter function, the SetWindowsHookEx function must receive a procedure-instance address of the function and the function must be exported in the library's module-definition file. Libraries can pass the procedure address directly. Tasks must use the MakeProcInstance function to get a procedure-instance address. Dynamic-link libraries must use the GetProcAddress function to get a procedure-instance address.

For a given hook type, task hooks are called first, then system hooks.

The WH_SYSMSGFILTER hooks are called before the WH_MSGFILTER hooks. If any of the WH_SYSMSGFILTER hook functions return TRUE, the WH_MSGFILTER hooks are not called.