Funzione GetModuleHandleExW (libloaderapi.h)

Articolo
02/05/2024

Recupera un handle di modulo per il modulo specificato e incrementa il conteggio dei riferimenti del modulo, a meno che non venga specificato GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT. Il modulo deve essere stato caricato dal processo chiamante.

Sintassi

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

Parametri

[in] dwFlags

Questo parametro può essere zero o uno o più dei valori seguenti. Se il conteggio dei riferimenti del modulo viene incrementato, il chiamante deve usare la funzione FreeLibrary per decrementare il conteggio dei riferimenti quando l'handle del modulo non è più necessario.

GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS (0x00000004)

Il parametro lpModuleName è un indirizzo nel modulo.

GET_MODULE_HANDLE_EX_FLAG_PIN (0x00000001)

Il modulo rimane caricato fino al termine del processo, indipendentemente dal numero di chiamate a FreeLibrary .

Questa opzione non può essere usata con GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT.

GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT (0x00000002)

Il conteggio dei riferimenti per il modulo non viene incrementato. Questa opzione equivale al comportamento di GetModuleHandle. Non passare l'handle del modulo recuperato alla funzione FreeLibrary ; in questo modo la DLL può essere annullata in modo prematuro. Per altre informazioni, vedere la sezione Osservazioni.

Questa opzione non può essere usata con GET_MODULE_HANDLE_EX_FLAG_PIN.

[in, optional] lpModuleName

Nome del modulo caricato (un file .dll o .exe) o un indirizzo nel modulo (se dwFlags è GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS).

Per un nome di modulo, se l'estensione del nome file viene omessa, viene aggiunta l'estensione della libreria predefinita .dll. La stringa del nome file può includere un carattere punto finale (.) per indicare che il nome del modulo non ha estensione. La stringa non deve specificare un percorso. Quando si specifica un percorso, assicurarsi di usare le barre rovesciata (\), non le barre (/). Il nome viene confrontato (in modo indipendente) con i nomi dei moduli attualmente mappati nello spazio degli indirizzi del processo chiamante.

Se questo parametro è NULL, la funzione restituisce un handle al file usato per creare il processo chiamante (.exe file).

[out] phModule

Handle per il modulo specificato. Se la funzione ha esito negativo, questo parametro è NULL.

La funzione GetModuleHandleEx non recupera handle per i moduli caricati usando il flag LOAD_LIBRARY_AS_DATAFILE . Per altre informazioni, vedere LoadLibraryEx.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per ottenere informazioni estese sull'errore, vedere GetLastError.

Commenti

L'handle restituito non è globale o ereditabile. Non può essere duplicato o usato da un altro processo.

Se lpModuleName non include un percorso e sono presenti più moduli caricati con lo stesso nome di base ed estensione, non è possibile prevedere quale handle di modulo verrà restituito. Per risolvere questo problema, è possibile specificare un percorso, usare assembly side-by-side o specificare un percorso di memoria anziché un nome DLL nel parametro lpModuleName .

Se dwFlags contiene GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT, la funzione GetModuleHandleEx restituisce un handle a un modulo mappato senza incrementarne il conteggio dei riferimenti. Tuttavia, se questo handle viene passato alla funzione FreeLibrary , il conteggio dei riferimenti del modulo mappato verrà decrementato. Pertanto, non passare un handle restituito da GetModuleHandleEx con GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT alla funzione FreeLibrary . In questo modo, un modulo DLL può essere ignorato in modo anomalo.

Se dwFlags contiene GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT, questa funzione deve essere usata attentamente in un'applicazione multithreading. Non esiste alcuna garanzia che l'handle del modulo rimanga valido tra il momento in cui questa funzione restituisce l'handle e l'ora in cui viene usata. Ad esempio, un thread recupera un handle di modulo, ma prima di usare l'handle, un secondo thread libera il modulo. Se il sistema carica un altro modulo, potrebbe riutilizzare l'handle del modulo liberato di recente. Pertanto, il primo thread avrà un handle per un modulo diverso da quello previsto.

Per compilare un'applicazione che usa questa funzione, definire _WIN32_WINNT come 0x0501 o versione successiva. Per altre informazioni, vedere Uso delle intestazioni di Windows.

Nota

L'intestazione libloaderapi.h definisce GetModuleHandleEx come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti


Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	libloaderapi.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll