SetWindowsHook

Syntax

FARPROC SetWindowsHook(nFilterType,lpFilterFunc)

This function installs a filter function in a chain. A filter function processes events before they are sent to an application's message loop in the WinMain function. A chain is a linked list of filter functions of the same type.

Return Value

The return value points to the procedure-instance address of the previously installed filter (if any). It is NULL if there is no previous filter. The application or library that calls the SetWindowsHook function should save this return value in the library's data segment. The fourth argument of the DefHookProc function points to the location in memory where the library saves this return value.

The return value is –1 if the function fails.

Comments

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

The system hooks are a shared resource. Installing a hook affects all applications. Most hook functions must be in libraries. The only exception is WH_MSGFILTER, which is task-specific. System hooks should be restricted to special-purpose applications or as a development aid during debugging of an application. Libraries that no longer need the hook should remove the filter function.

To install a filter function, the SetWindowsHook 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 MakeProcInstance to get a procedure-instance address. Dynamic-link libraries must use GetProcAddress to get a procedure-instance address.

The following section describes how to support the individual hook functions.

WH_CALLWNDPROC

Windows calls the WH_CALLWNDPROC filter function whenever the SendMessage function is called. Windows does not call the filter function when the PostMessage function is called.

The filter function must use the Pascal calling convention and must be declared FAR. The filter function must have the following form:

Filter Function

DWORD FAR PASCAL FilterFunc(nCode, wParam, lParam)
int nCode;
WORD wParam;
DWORD lParam;

FilterFunc is a placeholder for the application- or library-supplied function name. The actual name must be exported by including it in an EXPORTS statement in the library's module-definition file.

Comments

The WH_CALLWNDPROC filter function can examine or modify the message as desired. Once it returns control to Windows, the message, with any modifications, is passed on to the window function. The filter function does not require a return value.

WH_GETMESSAGE

Windows calls the WH_GETMESSAGE filter function whenever the GetMessage function is called. Windows calls the filter function immediately after GetMessage has retrieved a message from an application queue. The filter function must use the Pascal calling convention and must be declared FAR. The filter function must have the following form:

Filter Function

DWORD FAR PASCAL FilterFunc(nCode, wParam, lParam)
int nCode;
WORD wParam;
DWORD lParam;

FilterFunc is a placeholder for the library-supplied function name. The actual name must be exported by including it in an EXPORTS statement in the library's module-definition file.

Comments

The WH_GETMESSAGE filter function can examine or modify the message as desired. Once it returns control to Windows, the GetMessage function returns the message, with any modifications, to the application that originally called it. The filter function does not require a return value.

WH_JOURNALPLAYBACK

Windows calls the WH_JOURNALPLAYBACK filter function whenever a request for an event message is made. The function is intended to be used to supply a previously recorded event message.

The filter function must use the Pascal calling convention and must be declared FAR.
The filter function must have the following form:

Filter Function

DWORD FAR PASCAL FilterFunc(nCode, wParam, lParam);
int nCode;
WORD wParam;
DWORD lParam;

FilterFunc is a placeholder for the library-supplied function name. The actual name must be exported by including it in an EXPORTS statement in the library's module-definition file.

Comments

The WH_JOURNALPLAYBACK function should copy an event message to the lParam parameter. The message must have been previously recorded by using the WH_JOURNALRECORD filter. It should not modify the message. The return value should be the amount of time (in clock ticks) Windows should wait before processing the message. This time can be computed by calculating the difference between the time fields in the current and previous event messages. If the function returns zero, the message is processed immediately. Once it returns control to Windows, the message continues to be processed. If the nCode parameter is HC_SKIP, the filter function should prepare to return the next recorded event message on its next call.

While the WH_JOURNALPLAYBACK function is in effect, Windows ignores all mouse and keyboard input.

WH_JOURNALRECORD

Windows calls the WH_JOURNALRECORD filter function whenever it processes a message from the event queue. The filter can be used to record the event for later playback.

The filter function must use the Pascal calling convention and must be declared FAR. The filter function must have the following form:

Filter Function

DWORD FAR PASCAL FilterFunc(nCode, wParam,lParam);
int nCode;
WORD wParam;
DWORD lParam;

FilterFunc is a placeholder for the library-supplied function name. The actual name must be exported by including it in an EXPORTS statement in the library's module-definition file.

Comments

The WH_JOURNALRECORD function should save a copy of the event message for later playback. It should not modify the message. Once it returns control to Windows, the message continues to be processed. The filter function does not require a return value.

WH_KEYBOARD

Windows calls the WH_KEYBOARD filter function whenever the application calls the GetMessage or PeekMessage function and there is a keyboard event (WM_KEYUP or WM_KEYDOWN) to process.

The filter function must use the Pascal calling convention and must be declared FAR. The filter function must have the following form:

Filter Function

DWORD FAR PASCAL FilterFunc(nCode, wParam, lParam)
int nCode;
WORD wParam;
DWORD lParam;

FilterFunc is a placeholder for the library-supplied function name. The actual name must be exported by including it in an EXPORTS statement in the library's module-definition file.

Return Value

The return value specifies what should happen to the message. It is zero if the message should be processed by Windows; it is 1 if the message should be discarded.

WH_MSGFILTER

Windows calls the WH_MSGFILTER filter function whenever a dialog box, message box, or menu has retrieved a message, and before it has processed that message. The filter allows an application to process or modify the messages.

NOTE:

This is the only task-specific filter. A task may install this filter.

The WH_MSGFILTER filter function must use the Pascal calling convention and must be declared FAR. The filter function must have the following form:

Filter Function

DWORD FAR PASCAL FilterFunc(nCode, wParam, lParam )
int nCode;
WORD wParam;
DWORD lParam;

FilterFunc is a placeholder for the library- or application-supplied function name. The actual name must be exported by including it in an EXPORTS statement in the application's module-definition file.

Return Value

The return value specifies the outcome of the function. It is nonzero if the hook function processes the message. Otherwise, it is zero.

WH_SYSMSGFILTER

Windows calls the WH_SYSMSGFILTER filter function whenever a dialog box, message box, or menu has retrieved a message and before it has processed that message. The filter allows an application to process or modify messages for any application in the system.

The filter function must use the Pascal calling convention and must be declared FAR.
The filter function must have the following form:

Filter Function

DWORD FAR PASCAL FilterFunc(nCode, wParam, lParam )
int nCode;
WORD wParam;
DWORD lParam;

FilterFunc is a placeholder for the library-supplied function name. The actual name must be exported by including it in an EXPORTS statement in the library's module-definition file.

Return Value

The return value specifies the outcome of the function. It is nonzero if the hook function processes the message. Otherwise, it is zero.