Registers a handler with the current process event thread. The handler is called when an event is received by the thread which matches the flags registered with the handler.

The handler is called with a parameter pointing to an EVENTINFO structure.

DWORD RegisterRtEventHandler(
    DWORD dwEventFlags,
    EVENTHANDLER pHandler
);

typedef void (*EVENTHANDLER)(LPEVENTINFO pEventInfo);

Parameters

dwEventFlags

Specifies a combination of the following notification types which the event thread uses to determine when to call the handler:

RT_SYSTEM_NOTIFICATIONS
RT_SPONSOR_NOTIFICATIONS
RT_DEPENDENT_NOTIFICATIONS
RT_EXIT_NOTIFICATIONS

pHandler

Pointer to the handler to be called when a matching event arrives.

Return Values

A non-zero handle value to be used when unregistering the handler. If the call fails then 0 is returned.

Remarks

The event handler feature may be used in place of an explicit call to RtNotifyEvent. The first call to RegisterRtEventHandler causes an event thread to be created which in turn calls RtNotifyEvent. On return from that call it walks the list of registered handlers and calls those which match the event type just received. The call will fail if another thread has already called RtNotifyEvent, or if the maximum number of handlers has been registered. Currently the maximum is 16 (per process). The priority of the event thread defaults to 140 and may be changed before or after creating the thread by calling SetRtEventHandlerPriority.

Call UnregisterRtEventHandler to deactivate the handler.

This method is particularly useful when DSM events need to be processed in an RSL where is is not known whether the parent process also needs to process DSM events.

Status

E_OK 0x0000

No exceptional conditions occurred.

E_CONTEXT

A call to RtNotifyEvent has already been made in this process.

E_LIMIT

The handler table is full.

E_PARAM

An invalid dwEventFlags value was presented, or a null handler pointer.

Requirements