Funzione GetModuleHandleExA (libloaderapi.h)

Articolo
03/11/2023

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

Sintassi

BOOL GetModuleHandleExA(
  [in]           DWORD   dwFlags,
  [in, optional] LPCSTR  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 decrerere 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 finché il processo non viene terminato, indipendentemente dal numero di volte in cui viene chiamato FreeLibrary .

Questa opzione non può essere usata con GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT.

GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT (0x00000002)

Il numero di 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 prematuramente. 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 del modulo, 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, 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 di 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 sull'errore estese, 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 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 specificare una posizione 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 prematuramente.

Se dwFlags contiene GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT, questa funzione deve essere usata attentamente in un'applicazione multithreading. 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. 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 che è stato 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 versioni successive. 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 preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice non codificato 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