Fungsi CreateToolhelp32Snapshot (tlhelp32.h)

Artikel
03/08/2023

Mengambil rekam jepret dari proses yang ditentukan, serta tumpukan, modul, dan utas yang digunakan oleh proses ini.

Sintaks

HANDLE CreateToolhelp32Snapshot(
  [in] DWORD dwFlags,
  [in] DWORD th32ProcessID
);

Parameter

[in] dwFlags

Bagian sistem yang akan disertakan dalam rekam jepret. Parameter ini bisa menjadi satu atau beberapa nilai berikut.

Nilai	Makna
TH32CS_INHERIT 0x80000000	Menunjukkan bahwa handel rekam jepret akan dapat diwariskan.
TH32CS_SNAPALL	Mencakup semua proses dan utas dalam sistem, ditambah tumpukan dan modul proses yang ditentukan dalam th32ProcessID. Setara dengan menentukan nilai TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPPROCESS, dan TH32CS_SNAPTHREAD yang digabungkan menggunakan operasi OR ('\|').
TH32CS_SNAPHEAPLIST 0x00000001	Mencakup semua timbunan proses yang ditentukan dalam th32ProcessID dalam rekam jepret. Untuk menghitung tumpukan, lihat Heap32ListFirst.
TH32CS_SNAPMODULE 0x00000008	Mencakup semua modul proses yang ditentukan dalam th32ProcessID dalam rekam jepret. Untuk menghitung modul, lihat Module32First. Jika fungsi gagal dengan ERROR_BAD_LENGTH, coba lagi fungsi hingga berhasil. Windows 64-bit: Menggunakan bendera ini dalam proses 32-bit mencakup modul 32-bit dari proses yang ditentukan dalam th32ProcessID, saat menggunakannya dalam proses 64-bit mencakup modul 64-bit. Untuk menyertakan modul 32-bit dari proses yang ditentukan dalam th32ProcessID dari proses 64-bit, gunakan bendera TH32CS_SNAPMODULE32 .
TH32CS_SNAPMODULE32 0x00000010	Mencakup semua modul 32-bit dari proses yang ditentukan dalam th32ProcessID dalam rekam jepret ketika dipanggil dari proses 64-bit. Bendera ini dapat dikombinasikan dengan TH32CS_SNAPMODULE atau TH32CS_SNAPALL. Jika fungsi gagal dengan ERROR_BAD_LENGTH, coba lagi fungsi hingga berhasil.
TH32CS_SNAPPROCESS 0x00000002	Mencakup semua proses dalam sistem dalam rekam jepret. Untuk menghitung proses, lihat Process32First.
TH32CS_SNAPTHREAD 0x00000004	Termasuk semua utas dalam sistem dalam rekam jepret. Untuk menghitung utas, lihat Thread32First. Untuk mengidentifikasi utas yang termasuk dalam proses tertentu, bandingkan pengidentifikasi prosesnya dengan anggota th32OwnerProcessID dari struktur THREADENTRY32 saat menghitung utas.

[in] th32ProcessID

Pengidentifikasi proses yang akan disertakan dalam rekam jepret. Parameter ini bisa nol untuk menunjukkan proses saat ini. Parameter ini digunakan saat nilai TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPMODULE32, atau TH32CS_SNAPALL ditentukan. Jika tidak, itu diabaikan dan semua proses disertakan dalam rekam jepret.

Jika proses yang ditentukan adalah proses Menganggur atau salah satu proses CSRSS, fungsi ini gagal dan kode kesalahan terakhir ERROR_ACCESS_DENIED karena pembatasan aksesnya mencegah kode tingkat pengguna membukanya.

Jika proses yang ditentukan adalah proses 64-bit dan pemanggil adalah proses 32-bit, fungsi ini gagal dan kode kesalahan terakhir adalah ERROR_PARTIAL_COPY (299).

Nilai kembali

Jika fungsi berhasil, fungsi mengembalikan handel terbuka ke rekam jepret yang ditentukan.

Jika fungsi gagal, fungsi akan mengembalikan INVALID_HANDLE_VALUE. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError. Kemungkinan kode kesalahan termasuk ERROR_BAD_LENGTH.

Keterangan

Rekam jepret yang diambil oleh fungsi ini diperiksa oleh alat lain membantu fungsi untuk memberikan hasilnya. Akses ke rekam jepret bersifat baca saja. Handel rekam jepret bertindak sebagai handel objek dan tunduk pada aturan yang sama mengenai proses dan utas mana yang valid.

Untuk menghitung status tumpukan atau modul untuk semua proses, tentukan TH32CS_SNAPALL dan atur th32ProcessID ke nol. Kemudian, untuk setiap proses tambahan dalam rekam jepret, panggil CreateToolhelp32Snapshot lagi, menentukan pengidentifikasi prosesnya dan nilai TH32CS_SNAPHEAPLIST atau TH32_SNAPMODULE .

Saat mengambil rekam jepret yang mencakup tumpukan dan modul untuk proses selain proses saat ini, fungsi CreateToolhelp32Snapshot dapat gagal atau mengembalikan informasi yang salah karena berbagai alasan. Misalnya, jika tabel data pemuat dalam proses target rusak atau tidak diinisialisasi, atau jika daftar modul berubah selama panggilan fungsi sebagai akibat dari DLL yang dimuat atau dibongkar, fungsi mungkin gagal dengan ERROR_BAD_LENGTH atau kode kesalahan lainnya. Pastikan bahwa proses target tidak dimulai dalam status ditangguhkan, dan coba panggil fungsi lagi. Jika fungsi gagal dengan ERROR_BAD_LENGTH saat dipanggil dengan TH32CS_SNAPMODULE atau TH32CS_SNAPMODULE32, panggil fungsi lagi hingga berhasil.

Bendera TH32CS_SNAPMODULE dan TH32CS_SNAPMODULE32 tidak mengambil handel untuk modul yang dimuat dengan LOAD_LIBRARY_AS_DATAFILE atau bendera serupa. Untuk informasi selengkapnya, lihat LoadLibraryEx.

Untuk menghancurkan rekam jepret, gunakan fungsi CloseHandle .

Perhatikan bahwa Anda dapat menggunakan fungsi QueryFullProcessImageName untuk mengambil nama lengkap gambar yang dapat dieksekusi untuk proses 32 dan 64-bit dari proses 32-bit.

Contoh

Misalnya, lihat Mengambil Rekam Jepret dan Menampilkan Proses.

Persyaratan


Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	tlhelp32.h
Pustaka	Kernel32.lib
DLL	Kernel32.dll