Функция WaitForDebugEvent (debugapi.h)

Статья
08/23/2023

Ожидает возникновения события отладки в отлаживаемом процессе.

Важно В прошлом операционная система не выводил строки Юникода через OutputDebugStringW , а выводил только строки ASCII. Чтобы принудить OutputDebugStringW правильно выводить строки Юникода, отладчики должны вызвать WaitForDebugEventEx , чтобы выбрать новое поведение. При вызове WaitForDebugEventEx операционная система будет знать, что отладчик поддерживает Юникод и специально выбирает получение строк Юникода.

Синтаксис

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

Параметры

[out] lpDebugEvent

Указатель на структуру DEBUG_EVENT , получающую сведения о событии отладки.

[in] dwMilliseconds

Время ожидания события отладки в миллисекундах. Если этот параметр равен нулю, функция проверяет событие отладки и возвращает немедленно. Если параметр имеет значение INFINITE, функция не возвращается, пока не произошло событие отладки.

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

При CREATE_PROCESS_DEBUG_EVENT приложение отладчика получает дескриптор файла изображения отлаживаемого процесса, дескриптор отлаживаемого процесса и дескриптор начального потока отлаживаемого процесса в структуре DEBUG_EVENT . Элементы, в которых возвращаются эти дескрипторы: u.CreateProcessInfo.hFile (файл изображения), u.CreateProcessInfo.hProcess (process) и u.CreateProcessInfo.hThread (исходный поток). Если система ранее сообщала о событии отладки EXIT_PROCESS_DEBUG_EVENT, система закрывает дескриптор для процесса и потока, когда отладчик вызывает функцию ContinueDebugEvent . Отладчик должен закрыть дескриптор для файла изображения, вызвав функцию CloseHandle .

Аналогичным образом, при CREATE_THREAD_DEBUG_EVENT приложение отладчика получает дескриптор для потока, создание которого вызвало событие отладки в элементе u.CreateThread.hThreadструктуры DEBUG_EVENT . Если система ранее сообщала о событии отладки EXIT_THREAD_DEBUG_EVENT, система закрывает дескриптор для потока, когда отладчик вызывает функцию ContinueDebugEvent .

При LOAD_DLL_DEBUG_EVENT приложение отладчика получает дескриптор загруженной библиотеки DLL в элементе u.LoadDll.hFile структуры DEBUG_EVENT . Этот дескриптор должен быть закрыт приложением отладчика путем вызова функции CloseHandle .

Предупреждение Не помещайте в очередь асинхронный вызов процедуры (APC) в поток, который вызывает WaitForDebugEvent.

Примеры

Пример см. в разделе Написание основного цикла отладчика.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	debugapi.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll