Funzione GetModuleHandleW (libloaderapi.h)

Articolo
12/09/2024

Recupera un handle di modulo per il modulo specificato. Il modulo deve essere stato caricato dal processo chiamante.

Per evitare le race condition descritte nella sezione Osservazioni, usare la funzione getModuleHandleEx .

Sintassi

HMODULE GetModuleHandleW(
  [in, optional] LPCWSTR lpModuleName
);

Parametri

[in, optional] lpModuleName

Nome del modulo caricato (un file .dll o .exe). 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 di 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, GetModuleHandle restituisce un handle al file usato per creare il processo chiamante (.exe file).

La funzione GetModuleHandle non recupera gli 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 è un handle per il modulo specificato.

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

Osservazioni

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-sideoppure usare GetModuleHandleEx per specificare una posizione di memoria anziché un nome DLL.

La funzione getModuleHandle restituisce un handle a un modulo mappato senza incrementarne il numero di 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 GetModuleHandle alla funzione FreeLibrary. In questo modo, un modulo DLL può essere decompresso prematuramente.

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. Si supponga, ad esempio, che un thread recuperi 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 che è stato liberato di recente. Pertanto, il primo thread avrà un handle per un modulo diverso da quello previsto.

Esempi

Per un esempio, vedere Uso di pennelli.

Nota

L'intestazione libloaderapi.h definisce GetModuleHandle 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 non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows XP [solo app desktop]
server minimo supportato	Windows Server 2003 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	libloaderapi.h (include Windows.h)
libreria	Kernel32.lib
dll	Kernel32.dll