Funzione CreateToolhelp32Snapshot (tlhelp32.h)
Acquisisce uno snapshot dei processi specificati, nonché gli heaps, i moduli e i thread usati da questi processi.
Sintassi
HANDLE CreateToolhelp32Snapshot(
[in] DWORD dwFlags,
[in] DWORD th32ProcessID
);
Parametri
[in] dwFlags
Parti del sistema da includere nello snapshot. Questo parametro può essere uno o più dei valori seguenti.
| valore | Significato |
|---|---|
|
Indica che l'handle snapshot deve essere ereditato. |
|
Include tutti i processi e i thread nel sistema, oltre agli heaps e ai moduli del processo specificato in th32ProcessID. Equivalente a specificare i valori TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPPROCESS e TH32CS_SNAPTHREAD combinati usando un'operazione OR ('|'). |
|
Include tutti gli heaps del processo specificato in th32ProcessID nello snapshot. Per enumerare gli heaps, vedere Heap32ListFirst. |
|
Include tutti i moduli del processo specificato in th32ProcessID nello snapshot. Per enumerare i moduli, vedere Module32First. Se la funzione ha esito negativo con ERROR_BAD_LENGTH, riprovare la funzione fino a quando non riesce.
Windows a 64 bit: L'uso di questo flag in un processo a 32 bit include i moduli a 32 bit del processo specificato nel th32ProcessID, mentre lo usa in un processo a 64 bit include i moduli a 64 bit. Per includere i moduli a 32 bit del processo specificato in th32ProcessID da un processo a 64 bit, usare il flag di TH32CS_SNAPMODULE32 . |
|
Include tutti i moduli a 32 bit del processo specificato in th32ProcessID nello snapshot quando viene chiamato da un processo a 64 bit. Questo flag può essere combinato con TH32CS_SNAPMODULE o TH32CS_SNAPALL. Se la funzione ha esito negativo con ERROR_BAD_LENGTH, riprovare la funzione fino a quando non riesce. |
|
Include tutti i processi nel sistema nello snapshot. Per enumerare i processi, vedere Process32First. |
|
Include tutti i thread nel sistema nello snapshot. Per enumerare i thread, vedere Thread32First.
Per identificare i thread appartenenti a un processo specifico, confrontare l'identificatore del processo al membro th32OwnerProcessID della struttura THREADENTRY32 durante l'enumerazione dei thread. |
[in] th32ProcessID
Identificatore del processo da includere nello snapshot. Questo parametro può essere zero per indicare il processo corrente. Questo parametro viene usato quando viene specificato il valore TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPMODULE32 o TH32CS_SNAPALL. In caso contrario, viene ignorato e tutti i processi vengono inclusi nello snapshot.
Se il processo specificato è il processo inattiva o uno dei processi CSRSS, questa funzione ha esito negativo e l'ultimo codice di errore viene ERROR_ACCESS_DENIED perché le restrizioni di accesso impediscono l'apertura del codice a livello di utente.
Se il processo specificato è un processo a 64 bit e il chiamante è un processo a 32 bit, questa funzione ha esito negativo e l'ultimo codice di errore è ERROR_PARTIAL_COPY (299).
Valore restituito
Se la funzione ha esito positivo, restituisce un handle aperto allo snapshot specificato.
Se la funzione ha esito negativo, restituisce INVALID_HANDLE_VALUE. Per informazioni dettagliate sull'errore, chiamare GetLastError. I codici di errore possibili includono ERROR_BAD_LENGTH.
Commenti
Lo snapshot eseguito da questa funzione viene esaminato dall'altro strumento per fornire i risultati. L'accesso allo snapshot è di sola lettura. L'handle snapshot funge da handle oggetto ed è soggetto alle stesse regole relative ai processi e ai thread in cui è valido.
Per enumerare gli stati dell'heap o del modulo per tutti i processi, specificare TH32CS_SNAPALL e impostare th32ProcessID su zero. Quindi, per ogni processo aggiuntivo nello snapshot, chiamare di nuovo CreateToolhelp32Snapshot , specificando il relativo identificatore di processo e il TH32CS_SNAPHEAPLIST o TH32_SNAPMODULE valore.
Quando si eseguono snapshot che includono heaps e moduli per un processo diverso dal processo corrente, la funzione CreateToolhelp32Snapshot può non riuscire o restituire informazioni non corrette per un'ampia gamma di motivi. Ad esempio, se la tabella dati del caricatore nel processo di destinazione è danneggiata o non inizializzata oppure se l'elenco dei moduli cambia durante la chiamata alla funzione in seguito al caricamento o al caricamento delle DLL, la funzione potrebbe non riuscire con ERROR_BAD_LENGTH o altro codice di errore. Assicurarsi che il processo di destinazione non sia stato avviato in uno stato sospeso e provare a chiamare nuovamente la funzione. Se la funzione ha esito negativo con ERROR_BAD_LENGTH quando viene chiamata con TH32CS_SNAPMODULE o TH32CS_SNAPMODULE32, chiamare di nuovo la funzione finché non riesce.
I flag TH32CS_SNAPMODULE e TH32CS_SNAPMODULE32 non recuperano handle per i moduli caricati con i flagLOAD_LIBRARY_AS_DATAFILE o simili. Per altre informazioni, vedere LoadLibraryEx.
Per eliminare lo snapshot, usare la funzione CloseHandle .
Si noti che è possibile usare la funzione QueryFullProcessImageName per recuperare il nome completo di un'immagine eseguibile per processi a 32 e 64 bit da un processo a 32 bit.
Esempio
Per un esempio, vedere Creazione di uno snapshot e visualizzazione di processi.
Requisiti
| Client minimo supportato | Windows XP [solo app desktop] |
| Server minimo supportato | Windows Server 2003 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | tlhelp32.h |
| Libreria | Kernel32.lib |
| DLL | Kernel32.dll |