CreateToolhelp32Snapshot

ŁF
<style type="text/css">tr { background-color: #eee; } td { padding: 6px; } </style>
// C/C++
HANDLE WINAPI CreateToolhelp32Snapshot(
    DWORD dwFlags, 
    DWORD th32ProcessID
);
// Delphi
function CreateToolhelp32Snapshot(dwFlags, th32ProcessID: DWORD): THandle;

Funkcja CreateToolhelp32Snapshot umożliwia wylistowanie procesów i należących do nich wątków, modułów oraz pamięci.

Parametry
dwFlags Określa jaki typ element systemu powinien znaleźć się na liście. Może zawierać jedną z poniższych wartości:
WartośćOpis
TH32CS_INHERIT
0x80000000
Uchwyt zwrócony przez funkcję może być dziedziczony.
TH32CS_SNAPALLPozwala na wylistowanie wszystkich procesów i wątków w systemie, oraz pamięci i modułów należących do procesu o id podanym w parametrze th32ProcessID. Wartość parametru to suma logiczna (OR, |) tych wartości: TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPPROCESS, i TH32CS_SNAPTHREAD.
TH32CS_SNAPHEAPLIST
0x00000001
Umożliwia wylistowanie obszarów pamięci należących do procesu o id podanym w parametrze th32ProcessID. Aby pobrać dane zgromadzone przez tą funkcję, należy użyć [[winapi/Procesy i wątki/Heap32First|Heap32First]] i [[winapi/Procesy i wątki/Heap32Next|Heap32Next]]. Aby pobrać listę wszystkich obszarów pamięci (stert) danego procesu, należy użyć funkcji [[winapi/Procesy i wątki/Heap32ListFirst|Heap32ListFirst]] oraz [[winapi/Procesy i wątki/Heap32ListNext|Heap32ListNext]].
TH32CS_SNAPMODULE
0x00000008
Umożliwia wylistowanie wszystkich modułów używanych przez proces o id podanym w parametrze th32ProcessID. Aby pobrać dane zgromadzone przez tą funkcję, użyj [[winapi/Procesy i wątki/Module32First|Module32First]] oraz [[winapi/Procesy i wątki/Module32Next|Module32Next]].
Dla Windows 64-bit użycie tego parametru w 32-bitowej aplikacji spowoduje pobranie listy 32-bitowych modułów, a w aplikacji 64-bitowej spowoduje pobranie listy modułów 64-bitowych.
TH32CS_SNAPMODULE32
0x00000010
Umożliwia wylistowanie wszystkich 32-bitowych modułów używanych przez proces o id podanym w parametrze th32ProcessID gdy aplikacja jest uruchomiona pod 64-bitowym Windows.
TH32CS_SNAPMODULE32 może być łączone z TH32CS_SNAPMODULE lub TH32CS_SNAPALL.
TH32CS_SNAPPROCESS
0x00000002
Umożliwia pobranie listy wszystkich uruchomionych w systemie procesów. Aby pobrać dane zgromadzone przez tą funkcję, użyj [[winapi/Procesy i wątki/Process32First|Process32First]] oraz [[winapi/Procesy i wątki/Process32Next|Process32Next]].
TH32CS_SNAPTHREAD
0x00000004
Umożliwia pobranie listy wszystkich wątków uruchomionych w systemie. Aby pobrać dane zgromadzone przez tą funkcję, użyj [[winapi/Procesy i wątki/Thread32First|Thread32First]] oraz [[winapi/Procesy i wątki/Thread32Next|Thread32Next]].
W celu pobrania listy wątków konkretnego procesu należy wyszukać te wątki, dla których pole th32OwnerProcessID struktury [[winapi/Procesy i wątki/THREADENTRY32|THREADENTRY32]] jest równe ID tego procesu.

th32ProcessID
Identyfikator procesu, którego ma dotyczyć tworzenie listy. Jeśli ma wartość 0, używany jest bieżący proces. Parametr ten jest używany z następującymi wartościami parametru dwFlags: TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPMODULE32, TH32CS_SNAPALL. Dla innych wartości jest ignorowany i przygotowana lista obejmie wszystkie procesy.

Jeśli identyfikator należy do 64-bitowego procesu, a funkcję wywołał proces 32-bitowy, wywołanie zakończy się błędem. W takim wypadku należy użyć funkcji QueryFullProcessImageName (zwraca ona pełną ścieżkę do pliku, z którego został uruchomiony proces), działa dla 64- i 32-bitowych procesów nawet, gdy proces wywołujący jest 32-bitowy.

Wartości zwracane
Jeśli wywołanie się powiedzie, funkcja zwróci uchwyt do listy z danymi. Po skończeniu operacji związanych z tym uchwytem, należy go zamknąć funkcją [[WinAPI/closehandle|CloseHandle]].

Jeśli wywołanie się nie powiedzie, funkcja zwraca wartość INVALID_HANDLE_VALUE. Dodatkowe informacje o błędzie można pobrać za pomocą funkcji GetLastError.

Uwagi
Lista tworzona przez tą funkcję jest używana przez inne funkcje z tej samej grupy w celu wygenerowania ich wyników. Dostęp do listy jest tylko do odczytu.

Aby otrzymać listę zawierającą stan pamięci lub używane moduły dla wszystkich procesów należy użyć TH32CS_SNAPALL i ustawić th32ProcessID na 0, następnie dla każdego otrzymanego procesu należy ponownie wywołać funkcję CreateToolhelp32Snapshot, podając jako parametry wartość TH32CS_SNAPHEAPLIST lub TH32_SNAPMODULE, oraz ID tego procesu.

Przykład
* wtop.zip - kod źródłowy (w Delphi) menedżera procesów (lista procesów, wątków, aktualne obciążenie procesora)

Zobacz też

0 komentarzy