Funzione WaitForDebugEvent (debugapi.h)

Articolo
03/11/2023

Attende che si verifichi un evento di debug in un processo di cui viene eseguito il debug.

Importante In passato, il sistema operativo non ha restituito stringhe Unicode tramite OutputDebugStringW e invece solo le stringhe ASCII di output. Per forzare OutputDebugStringW a restituire correttamente stringhe Unicode, i debugger devono chiamare WaitForDebugEventEx per acconsentire esplicitamente al nuovo comportamento. Quando si chiama WaitForDebugEventEx, il sistema operativo saprà che il debugger supporta Unicode e sceglie in modo specifico di ricevere stringhe Unicode.

Sintassi

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

Parametri

[out] lpDebugEvent

Puntatore a una struttura di DEBUG_EVENT che riceve informazioni sull'evento di debug.

[in] dwMilliseconds

Numero di millisecondi di attesa per un evento di debug. Se questo parametro è zero, la funzione verifica la presenza di un evento di debug e restituisce immediatamente. Se il parametro è INFINITE, la funzione non restituisce fino a quando non si è verificato un evento di debug.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Solo il thread che ha creato il processo sottoposto a debug può chiamare WaitForDebugEvent.

Quando si verifica un CREATE_PROCESS_DEBUG_EVENT, l'applicazione debugger riceve un handle per il file di immagine del processo di cui viene eseguito il debug, un handle per il processo di cui viene eseguito il debug e un handle per il thread iniziale del processo di cui viene eseguito il debug nella struttura DEBUG_EVENT . I membri in cui vengono restituiti questi handle sono u.CreateProcessInfo.hFile (file di immagine), u.CreateProcessInfo.hProcess (processo) e u.CreateProcessInfo.hThread (thread iniziale). Se il sistema ha segnalato in precedenza un evento di debug EXIT_PROCESS_DEBUG_EVENT, il sistema chiude gli handle al processo e al thread quando il debugger chiama la funzione ContinueDebugEvent . Il debugger deve chiudere l'handle al file di immagine chiamando la funzione CloseHandle .

Analogamente, quando si verifica un CREATE_THREAD_DEBUG_EVENT, l'applicazione debugger riceve un handle al thread la cui creazione ha causato l'evento di debug nel membro u.CreateThread.hThread della struttura DEBUG_EVENT . Se il sistema ha segnalato in precedenza un evento di debug EXIT_THREAD_DEBUG_EVENT, il sistema chiude gli handle al thread quando il debugger chiama la funzione ContinueDebugEvent .

Quando si verifica un LOAD_DLL_DEBUG_EVENT, l'applicazione debugger riceve un handle per la DLL caricata nel membro u.LoadDll.hFile della struttura DEBUG_EVENT . Questo handle deve essere chiuso dall'applicazione debugger chiamando la funzione CloseHandle .

Avviso Non accodare una chiamata di routine asincrona (APC) a un thread che chiama WaitForDebugEvent.

Esempio

Per un esempio, vedere Scrittura del ciclo principale del debugger.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	debugapi.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll