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 |
| 程式庫 | Kernel32.lib |
| DLL | Kernel32.dll |