CreateToolhelp32Snapshot 函数 (tlhelp32.h)
获取指定进程以及这些进程使用的堆、模块和线程的快照。
语法
HANDLE CreateToolhelp32Snapshot(
[in] DWORD dwFlags,
[in] DWORD th32ProcessID
);
参数
[in] dwFlags
要包含在快照中的系统部分。 此参数可使用以下一个或多个值。
| 值 | 含义 |
|---|---|
|
指示快照句柄是可继承的。 |
|
包括系统中的所有进程和线程，以及 th32ProcessID 中指定的进程的堆和模块。 等效于指定使用 OR 操作 (“|”组合的TH32CS_SNAPHEAPLIST、TH32CS_SNAPMODULE、TH32CS_SNAPPROCESS和TH32CS_SNAPTHREAD值) 。 |
|
包括快照 th32ProcessID 中指定的进程的所有堆。 若要枚举堆，请参阅 Heap32ListFirst。 |
|
包括快照 th32ProcessID 中指定的进程的所有模块。 若要枚举模块，请参阅 Module32First。 如果函数失败并 出现ERROR_BAD_LENGTH，请重试该函数，直到成功。
64 位 Windows： 在 32 位进程中使用此标志包括 th32ProcessID 中指定的进程的 32 位模块，而在 64 位进程中使用它包括 64 位模块。 若要从 64 位进程包括 th32ProcessID 中指定的进程的 32 位模块，请使用 TH32CS_SNAPMODULE32 标志。 |
|
从 64 位进程调用时，包括快照中 th32ProcessID 中指定的进程的所有 32 位模块。 此标志可以与 TH32CS_SNAPMODULE 或 TH32CS_SNAPALL结合使用。 如果函数失败并 出现ERROR_BAD_LENGTH，请重试该函数，直到成功。 |
|
包括系统中快照中的所有进程。 若要枚举进程，请参阅 Process32First。 |
|
包括快照系统中的所有线程。 若要枚举线程，请参阅 Thread32First。
若要标识属于特定进程的线程，请在枚举线程时将其进程标识符与 THREADENTRY32 结构的 th32OwnerProcessID 成员进行比较。 |
[in] th32ProcessID
要包含在快照中的进程的进程标识符。 此参数可以为零以指示当前进程。 指定 TH32CS_SNAPHEAPLIST、 TH32CS_SNAPMODULE、 TH32CS_SNAPMODULE32或 TH32CS_SNAPALL 值时，使用此参数。 否则，将忽略它，并且所有进程都包含在快照中。
如果指定的进程是空闲进程或 CSRSS 进程之一，则此函数将失败，并且最后一个错误代码 ERROR_ACCESS_DENIED ，因为它们的访问限制阻止用户级代码打开它们。
如果指定的进程是 64 位进程，调用方是 32 位进程，则此函数将失败，最后一个错误代码 ERROR_PARTIAL_COPY (299) 。
返回值
如果函数成功，它将返回指定快照的打开句柄。
如果函数失败，它将返回 INVALID_HANDLE_VALUE。 要获得更多的错误信息，请调用 GetLastError。 可能的错误代码包括 ERROR_BAD_LENGTH。
注解
此函数采用的快照由其他工具帮助函数检查，以提供其结果。 对快照的访问是只读的。 快照句柄充当对象句柄，并受制于有关其有效进程和线程的相同规则。
若要枚举所有进程的堆或模块状态， 请指定TH32CS_SNAPALL 并将 th32ProcessID 设置为零。 然后，对于快照中的每个附加进程，再次调用 CreateToolhelp32Snapshot，并指定其进程标识符以及TH32CS_SNAPHEAPLIST或TH32_SNAPMODULE值。
为当前进程以外的进程创建包含堆和模块的快照时， CreateToolhelp32Snapshot 函数可能会因各种原因而失败或返回不正确的信息。 例如，如果目标进程中的加载程序数据表已损坏或未初始化，或者模块列表在函数调用期间由于加载或卸载 DLL 而发生更改，则函数可能会失败 并出现ERROR_BAD_LENGTH 或其他错误代码。 确保目标进程未在挂起状态下启动，然后再次尝试调用函数。 如果使用 TH32CS_SNAPMODULE或 TH32CS_SNAPMODULE32 调用函数时ERROR_BAD_LENGTH 失败，请再次调用函数，直到成功。
TH32CS_SNAPMODULE和TH32CS_SNAPMODULE32标志不会检索使用LOAD_LIBRARY_AS_DATAFILE或类似标志加载的模块的句柄。 有关详细信息，请参阅 LoadLibraryEx。
若要销毁快照，请使用 CloseHandle 函数。
请注意，可以使用 QueryFullProcessImageName 函数从 32 位进程中检索 32 位和 64 位进程的可执行映像的全名。
示例
有关示例，请参阅 拍摄快照和查看进程。
要求
| 最低受支持的客户端 | Windows XP [仅限桌面应用] |
| 最低受支持的服务器 | Windows Server 2003 [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | tlhelp32.h |
| Library | Kernel32.lib |
| DLL | Kernel32.dll |