CheckMsgFilterHook

This hook is called whenever WinGetMsg, WinWaitMsg, or WinPeekMsg are used to filter message identities.

Syntax

CheckMsgFilterHook(hab, pQmsg, usFirst, usLast, fOptions);

Parameters

hab (HAB) - input

Anchor-block handle.

pQmsg (PQMSG) - input

Pointer to the QMSG structure of the message currently being reviewed.

usFirst (ULONG) - input

First message identity specified on a call to the WinGetMsg, WinPeekMsg or WinWaitMsg function.

usLast (ULONG) - input

Last message identity specified on a call to the WinGetMsg, WinPeekMsg or WinWaitMsg function.

fOptions (ULONG) - input

Message removal options.

PM_REMOVE Message is being removed from queue

PM_NOREMOVE Message is not being removed from queue

Returns

rc (BOOL) - returns

Processing indicator.

TRUE: The message is accepted by the filtering. Any further Check Message Filter Hooks in the chain are ignored, any filtering specified by the ulFirst and ulLast parameters of the WinGetMsg, WinPeekMsg or WinWaitMsg functions are ignored, and processing of the message continues.

A hook that always returns TRUE effectively switches off message filtering.

FALSE: The message is passed on to the next Check Message Filter Hook in the chain. If the end of the chain has been reached, the filtering specified by the ulFirst and ulLast parameters of the WinGetMsg, WinPeekMsg or WinWaitMsg functions is applied.

Remarks

This hook enables an application to apply a very specific message filtering, for example, based on the values of message parameters.

This hook is called after window handle filtering and before message filtering. Window handle filtering is controlled by the hwndFilter parameter of the WinGetMsg or WinPeekMsg functions. Message filtering is controlled by the ulFirst and ulLast parameters of the WinGetMsg, WinPeekMsg or WinWaitMsg functions.

This hook is called if the message passes window handle filtering and if non-null message filtering is specified. This means that, on entry to this hook:

• The hwndFilter parameter of the WinGetMsg or WinPeekMsg function is either NULLHANDLE or it specifies the window (or a parent of the window) referenced in the pQmsg structure.
• At least one of the usFirst and usLast parameters are nonzero.
• The msg field of the pQmsg structure might or might not lie inside the range specified by the usFirst and usLast parameters.

Example Code

#define INCL_WINHOOKS /* Or use INCL_WIN, INCL_PM, */
#include <os2.h>

HAB     hab;      /* Anchor-block handle. */
PQMSG   pQmsg;    /* Pointer to the QMSG structure of the message currently being reviewed. */
ULONG   usFirst;  /* First message identity specified on a call to the WinGetMsg, WinPeekMsg or WinWaitMsg function. */
ULONG   usLast;   /* Last message identity specified on a call to the WinGetMsg, WinPeekMsg or WinWaitMsg function. */
ULONG   fOptions; /* Message removal options. */
BOOL    rc;       /* Processing indicator. */

rc = CheckMsgFilterHook(hab, pQmsg, usFirst,
       usLast, fOptions);