WaitForEvent

The WaitForEvent method waits for an event that breaks into the debugger engine application.

HRESULT
  IDebugControl::WaitForEvent(
    IN ULONG  Flags,
    IN ULONG  Timeout
    );

Parameters

Flags

Set to zero. There are currently no flags that can be used in this parameter.

Timeout

Specifies how many milliseconds to wait before this method will return. If Timeout is INFINITE, this method will not return until an event that breaks into the debugger engine application occurs or an exit interrupt is issued. If the current session has a live kernel target, Timeout must be set to INFINITE.

Return Value

S_OK

The method was successful.

S_FALSE

The time-out expired.

E_PENDING

An exit interrupt was issued. The target is not available.

E_UNEXPECTED

Either there is an outstanding request for input, or none of the targets could generate events.

E_FAIL

The engine is already waiting for an event.

This method may return other error values and the above error values may have additional meanings. See Return Values for more details.

Interface Version

WaitForEvent is available in all versions of IDebugControl.

Comments

The method can be called only from the thread that started the debugger session.

When an event occurs, the debugger engine will process the event and call the event callbacks. If one of these callbacks indicates that the event should break into the debugger engine application (by returning DEBUG_STATUS_BREAK), this method will return; otherwise, it will continue waiting for an event. The event filters can also specify that an event should break into the debugger engine application. For more information about event filters, see Controlling Exceptions and Events.

This method is not re-entrant. Once it has been called, it can not be called again on any client until it has returned. In particular, it can not be called from the event callbacks, including extensions and commands executed by the callbacks.

If none of the targets are capable of generating events — for example, all the targets have exited — this method will end the current session, discard the targets, and then return E_UNEXPECTED.

For more information about using WaitForEvent to control the execution flow of the debugger application and targets, see Debugging Session and Execution Model. For details on the event callbacks, see Monitoring Events.

Requirements

Headers: Defined in Dbgeng.h. Include Dbgeng.h. The constant INFINITE is defined in Winbase.h.