WaitForDebugEvent-Funktion (debugapi.h)

Artikel
08/23/2023

Wartet, bis ein Debugereignis in einem gedebuggten Prozess auftritt.

Wichtig In der Vergangenheit hat das Betriebssystem keine Unicode-Zeichenfolgen über OutputDebugStringW ausgegeben, sondern nur ASCII-Zeichenfolgen ausgegeben. Damit OutputDebugStringW die korrekte Ausgabe von Unicode-Zeichenfolgen erzwingt, müssen Debugger WaitForDebugEventEx aufrufen, um das neue Verhalten zu aktivieren. Beim Aufrufen von WaitForDebugEventEx weiß das Betriebssystem, dass der Debugger Unicode unterstützt und sich speziell für den Empfang von Unicode-Zeichenfolgen entscheidet.

Syntax

BOOL WaitForDebugEvent(
  [out] LPDEBUG_EVENT lpDebugEvent,
  [in]  DWORD         dwMilliseconds
);

Parameter

[out] lpDebugEvent

Ein Zeiger auf eine DEBUG_EVENT-Struktur , die Informationen zum Debugereignis empfängt.

[in] dwMilliseconds

Die Anzahl der Millisekunden, die auf ein Debugereignis gewartet werden sollen. Wenn dieser Parameter 0 ist, testet die Funktion auf ein Debugereignis und gibt sofort zurück. Wenn der Parameter INFINITE ist, wird die Funktion erst zurückgegeben, wenn ein Debugereignis aufgetreten ist.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Nur der Thread, der den zu debuggenden Prozess erstellt hat, kann WaitForDebugEvent aufrufen.

Wenn ein CREATE_PROCESS_DEBUG_EVENT auftritt, empfängt die Debuggeranwendung ein Handle für die Imagedatei des zu debuggenden Prozesses, ein Handle für den zu debuggenden Prozess und ein Handle für den anfänglichen Thread des zu debuggenden Prozesses in der DEBUG_EVENT-Struktur . Die Elemente, in denen diese Handles zurückgegeben werden, sind u.CreateProcessInfo.hFile (Imagedatei), u.CreateProcessInfo.hProcess (process) und u.CreateProcessInfo.hThread (Anfangsthread). Wenn das System zuvor ein EXIT_PROCESS_DEBUG_EVENT Debugereignis gemeldet hat, schließt das System die Handles für den Prozess und den Thread, wenn der Debugger die ContinueDebugEvent-Funktion aufruft. Der Debugger sollte das Handle mit der Imagedatei schließen, indem er die CloseHandle-Funktion aufruft .

Auf ähnliche Weise empfängt die Debuggeranwendung bei einem CREATE_THREAD_DEBUG_EVENT ein Handle für den Thread, dessen Erstellung das Debugereignis im u.CreateThread.hThread-Member der DEBUG_EVENT-Struktur verursacht hat. Wenn das System zuvor ein EXIT_THREAD_DEBUG_EVENT Debugereignis gemeldet hat, schließt das System die Handles an den Thread, wenn der Debugger die ContinueDebugEvent-Funktion aufruft.

Wenn ein LOAD_DLL_DEBUG_EVENT auftritt, empfängt die Debuggeranwendung ein Handle für die geladene DLL im u.LoadDll.hFile-Member der DEBUG_EVENT-Struktur . Dieses Handle sollte von der Debuggeranwendung geschlossen werden, indem die CloseHandle-Funktion aufgerufen wird.

Warnung Führen Sie keinen asynchronen Prozeduraufruf (APC ) in eine Warteschlange für einen Thread aus, der WaitForDebugEvent aufruft.

Beispiele

Ein Beispiel finden Sie unter Schreiben der Hauptschleife des Debuggers.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	debugapi.h (einschließen von Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll