GetModuleHandleA, fonction (libloaderapi.h)

Article
08/24/2023

Récupère un handle de module pour le module spécifié. Le module doit avoir été chargé par le processus appelant.

Pour éviter les conditions de concurrence décrites dans la section Notes, utilisez la fonction GetModuleHandleEx .

Syntaxe

HMODULE GetModuleHandleA(
  [in, optional] LPCSTR lpModuleName
);

Paramètres

[in, optional] lpModuleName

Nom du module chargé (fichier .dll ou .exe). Si l’extension de nom de fichier est omise, l’extension de bibliothèque par défaut .dll est ajoutée. La chaîne de nom de fichier peut inclure un caractère de point de fin (.) pour indiquer que le nom du module n’a pas d’extension. La chaîne n’a pas besoin de spécifier de chemin d’accès. Lorsque vous spécifiez un chemin d’accès, veillez à utiliser des barres obliques inverses (\), et non des barres obliques (/). Le nom est comparé (indépendamment de la casse) aux noms des modules actuellement mappés dans l’espace d’adressage du processus appelant.

Si ce paramètre a la valeur NULL, GetModuleHandle retourne un handle au fichier utilisé pour créer le processus appelant (fichier .exe).

La fonction GetModuleHandle ne récupère pas de handles pour les modules qui ont été chargés à l’aide de l’indicateur LOAD_LIBRARY_AS_DATAFILE . Pour plus d’informations, consultez LoadLibraryEx.

Valeur retournée

Si la fonction réussit, la valeur de retour est un handle pour le module spécifié.

Si la fonction échoue, la valeur de retour est NULL. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Notes

Le handle retourné n’est ni global ni pouvant être hérité. Il ne peut pas être dupliqué ou utilisé par un autre processus.

Si lpModuleName n’inclut pas de chemin et qu’il existe plusieurs modules chargés avec le même nom de base et la même extension, vous ne pouvez pas prédire le handle de module qui sera retourné. Pour contourner ce problème, vous pouvez spécifier un chemin d’accès, utiliser des assemblys côte à côte ou utiliser GetModuleHandleEx pour spécifier un emplacement mémoire plutôt qu’un nom de DLL.

La fonction GetModuleHandle retourne un handle à un module mappé sans incrémenter son nombre de références. Toutefois, si ce handle est passé à la fonction FreeLibrary , le nombre de références du module mappé est décrémenté. Par conséquent, ne passez pas de handle retourné par GetModuleHandle à la fonction FreeLibrary . Cela peut entraîner le démappement prématuré d’un module DLL.

Cette fonction doit être utilisée avec soin dans une application multithread. Il n’existe aucune garantie que le handle de module reste valide entre le moment où cette fonction retourne le handle et le moment où il est utilisé. Par exemple, supposons qu’un thread récupère un handle de module, mais avant d’utiliser le handle, un deuxième thread libère le module. Si le système charge un autre module, il peut réutiliser le handle de module qui a été libéré récemment. Par conséquent, le premier thread aurait un handle pour un module différent de celui prévu.

Exemples

Pour obtenir un exemple, consultez Utilisation de pinceaux.

Notes

L’en-tête libloaderapi.h définit GetModuleHandle en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Spécifications


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	libloaderapi.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll