Функция CreateToolhelp32Snapshot (tlhelp32.h)
Принимает snapshot указанных процессов, а также кучи, модули и потоки, используемые этими процессами.
Синтаксис
HANDLE CreateToolhelp32Snapshot(
[in] DWORD dwFlags,
[in] DWORD th32ProcessID
);
Параметры
[in] dwFlags
Части системы, которые будут включены в snapshot. Этот параметр может иметь одно или несколько из следующих значений.
| Значение | Значение |
|---|---|
|
Указывает, что дескриптор snapshot должен быть наследуемым. |
|
Включает все процессы и потоки в системе, а также кучи и модули процесса, указанного в th32ProcessID. Эквивалентно указанию значений TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPPROCESS и TH32CS_SNAPTHREAD , объединенных с помощью операции OR ('|'). |
|
Включает все кучи процесса, указанного в th32ProcessID в snapshot. Сведения о перечислении кучи см. в разделе Heap32ListFirst. |
|
Включает все модули процесса, указанного в th32ProcessID в snapshot. Сведения о перечислении модулей см. в разделе Module32First. Если функция завершается сбоем с ERROR_BAD_LENGTH, повторите ее до тех пор, пока она не будет выполнена успешно.
64-разрядная версия Windows: Использование этого флага в 32-разрядном процессе включает 32-разрядные модули процесса, указанного в th32ProcessID, а его использование в 64-разрядном процессе включает 64-разрядные модули. Чтобы включить 32-разрядные модули процесса, указанного в th32ProcessID , из 64-разрядного процесса, используйте флаг TH32CS_SNAPMODULE32 . |
|
Включает все 32-разрядные модули процесса, указанного в th32ProcessID, в snapshot при вызове из 64-разрядного процесса. Этот флаг можно сочетать с TH32CS_SNAPMODULE или TH32CS_SNAPALL. Если функция завершается сбоем с ERROR_BAD_LENGTH, повторите ее до тех пор, пока она не будет выполнена успешно. |
|
Включает все процессы в системе в snapshot. Сведения о перечислении процессов см. в разделе Process32First. |
|
Включает все потоки в системе в snapshot. Сведения о перечислении потоков см. в разделе Thread32First.
Чтобы определить потоки, принадлежащие конкретному процессу, сравните его идентификатор процесса с элементом th32OwnerProcessIDструктуры THREADENTRY32 при перечислении потоков. |
[in] th32ProcessID
Идентификатор процесса, включаемого в snapshot. Этот параметр может быть равен нулю, чтобы указать текущий процесс. Этот параметр используется при указании значения TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPMODULE32 или TH32CS_SNAPALL . В противном случае он игнорируется, и все процессы включаются в snapshot.
Если указанный процесс является неактивным процессом или одним из процессов CSRSS, эта функция завершается сбоем и последний код ошибки ERROR_ACCESS_DENIED , так как их ограничения доступа препятствуют открытию кода на уровне пользователя.
Если указанный процесс является 64-разрядным, а вызывающим — 32-разрядным процессом, эта функция завершается ошибкой и последний код ошибки — ERROR_PARTIAL_COPY (299).
Возвращаемое значение
Если функция завершается успешно, она возвращает открытый дескриптор указанной snapshot.
Если функция завершается сбоем, она возвращает INVALID_HANDLE_VALUE. Дополнительные сведения об ошибке можно получить, вызвав GetLastError. Возможные коды ошибок включают ERROR_BAD_LENGTH.
Комментарии
Snapshot, принятые этой функцией, проверяются другими функциями справки для предоставления результатов. Доступ к snapshot доступен только для чтения. Дескриптор snapshot действует как дескриптор объекта и подчиняется тем же правилам, в отношении каких процессов и потоков он действителен.
Чтобы перечислить состояния кучи или модуля для всех процессов, укажите TH32CS_SNAPALL и присвойте th32ProcessID значение 0. Затем для каждого дополнительного процесса в snapshot снова вызовите CreateToolhelp32Snapshot, указав идентификатор процесса и значение TH32CS_SNAPHEAPLIST или TH32_SNAPMODULE.
При создании моментальных снимков, включающих кучи и модули для процесса, отличного от текущего процесса, функция CreateToolhelp32Snapshot может завершаться ошибкой или возвращать неверные сведения по различным причинам. Например, если таблица данных загрузчика в целевом процессе повреждена или не инициализирована или список модулей изменяется во время вызова функции в результате загрузки или выгрузки библиотек DLL, функция может завершиться ошибкой с ERROR_BAD_LENGTH или другим кодом ошибки. Убедитесь, что целевой процесс не запущен в приостановленном состоянии, и попробуйте вызвать функцию еще раз. Если функция завершается сбоем с ERROR_BAD_LENGTH при вызове с помощью TH32CS_SNAPMODULE или TH32CS_SNAPMODULE32, вызывайте функцию еще раз, пока она не будет успешной.
Флаги TH32CS_SNAPMODULE и TH32CS_SNAPMODULE32 не извлекают дескрипторы для модулей, загруженных с LOAD_LIBRARY_AS_DATAFILE или аналогичными флагами. Дополнительные сведения см. в разделе LoadLibraryEx.
Чтобы уничтожить snapshot, используйте функцию CloseHandle.
Обратите внимание, что функцию QueryFullProcessImageName можно использовать для получения полного имени исполняемого образа для 32- и 64-разрядных процессов из 32-разрядного процесса.
Примеры
Пример см. в разделе Создание моментального снимка и просмотр процессов.
Требования
| Минимальная версия клиента | Windows XP [только классические приложения] |
| Минимальная версия сервера | Windows Server 2003 [только классические приложения] |
| Целевая платформа | Windows |
| Header | tlhelp32.h |
| Библиотека | Kernel32.lib |
| DLL | Kernel32.dll |