GetModuleHandleA-Funktion (libloaderapi.h)
Ruft ein Modulhandle für das angegebene Modul ab. Das Modul muss vom aufrufenden Prozess geladen worden sein.
Um die im Abschnitt "Hinweise" beschriebenen Racebedingungen zu vermeiden, verwenden Sie die GetModuleHandleEx--Funktion.
Syntax
HMODULE GetModuleHandleA(
[in, optional] LPCSTR lpModuleName
);
Parameter
[in, optional] lpModuleName
Der Name des geladenen Moduls (entweder eine .dll oder .exe Datei). Wenn die Dateinamenerweiterung nicht angegeben wird, wird die Standardbibliothekserweiterung .dll angefügt. Die Dateinamenzeichenfolge kann ein nachfolgendes Punktzeichen (.) enthalten, um anzugeben, dass der Modulname keine Erweiterung hat. Die Zeichenfolge muss keinen Pfad angeben. Achten Sie beim Angeben eines Pfads darauf, dass Umgekehrte Schrägstriche (\) und keine Schrägstriche (/) verwendet werden. Der Name wird (unabhängig von Groß-/Kleinschreibung) mit den Namen der Module verglichen, die derzeit im Adressraum des aufrufenden Prozesses zugeordnet sind.
Wenn dieser Parameter NULL ist, gibt GetModuleHandle- ein Handle für die Datei zurück, die zum Erstellen des aufrufenden Prozesses (.exe Datei) verwendet wird.
Die GetModuleHandle--Funktion ruft keine Handles für Module ab, die mit dem LOAD_LIBRARY_AS_DATAFILE-Flag geladen wurden. Weitere Informationen finden Sie unter LoadLibraryEx.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für das angegebene Modul.
Wenn die Funktion fehlschlägt, ist der Rückgabewert NULL. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.
Bemerkungen
Das zurückgegebene Handle ist nicht global oder vererbbar. Sie kann nicht dupliziert oder von einem anderen Prozess verwendet werden.
Wenn lpModuleName keinen Pfad enthält und mehrere geladene Module mit demselben Basisnamen und derselben Erweiterung vorhanden sind, können Sie nicht vorhersehen, welches Modulhandle zurückgegeben wird. Um dieses Problem zu umgehen, können Sie einen Pfad angeben, parallele Assemblysverwenden oder GetModuleHandleEx- verwenden, um einen Speicherort anstelle eines DLL-Namens anzugeben.
Die GetModuleHandle--Funktion gibt ein Handle an ein zugeordnetes Modul zurück, ohne die Referenzanzahl zu erhöhen. Wenn dieses Handle jedoch an die FreeLibrary-Funktion übergeben wird, wird die Referenzanzahl des zugeordneten Moduls verringert. Übergeben Sie daher kein Handle, das von GetModuleHandle an die FreeLibrary--Funktion zurückgegeben wird. Dies kann dazu führen, dass ein DLL-Modul vorzeitig nicht zugeordnet wird.
Diese Funktion muss in einer Multithreadanwendung sorgfältig verwendet werden. Es besteht keine Garantie dafür, dass der Modulhandle zwischen dem Zeitpunkt, zu dem diese Funktion den Handle zurückgibt, und der Zeit, zu der es verwendet wird, gültig bleibt. Angenommen, ein Thread ruft ein Modulhandle ab, aber bevor er den Handle verwendet, gibt ein zweiter Thread das Modul frei. Wenn das System ein anderes Modul lädt, könnte es den zuletzt freigegebenen Modulhandle wiederverwenden. Daher hätte der erste Thread ein Handle für ein anderes Modul als das beabsichtigte.
Beispiele
Ein Beispiel finden Sie unter Using Brushes.
Anmerkung
Der libloaderapi.h-Header definiert GetModuleHandle als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows XP [nur Desktop-Apps] |
| mindestens unterstützte Server- | Windows Server 2003 [Nur Desktop-Apps] |
| Zielplattform- | Fenster |
| Header- | libloaderapi.h (include Windows.h) |
| Library | Kernel32.lib |
| DLL- | Kernel32.dll |