GetModuleHandleExW-Funktion (libloaderapi.h)

Artikel
02/05/2024

Ruft ein Modulhandle für das angegebene Modul ab und erhöht die Verweisanzahl des Moduls, es sei denn, GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT angegeben wird. Das Modul muss vom aufrufenden Prozess geladen worden sein.

Syntax

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

Parameter

[in] dwFlags

Dieser Parameter kann null oder ein oder mehrere der folgenden Werte sein. Wenn die Verweisanzahl des Moduls erhöht wird, muss der Aufrufer die FreeLibrary-Funktion verwenden, um die Verweisanzahl zu verringern, wenn das Modulhandle nicht mehr benötigt wird.

GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS (0x00000004)

Der parameter lpModuleName ist eine Adresse im Modul.

GET_MODULE_HANDLE_EX_FLAG_PIN (0x00000001)

Das Modul bleibt geladen, bis der Prozess beendet wird, unabhängig davon, wie oft FreeLibrary aufgerufen wird.

Diese Option kann nicht mit GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT verwendet werden.

GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT (0x00000002)

Die Referenzanzahl für das Modul wird nicht erhöht. Diese Option entspricht dem Verhalten von GetModuleHandle. Übergeben Sie das abgerufene Modulhandle nicht an die FreeLibrary-Funktion . Dies kann dazu führen, dass die DLL vorzeitig aufgehoben wird. Weitere Informationen finden Sie in den Hinweisen.

Diese Option kann nicht mit GET_MODULE_HANDLE_EX_FLAG_PIN verwendet werden.

[in, optional] lpModuleName

Der Name des geladenen Moduls (entweder eine .dll- oder .exe datei) oder eine Adresse im Modul (wenn dwFlags GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS ist).

Wenn für einen Modulnamen die Dateinamenerweiterung weggelassen 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, umgekehrte Schrägstriche (\) und keine Schrägstriche (/) zu verwenden. Der Name wird (unabhängig von Groß-/Kleinschreibung) mit den Namen der Module verglichen, die derzeit dem Adressraum des aufrufenden Prozesses zugeordnet sind.

Wenn dieser Parameter NULL ist, gibt die Funktion ein Handle an die Datei zurück, die zum Erstellen des aufrufenden Prozesses (.exe Datei) verwendet wird.

[out] phModule

Ein Handle für das angegebene Modul. Wenn die Funktion fehlschlägt, ist NULLdieser Parameter .

Die GetModuleHandleEx-Funktion ruft keine Handles für Module ab, die mit dem flag LOAD_LIBRARY_AS_DATAFILE geladen wurden. Weitere Informationen finden Sie unter LoadLibraryEx.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Informationen zu erweiterten Fehlern finden Sie unter GetLastError.

Hinweise

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 mehr als ein geladenes Modul mit demselben Basisnamen und derselben Erweiterung vorhanden ist, können Sie nicht vorhersagen, welches Modulhandle zurückgegeben wird. Um dieses Problem zu umgehen, können Sie einen Pfad angeben, parallele Assemblys verwenden oder einen Speicherort anstelle eines DLL-Namens im parameter lpModuleName angeben.

Wenn dwFlags GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT enthält, gibt die GetModuleHandleEx-Funktion ein Handle an ein zugeordnetes Modul zurück, ohne die Verweisanzahl zu erhöhen. Wenn dieses Handle jedoch an die FreeLibrary-Funktion übergeben wird, wird die Verweisanzahl des zugeordneten Moduls verringert. Übergeben Sie daher kein von GetModuleHandleEx zurückgegebenes Handle mit GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT an die FreeLibrary-Funktion . Dies kann dazu führen, dass die Mappe eines DLL-Moduls vorzeitig aufgehoben wird.

Wenn dwFlags GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT enthält, muss diese Funktion in einer Multithreadanwendung sorgfältig verwendet werden. Es gibt keine Garantie, dass das Modulhandle zwischen dem Zeitpunkt, zu dem diese Funktion das Handle zurückgibt, und dem Zeitpunkt, zu dem es verwendet wird, gültig bleibt. Beispielsweise ruft ein Thread ein Modulhandle ab, aber bevor er das Handle verwendet, gibt ein zweiter Thread das Modul frei. Wenn das System ein anderes Modul lädt, kann es das modulhandle wiederverwenden, das kürzlich freigegeben wurde. Daher verfügt der erste Thread über ein anderes Handle für ein Modul als das beabsichtigte.

Um eine Anwendung zu kompilieren, die diese Funktion verwendet, definieren Sie _WIN32_WINNT als 0x0501 oder höher. Weitere Informationen finden Sie unter Verwenden der Windows-Header.

Hinweis

Der libloaderapi.h Header definiert GetModuleHandleEx 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


Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	libloaderapi.h (Einschließen von Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll