WaitForDebugEventEx-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. Um zu erzwingen , dass OutputDebugStringW Unicode-Zeichenfolgen ordnungsgemäß ausgibt, 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 WaitForDebugEventEx(
  [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 soll. Wenn dieser Parameter null 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 WaitForDebugEventEx 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 Prozesses, der in der DEBUG_EVENT-Struktur gedebuggt wird. Die Elemente, in denen diese Handles zurückgegeben werden, sind u.CreateProcessInfo.hFile (Bilddatei), u.CreateProcessInfo.hProcess (Prozess) und u.CreateProcessInfo.hThread (anfänglicher Thread). 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 für die Bilddatei durch Aufrufen der CloseHandle-Funktion schließen.

Analog dazu empfängt die Debuggeranwendung, wenn ein CREATE_THREAD_DEBUG_EVENT auftritt, 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 für 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 durch Aufrufen der CloseHandle-Funktion geschlossen werden.

Warnung Stellen Sie einen asynchronen Prozeduraufruf (APC) nicht in eine Warteschlange für einen Thread, der WaitForDebugEventEx aufruft.

Beispiele

Ein Beispiel finden Sie unter Schreiben der Hauptschleife des Debuggers.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 10 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2016 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	debugapi.h (windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll