Função CreateToolhelp32Snapshot (tlhelp32.h)
Usa uma instantâneo dos processos especificados, bem como os heaps, módulos e threads usados por esses processos.
Sintaxe
HANDLE CreateToolhelp32Snapshot(
[in] DWORD dwFlags,
[in] DWORD th32ProcessID
);
Parâmetros
[in] dwFlags
As partes do sistema a serem incluídas no instantâneo. Esse parâmetro pode usar um dos valores a seguir.
| Valor | Significado |
|---|---|
|
Indica que o identificador instantâneo deve ser herdável. |
|
Inclui todos os processos e threads no sistema, além dos heaps e módulos do processo especificado no th32ProcessID. Equivalente a especificar os valores TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPPROCESS e TH32CS_SNAPTHREAD combinados usando uma operação OR ('|'). |
|
Inclui todos os heaps do processo especificado no th32ProcessID no instantâneo. Para enumerar os heaps, consulte Heap32ListFirst. |
|
Inclui todos os módulos do processo especificado no th32ProcessID no instantâneo. Para enumerar os módulos, consulte Module32First. Se a função falhar com ERROR_BAD_LENGTH, tente novamente a função até que ela seja bem-sucedida.
Windows de 64 bits: Usar esse sinalizador em um processo de 32 bits inclui os módulos de 32 bits do processo especificado em th32ProcessID, enquanto usá-lo em um processo de 64 bits inclui os módulos de 64 bits. Para incluir os módulos de 32 bits do processo especificado no th32ProcessID de um processo de 64 bits, use o sinalizador TH32CS_SNAPMODULE32 . |
|
Inclui todos os módulos de 32 bits do processo especificado em th32ProcessID no instantâneo quando chamado de um processo de 64 bits. Esse sinalizador pode ser combinado com TH32CS_SNAPMODULE ou TH32CS_SNAPALL. Se a função falhar com ERROR_BAD_LENGTH, tente novamente a função até que ela seja bem-sucedida. |
|
Inclui todos os processos no sistema no instantâneo. Para enumerar os processos, consulte Process32First. |
|
Inclui todos os threads no sistema no instantâneo. Para enumerar os threads, consulte Thread32First.
Para identificar os threads que pertencem a um processo específico, compare seu identificador de processo com o membro th32OwnerProcessID da estrutura THREADENTRY32 ao enumerar os threads. |
[in] th32ProcessID
O identificador de processo do processo a ser incluído no instantâneo. Esse parâmetro pode ser zero para indicar o processo atual. Esse parâmetro é usado quando o valor TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPMODULE32 ou TH32CS_SNAPALL é especificado. Caso contrário, ele será ignorado e todos os processos serão incluídos no instantâneo.
Se o processo especificado for o processo ocioso ou um dos processos CSRSS, essa função falhará e o último código de erro será ERROR_ACCESS_DENIED porque suas restrições de acesso impedem que o código no nível do usuário os abra.
Se o processo especificado for um processo de 64 bits e o chamador for um processo de 32 bits, essa função falhará e o último código de erro será ERROR_PARTIAL_COPY (299).
Valor retornado
Se a função for bem-sucedida, ela retornará um identificador aberto para o instantâneo especificado.
Se a função falhar, ela retornará INVALID_HANDLE_VALUE. Para obter informações de erro estendidas, chame GetLastError. Os códigos de erro possíveis incluem ERROR_BAD_LENGTH.
Comentários
Os instantâneo obtidos por essa função são examinados pelas outras funções de ajuda da ferramenta para fornecer seus resultados. O acesso ao instantâneo é somente leitura. O identificador instantâneo atua como um identificador de objeto e está sujeito às mesmas regras em relação a quais processos e threads ele é válido.
Para enumerar os estados de heap ou módulo para todos os processos, especifique TH32CS_SNAPALL e defina th32ProcessID como zero. Em seguida, para cada processo adicional no instantâneo, chame CreateToolhelp32Snapshot novamente, especificando seu identificador de processo e o valor TH32CS_SNAPHEAPLIST ou TH32_SNAPMODULE.
Ao tirar instantâneos que incluem heaps e módulos para um processo diferente do processo atual, a função CreateToolhelp32Snapshot pode falhar ou retornar informações incorretas por vários motivos. Por exemplo, se a tabela de dados do carregador no processo de destino estiver corrompida ou não for inicializada, ou se a lista de módulos for alterada durante a chamada de função como resultado de DLLs sendo carregadas ou descarregadas, a função poderá falhar com ERROR_BAD_LENGTH ou outro código de erro. Verifique se o processo de destino não foi iniciado em um estado suspenso e tente chamar a função novamente. Se a função falhar com ERROR_BAD_LENGTH quando chamada com TH32CS_SNAPMODULE ou TH32CS_SNAPMODULE32, chame a função novamente até que ela seja bem-sucedida.
Os sinalizadores TH32CS_SNAPMODULE e TH32CS_SNAPMODULE32 não recuperam identificadores para módulos que foram carregados com o LOAD_LIBRARY_AS_DATAFILE ou sinalizadores semelhantes. Para obter mais informações, consulte LoadLibraryEx.
Para destruir o instantâneo, use a função CloseHandle.
Observe que você pode usar a função QueryFullProcessImageName para recuperar o nome completo de uma imagem executável para processos de 32 e 64 bits de um processo de 32 bits.
Exemplos
Para obter um exemplo, consulte Tomando um instantâneo e exibindo processos.
Requisitos
| 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 | tlhelp32.h |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |