WaitForDebugEvent 函数 (debugapi.h)

项目
03/05/2024

等待正在调试的进程中发生调试事件。

重要过去，操作系统未通过 OutputDebugStringW 输出 Unicode 字符串，而是仅输出 ASCII 字符串。若要强制 OutputDebugStringW 正确输出 Unicode 字符串，调试器需要调用 WaitForDebugEventEx 以选择加入新行为。调用 WaitForDebugEventEx 时，操作系统将知道调试器支持 Unicode，并专门选择接收 Unicode 字符串。

语法

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

参数

[out] lpDebugEvent

指向接收调试事件相关信息的 DEBUG_EVENT 结构的指针。

[in] dwMilliseconds

等待调试事件的毫秒数。如果此参数为零，则函数将测试调试事件并立即返回。如果参数为 INFINITE，则在发生调试事件之前，函数不会返回。

返回值

如果该函数成功，则返回值为非零值。

如果函数失败，则返回值为零。要获得更多的错误信息，请调用 GetLastError。

注解

只有创建了正在调试的进程的线程才能调用 WaitForDebugEvent。

发生CREATE_PROCESS_DEBUG_EVENT时，调试器应用程序会收到正在调试的进程的图像文件的句柄、正在调试的进程句柄以及 DEBUG_EVENT 结构中正在调试的进程的初始线程的句柄。这些句柄返回的成员为 u.CreateProcessInfo.hFile (image file) 、 u.CreateProcessInfo.hProcess (process) 和 u.CreateProcessInfo.hThread (初始线程) 。如果系统以前报告了EXIT_PROCESS_DEBUG_EVENT调试事件，则当调试器调用 ContinueDebugEvent 函数时，系统会关闭进程和线程的句柄。调试器应通过调用 CloseHandle 函数关闭图像文件的句柄。

同样，当发生CREATE_THREAD_DEBUG_EVENT时，调试器应用程序会收到线程的句柄，该线程的创建导致了DEBUG_EVENT结构的 u.CreateThread.hThread 成员中的调试事件。如果系统以前报告了EXIT_THREAD_DEBUG_EVENT调试事件，则当调试器调用 ContinueDebugEvent 函数时，系统会关闭线程的句柄。

发生LOAD_DLL_DEBUG_EVENT时，调试器应用程序在 DEBUG_EVENT 结构的 u.LoadDll.hFile 成员中接收已加载 DLL 的句柄。调试器应用程序应通过调用 CloseHandle 函数关闭此句柄。

警告不要将异步过程调用 (APC) 排队到调用 WaitForDebugEvent 的线程。

示例

有关示例，请参阅编写调试器的主循环。

要求

要求	值
最低受支持的客户端	Windows XP [仅限桌面应用]
最低受支持的服务器	Windows Server 2003 [仅限桌面应用]
目标平台	Windows
标头	debugapi.h (包括 Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll