CreateToolhelp32Snapshot, fonction (tlhelp32.h)

Article
08/26/2023

Prend une instantané des processus spécifiés, ainsi que des tas, modules et threads utilisés par ces processus.

Syntaxe

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

Paramètres

[in] dwFlags

Parties du système à inclure dans le instantané. Ce paramètre peut prendre une ou plusieurs des valeurs suivantes.

Valeur	Signification
TH32CS_INHERIT 0x80000000	Indique que le handle instantané doit être héridable.
TH32CS_SNAPALL	Inclut tous les processus et threads du système, ainsi que les tas et modules du processus spécifiés dans th32ProcessID. Équivaut à spécifier les valeurs TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPPROCESS et TH32CS_SNAPTHREAD combinées à l’aide d’une opération OR (« \| »).
TH32CS_SNAPHEAPLIST 0x00000001	Inclut tous les tas du processus spécifié dans th32ProcessID dans le instantané. Pour énumérer les tas, consultez Heap32ListFirst.
TH32CS_SNAPMODULE 0x00000008	Inclut tous les modules du processus spécifiés dans th32ProcessID dans le instantané. Pour énumérer les modules, consultez Module32First. Si la fonction échoue avec ERROR_BAD_LENGTH, réessayez la fonction jusqu’à ce qu’elle réussisse. Windows 64 bits : L’utilisation de cet indicateur dans un processus 32 bits inclut les modules 32 bits du processus spécifié dans th32ProcessID, tandis que son utilisation dans un processus 64 bits inclut les modules 64 bits. Pour inclure les modules 32 bits du processus spécifiés dans th32ProcessID à partir d’un processus 64 bits, utilisez l’indicateur TH32CS_SNAPMODULE32 .
TH32CS_SNAPMODULE32 0x00000010	Inclut tous les modules 32 bits du processus spécifié dans th32ProcessID dans le instantané lorsqu’ils sont appelés à partir d’un processus 64 bits. Cet indicateur peut être combiné avec TH32CS_SNAPMODULE ou TH32CS_SNAPALL. Si la fonction échoue avec ERROR_BAD_LENGTH, réessayez la fonction jusqu’à ce qu’elle réussisse.
TH32CS_SNAPPROCESS 0x00000002	Inclut tous les processus du système dans le instantané. Pour énumérer les processus, consultez Process32First.
TH32CS_SNAPTHREAD 0x00000004	Inclut tous les threads du système dans le instantané. Pour énumérer les threads, consultez Thread32First. Pour identifier les threads qui appartiennent à un processus spécifique, comparez son identificateur de processus au membre th32OwnerProcessID de la structure THREADENTRY32 lors de l’énumération des threads.

[in] th32ProcessID

Identificateur de processus du processus à inclure dans le instantané. Ce paramètre peut être égal à zéro pour indiquer le processus actuel. Ce paramètre est utilisé lorsque la valeur TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPMODULE32 ou TH32CS_SNAPALL est spécifiée. Sinon, il est ignoré et tous les processus sont inclus dans le instantané.

Si le processus spécifié est le processus inactif ou l’un des processus CSRSS, cette fonction échoue et le dernier code d’erreur est ERROR_ACCESS_DENIED , car leurs restrictions d’accès empêchent le code au niveau de l’utilisateur de les ouvrir.

Si le processus spécifié est un processus 64 bits et que l’appelant est un processus 32 bits, cette fonction échoue et le dernier code d’erreur est ERROR_PARTIAL_COPY (299).

Valeur retournée

Si la fonction réussit, elle retourne un handle ouvert au instantané spécifié.

Si la fonction échoue, elle retourne INVALID_HANDLE_VALUE. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError. Les codes d’erreur possibles incluent ERROR_BAD_LENGTH.

Remarques

Les instantané prises par cette fonction sont examinées par les autres fonctions d’aide de l’outil pour fournir leurs résultats. L’accès au instantané est en lecture seule. Le handle instantané agit comme un handle d’objet et est soumis aux mêmes règles concernant les processus et les threads dans lesquels il est valide.

Pour énumérer les états de tas ou de module pour tous les processus, spécifiez TH32CS_SNAPALL et définissez th32ProcessID sur zéro. Ensuite, pour chaque processus supplémentaire dans le instantané, appelez à nouveau CreateToolhelp32Snapshot, en spécifiant son identificateur de processus et la valeur TH32CS_SNAPHEAPLIST ou TH32_SNAPMODULE.

Lors de la prise d’instantanés qui incluent des tas et des modules pour un processus autre que le processus actuel, la fonction CreateToolhelp32Snapshot peut échouer ou retourner des informations incorrectes pour diverses raisons. Par exemple, si la table de données du chargeur dans le processus cible est endommagée ou n’est pas initialisée, ou si la liste des modules change pendant l’appel de la fonction à la suite du chargement ou du déchargement des DLL, la fonction peut échouer avec ERROR_BAD_LENGTH ou un autre code d’erreur. Vérifiez que le processus cible n’a pas été démarré dans un état suspendu, puis réessayez d’appeler la fonction. Si la fonction échoue avec ERROR_BAD_LENGTH lorsqu’elle est appelée avec TH32CS_SNAPMODULE ou TH32CS_SNAPMODULE32, appelez à nouveau la fonction jusqu’à ce qu’elle réussisse.

Les indicateurs TH32CS_SNAPMODULE et TH32CS_SNAPMODULE32 ne récupèrent pas de handles pour les modules qui ont été chargés avec le LOAD_LIBRARY_AS_DATAFILE ou des indicateurs similaires. Pour plus d’informations, consultez LoadLibraryEx.

Pour détruire le instantané, utilisez la fonction CloseHandle.

Notez que vous pouvez utiliser la fonction QueryFullProcessImageName pour récupérer le nom complet d’une image exécutable pour les processus 32 et 64 bits à partir d’un processus 32 bits.

Exemples

Pour obtenir un exemple, consultez Prise d’un instantané et Affichage des processus.

Configuration requise


Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	tlhelp32.h
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll