WaitForDebugEvent 函式 (debugapi.h)

發行項
02/28/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 (圖像檔) 、 u.CreateProcessInfo.hProcess (進程) ，以及 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 的線程。

範例

如需範例，請參閱撰寫調試程式的Main迴圈。

規格需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限桌面應用程式]
目標平台	Windows
標頭	debugapi.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll