Funzione GetModuleHandleA (libloaderapi.h)

Articolo
03/11/2023

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

Per evitare le condizioni di gara descritte nella sezione Osservazioni, usare la funzione GetModuleHandleEx .

Sintassi

HMODULE GetModuleHandleA(
  [in, optional] LPCSTR lpModuleName
);

Parametri

[in, optional] lpModuleName

Nome del modulo caricato (un file di .dll o di .exe). Se l'estensione del nome file viene omessa, l'estensione della libreria predefinita .dll viene aggiunta. 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 in avanti (/). Il nome viene confrontato (in modo indipendente) ai nomi dei moduli attualmente mappati nello spazio 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 handle per i moduli caricati usando il flag di 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 informazioni dettagliate sull'errore, chiamare 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 ed è presente più di un modulo caricato con lo stesso nome di base e estensione, non è possibile prevedere quale handle del modulo verrà restituito. Per risolvere questo problema, è possibile specificare un percorso, usare assembly side-by-side o usare GetModuleHandleEx per specificare una posizione di memoria anziché un nome DLL.

La funzione GetModuleHandle restituisce un handle a un modulo mappato senza aumentare 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 ignorato prematuramente.

Questa funzione deve essere usata attentamente in un'applicazione multithreaded. Non è garantito che l'handle del modulo rimanga valido tra l'ora in cui questa funzione restituisce l'handle e l'ora in cui viene usata. Si supponga, ad esempio, che 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 che è stato liberato di recente. Pertanto, il primo thread avrà un handle per un modulo diverso rispetto a quello previsto.

Esempio

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 preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

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 (includere Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll