SetWinEventHook

[This is preliminary documentation and subject to change.]

Sets an event hook for a range of events.

HWINEVENTHOOK WINAPI SetWinEventHook(
  UINT eventMin,
  UINT eventMax,
  HMODULE hmodWinEventProc,
  WINEVENTPROC lpfnWinEventProc,
  DWORD idProcess,
  DWORD idThread,
  UINT dwflags
);

Parameters

eventMin

Event constant describing the lowest event value in the range. This parameter can be EVENT_MIN to indicate the lowest possible event value.

eventMax

Event constant describing the highest event value in the range. This parameter can be EVENT_MAX to indicate the highest possible event value.

hmodWinEventProc

Handle to the dynamic-link library (DLL) containing the callback function at lpfnWinEventProc, if the WINEVENT_INCONTEXT flag is specified in the dwFlags parameter. If the callback function is not located in a DLL or the WINEVENT_OUTOFCONTEXT flag is specified, this parameter is ignored.

lpfnWinEventProc

Address of a callback function that matches the return value and argument list of the WinEventProc function declaration. The winable.h header file defines the WINEVENTPROC data type for declaring variables that match the WinEventProc declaration. USER calls this function when a server posts an event that falls within the range specified by the eventMin and eventMax parameters.

idProcess

ID of the process to be monitored, or zero for all processes.

idThread

ID of the thread with which the callback function will be associated. If this parameter is zero, the hook procedure is associated with all existing threads.

dwflags

Flag values specifying one or more receiving options. This parameter can contain one or more of the following values. The default value is WINEVENT_OUTOFCONTEXT.

WINEVENT_INCONTEXT
	USER sends event notifications to the callback function as they occur. In this case, the DLL containing the callback function is mapped into the address space of the process generating the event. The callback function must be in a DLL to use this option.
WINEVENT_OUTOFCONTEXT
	USER sends event notifications that are queued before sending them to the callback function. Queuing is required because the callback function is not mapped into the address space of the process generating the event. Although this method is asynchronous, events are guaranteed to be in sequential order.
WINEVENT_SKIPOWNPROCESS
	Prevents any threads in the caller's process from receiving their own notifications. This flag does not prevent threads from generating events.
WINEVENT_SKIPOWNTHREAD
	Prevents the thread that is processing notifications from receiving any events it might have generated itself. This flag does not prevent the thread from generating events.

Return Values

Returns an HWINEVENTHOOK value that identifies this event hook instance if successful, or zero otherwise. Your application should save this return value to use with the UnhookWinEvent function.

Remarks

This function allows you to specify not only which events you want, but also the process and thread in which you want to look for those events. This is useful when you want to work only with certain applications or just the system.

If the idProcess parameter is nonzero and idThread is zero, this function will hook all threads in that process. If the idProcess parameter is zero and idThread is nonzero, this function will hook only the thread specified by idThread. If both are zero, the function will hook in all threads and processes.

To monitor a noncontiguous range of events, call this method twice, specifying the same callback function in the lpfnWinEventProc parameter each time.

The client thread calling SetWinEventHook must be a thread that has a message loop, sometimes known as a "GUI thread."