GetModuleHandleExA, fonction (libloaderapi.h)

Article
08/24/2023

Récupère un handle de module pour le module spécifié et incrémente le nombre de références du module, sauf si GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT est spécifié. Le module doit avoir été chargé par le processus appelant.

Syntaxe

BOOL GetModuleHandleExA(
  [in]           DWORD   dwFlags,
  [in, optional] LPCSTR  lpModuleName,
  [out]          HMODULE *phModule
);

Paramètres

[in] dwFlags

Ce paramètre peut être égal à zéro ou à une ou plusieurs des valeurs suivantes. Si le nombre de références du module est incrémenté, l’appelant doit utiliser la fonction FreeLibrary pour décrémenter le nombre de références lorsque le handle de module n’est plus nécessaire.

GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS (0x00000004)

Le paramètre lpModuleName est une adresse dans le module.

GET_MODULE_HANDLE_EX_FLAG_PIN (0x00000001)

Le module reste chargé jusqu’à l’arrêt du processus, quel que soit le nombre d’appel de FreeLibrary .

Cette option ne peut pas être utilisée avec GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT.

GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT (0x00000002)

Le nombre de références pour le module n’est pas incrémenté. Cette option équivaut au comportement de GetModuleHandle. Ne passez pas le handle de module récupéré à la fonction FreeLibrary ; Cela peut entraîner le démassement prématuré de la DLL. Pour plus d'informations, consultez la section Notes.

Cette option ne peut pas être utilisée avec GET_MODULE_HANDLE_EX_FLAG_PIN.

[in, optional] lpModuleName

Nom du module chargé (fichier .dll ou .exe) ou adresse du module (si dwFlags est GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS).

Pour un nom de module, 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é (cas indépendant) aux noms des modules actuellement mappés dans l’espace d’adressage du processus appelant.

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

[out] phModule

Handle du module spécifié. Si la fonction échoue, ce paramètre a la valeur NULL.

La fonction GetModuleHandleEx 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 différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations d’erreur étendues, consultez GetLastError.

Notes

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

Si lpModuleName n’inclut pas de chemin d’accès 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 spécifier un emplacement de mémoire plutôt qu’un nom de DLL dans le paramètre lpModuleName .

Si dwFlags contient GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT, la fonction GetModuleHandleEx 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é sera décrémenté. Par conséquent, ne passez pas de handle retourné par GetModuleHandleEx avec GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT à la fonction FreeLibrary . Cela peut entraîner la désinstallation prématurée d’un module DLL.

Si dwFlags contient GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT, cette fonction doit être utilisée avec soin dans une application multithread. Il n’est pas garanti que le handle de module reste valide entre le moment où cette fonction retourne le handle et le moment où elle est utilisée. Par exemple, 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 récemment libéré. Par conséquent, le premier thread aurait un handle pour un module différent de celui prévu.

Pour compiler une application qui utilise cette fonction, définissez _WIN32_WINNT comme 0x0501 ou version ultérieure. Pour plus d’informations, consultez Utilisation des en-têtes Windows.

Notes

L’en-tête libloaderapi.h définit GetModuleHandleEx comme un 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.

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