Função WaitForDebugEvent (debugapi.h)

Artigo
02/28/2024

Aguarda a ocorrência de um evento de depuração em um processo que está sendo depurado.

Importante No passado, o sistema operacional não gerava cadeias de caracteres Unicode por meio de OutputDebugStringW e, em vez disso, gerava apenas cadeias de caracteres ASCII. Para forçar OutputDebugStringW a gerar corretamente cadeias de caracteres Unicode, os depuradores precisam chamar WaitForDebugEventEx para aceitar o novo comportamento. Ao chamar WaitForDebugEventEx, o sistema operacional saberá que o depurador dá suporte a Unicode e está optando especificamente por receber cadeias de caracteres Unicode.

Sintaxe

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

Parâmetros

[out] lpDebugEvent

Um ponteiro para uma estrutura DEBUG_EVENT que recebe informações sobre o evento de depuração.

[in] dwMilliseconds

O número de milissegundos a aguardar por um evento de depuração. Se esse parâmetro for zero, a função testará um evento de depuração e retornará imediatamente. Se o parâmetro for INFINITE, a função não retornará até que ocorra um evento de depuração.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Somente o thread que criou o processo que está sendo depurado pode chamar WaitForDebugEvent.

Quando ocorre um CREATE_PROCESS_DEBUG_EVENT, o aplicativo depurador recebe um identificador para o arquivo de imagem do processo que está sendo depurado, um identificador para o processo que está sendo depurado e um identificador para o thread inicial do processo que está sendo depurado na estrutura DEBUG_EVENT . Os membros em que esses identificadores são retornados são u.CreateProcessInfo.hFile (arquivo de imagem), u.CreateProcessInfo.hProcess (processo) e u.CreateProcessInfo.hThread (thread inicial). Se o sistema relatou anteriormente um evento de depuração EXIT_PROCESS_DEBUG_EVENT, o sistema fecha os identificadores para o processo e o thread quando o depurador chama a função ContinueDebugEvent . O depurador deve fechar o identificador do arquivo de imagem chamando a função CloseHandle .

Da mesma forma, quando ocorre um CREATE_THREAD_DEBUG_EVENT, o aplicativo depurador recebe um identificador para o thread cuja criação causou o evento de depuração no membro u.CreateThread.hThread da estrutura DEBUG_EVENT . Se o sistema relatou anteriormente um evento de depuração EXIT_THREAD_DEBUG_EVENT, o sistema fecha os identificadores do thread quando o depurador chama a função ContinueDebugEvent .

Quando ocorre um LOAD_DLL_DEBUG_EVENT, o aplicativo depurador recebe um identificador para a DLL carregada no membro u.LoadDll.hFile da estrutura DEBUG_EVENT . Esse identificador deve ser fechado pelo aplicativo depurador chamando a função CloseHandle .

Aviso Não enfileirar uma APC ( chamada de procedimento assíncrono ) para um thread que chama WaitForDebugEvent.

Exemplos

Para obter um exemplo, consulte Escrevendo o loop principal do depurador.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	debugapi.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll