GetModuleHandleExW, fonction (libloaderapi.h)
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 GetModuleHandleExW(
[in] DWORD dwFlags,
[in, optional] LPCWSTR 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’à ce que le processus soit arrêté, peu importe le nombre de fois freeLibrary est appelé.
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 transmettez pas le handle de module récupéré à la fonction FreeLibrary ; cela peut entraîner l’annulation prématuré de la DLL. Pour plus d’informations, consultez Remarques.
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 un chemin d’accès. Lors de la spécification d’un chemin d’accès, veillez à utiliser des barres obliques inverses (\), et non pas des barres obliques (/). Le nom est comparé (cas indépendamment) aux noms des modules actuellement mappés dans l’espace d’adressage du processus appelant.
Si ce paramètre est NULL, la fonction retourne un handle au fichier utilisé pour créer le processus appelant (fichier.exe).
[out] phModule
Handle du module spécifié. Si la fonction échoue, ce paramètre est NULL.
La fonction GetModuleHandleEx ne récupère pas de handles pour les modules chargés à l’aide de l’indicateur LOAD_LIBRARY_AS_DATAFILE. Pour plus d’informations, consultez LoadLibraryEx.
Valeur de retour
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.
Remarques
Le handle retourné n’est pas global ou hérite. 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 assemblys côte à côte, ou spécifier un emplacement de mémoire plutôt qu’un nom 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
Si dwFlags contient GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT, 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 l’heure à laquelle 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 en tant que 0x0501 ou version ultérieure. Pour plus d’informations, consultez Utilisation des en-têtes Windows.
Note
L’en-tête libloaderapi.h définit GetModuleHandleEx 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. Le mélange 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.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows XP [applications de bureau uniquement] |
| serveur minimum pris en charge | Windows Server 2003 [applications de bureau uniquement] |
| plateforme cible | Windows |
| d’en-tête | libloaderapi.h (include Windows.h) |
| bibliothèque | Kernel32.lib |
| DLL | Kernel32.dll |
Voir aussi
fonctions de bibliothèque Dynamic-Link