Funzione LoadLibraryExA (libloaderapi.h)
Carica il modulo specificato nello spazio indirizzi del processo chiamante. Il modulo specificato può causare il caricamento di altri moduli.
Sintassi
HMODULE LoadLibraryExA(
[in] LPCSTR lpLibFileName,
HANDLE hFile,
[in] DWORD dwFlags
);
Parametri
[in] lpLibFileName
Stringa che specifica il nome file del modulo da caricare. Questo nome non è correlato al nome archiviato in un modulo di libreria stesso, come specificato dalla parola chiave LIBRARY
Il modulo può essere un modulo di libreria (un file .dll) o un modulo eseguibile (un file .exe). Se il modulo specificato è un modulo eseguibile, le importazioni statiche non vengono caricate; Il modulo viene invece caricato come se fosse stato specificato DONT_RESOLVE_DLL_REFERENCES. Per altre informazioni, vedere il parametro dwFlags
Se la stringa specifica un nome di modulo senza un percorso e l'estensione del nome file viene omessa, la funzione aggiunge l'estensione di libreria predefinita ".DLL" al nome del modulo. Per impedire alla funzione di aggiungere ".DLL" al nome del modulo, includere un carattere punto finale (.) nella stringa del nome del modulo.
Se la stringa specifica un percorso completo, la funzione cerca solo il percorso del modulo. Quando si specifica un percorso, assicurarsi di usare le barre rovesciata (\), non le barre (/). Per altre informazioni sui percorsi, vedere Denominazione di file, percorsi e spazi dei nomi.
Se la stringa specifica un nome di modulo senza un percorso e più moduli caricati hanno lo stesso nome di base ed estensione, la funzione restituisce un handle al modulo caricato per primo.
Se la stringa specifica un nome di modulo senza un percorso e un modulo con lo stesso nome non è già caricato oppure se la stringa specifica un nome di modulo con un percorso relativo, la funzione cerca il modulo specificato. La funzione cerca anche i moduli se il caricamento del modulo specificato fa sì che il sistema carichi altri moduli associati, ovvero se il modulo presenta dipendenze. Le directory in cui viene eseguita la ricerca e l'ordine in cui viene eseguita la ricerca dipendono dal percorso specificato e dal parametro dwFlags. Per altre informazioni, vedere Osservazioni.
Se la funzione non riesce a trovare il modulo o una delle relative dipendenze, la funzione ha esito negativo.
hFile
Questo parametro è riservato per un uso futuro. Deve essere NULL.
[in] dwFlags
Azione da eseguire durante il caricamento del modulo. Se non vengono specificati flag, il comportamento di questa funzione è identico a quello della funzione LoadLibrary
Valore | Significato |
---|---|
|
Se questo valore viene usato e il modulo eseguibile è una DLL, il sistema non chiama DllMain per l'inizializzazione e la terminazione del processo e del thread. Inoltre, il sistema non carica moduli eseguibili aggiuntivi a cui fa riferimento il modulo specificato.
Nota Non usare questo valore; viene fornito solo per la compatibilità con le versioni precedenti. Se si prevede di accedere solo a dati o risorse nella DLL, usare LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE o LOAD_LIBRARY_AS_IMAGE_RESOURCE o entrambi. In caso contrario, caricare la libreria come dll o modulo eseguibile usando la funzione LoadLibrary.
|
|
Se questo valore viene usato, il sistema non controlla regole di AppLocker o applica criteri di restrizione software per la DLL. Questa azione si applica solo alla DLL caricata e non alle relative dipendenze. Questo valore è consigliato per l'uso nei programmi di installazione che devono eseguire DLL estratte durante l'installazione.
Windows Server 2008 R2 e Windows 7: Nei sistemi con KB2532445 installato, il chiamante deve essere in esecuzione come "LocalSystem" o "TrustedInstaller"; in caso contrario, il sistema ignora questo flag. Per altre informazioni, vedere "È possibile aggirare le regole di AppLocker usando una macro di Office in un computer che esegue Windows 7 o Windows Server 2008 R2" nella Guida e supporto tecnico della Knowledge Base all'indirizzo https://support.microsoft.com/kb/2532445. Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: AppLocker è stato introdotto in Windows 7 e Windows Server 2008 R2. |
|
Se questo valore viene usato, il sistema esegue il mapping del file nello spazio indirizzi virtuale del processo chiamante come se fosse un file di dati. Non viene eseguita alcuna operazione per eseguire o preparare l'esecuzione del file mappato. Pertanto, non è possibile chiamare funzioni come GetModuleFileName, GetModuleHandle o GetProcAddress con questa DLL. L'uso di questo valore causa la generazione di una violazione di accesso da parte delle scritture nella memoria di sola lettura. Usare questo flag quando si vuole caricare una DLL solo per estrarre messaggi o risorse da esso.
Questo valore può essere usato con LOAD_LIBRARY_AS_IMAGE_RESOURCE. Per altre informazioni, vedere Osservazioni. |
|
Analogamente a LOAD_LIBRARY_AS_DATAFILE, ad eccezione del fatto che il file DLL viene aperto con accesso in scrittura esclusivo per il processo chiamante. Altri processi non possono aprire il file DLL per l'accesso in scrittura mentre è in uso. Tuttavia, la DLL può comunque essere aperta da altri processi.
Questo valore può essere usato con LOAD_LIBRARY_AS_IMAGE_RESOURCE. Per altre informazioni, vedere Osservazioni. Windows Server 2003 e Windows XP: Questo valore non è supportato fino a Windows Vista. |
|
Se questo valore viene usato, il sistema esegue il mapping del file nello spazio indirizzi virtuale del processo come file di immagine.
Tuttavia, il caricatore non carica le importazioni statiche o esegue gli altri passaggi di inizializzazione consueti. Usare questo flag quando si vuole caricare una DLL solo per estrarre messaggi o risorse da esso.
A meno che l'applicazione non dipenda dal file con il layout in memoria di un'immagine, questo valore deve essere usato con LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE o LOAD_LIBRARY_AS_DATAFILE. Per altre informazioni, vedere la sezione Osservazioni. Windows Server 2003 e Windows XP: Questo valore non è supportato fino a Windows Vista. |
|
Se questo valore viene usato, la directory di installazione dell'applicazione viene cercata la DLL e le relative dipendenze. Le directory nel percorso di ricerca standard non vengono cercate. Questo valore non può essere combinato con LOAD_WITH_ALTERED_SEARCH_PATH.
Windows 7, Windows Server 2008 R2, Windows Vista e Windows Server 2008: Questo valore richiede KB2533623 da installare. Windows Server 2003 e Windows XP: Questo valore non è supportato. |
|
Questo valore è una combinazione di LOAD_LIBRARY_SEARCH_APPLICATION_DIR, LOAD_LIBRARY_SEARCH_SYSTEM32e LOAD_LIBRARY_SEARCH_USER_DIRS. Le directory nel percorso di ricerca standard non vengono cercate. Questo valore non può essere combinato con LOAD_WITH_ALTERED_SEARCH_PATH.
Questo valore rappresenta il numero massimo consigliato di directory che un'applicazione deve includere nel percorso di ricerca della DLL. Windows 7, Windows Server 2008 R2, Windows Vista e Windows Server 2008: Questo valore richiede KB2533623 da installare. Windows Server 2003 e Windows XP: Questo valore non è supportato. |
|
Se questo valore viene usato, la directory che contiene la DLL viene aggiunta temporaneamente all'inizio dell'elenco di directory in cui viene eseguita la ricerca delle dipendenze della DLL. Le directory nel percorso di ricerca standard non vengono cercate.
Il parametro lpFileName deve specificare un percorso completo. Questo valore non può essere combinato con LOAD_WITH_ALTERED_SEARCH_PATH. Ad esempio, se Lib2.dll è una dipendenza di C:\Dir1\Lib1.dll, loading Lib1.dll with this value causes the system to search for Lib2.dll solo in C:\Dir1. Per cercare Lib2.dll in C:\Dir1 e tutte le directory nel percorso di ricerca dll, combinare questo valore con LOAD_LIBRARY_SEARCH_DEFAULT_DIRS. Windows 7, Windows Server 2008 R2, Windows Vista e Windows Server 2008: Questo valore richiede KB2533623 da installare. Windows Server 2003 e Windows XP: Questo valore non è supportato. |
|
Se si usa questo valore, %windows%\system32 viene cercata la DLL e le relative dipendenze.
Le directory nel percorso di ricerca standard non vengono cercate. Questo valore non può essere combinato con LOAD_WITH_ALTERED_SEARCH_PATH.
Windows 7, Windows Server 2008 R2, Windows Vista e Windows Server 2008: Questo valore richiede KB2533623 da installare. Windows Server 2003 e Windows XP: Questo valore non è supportato. |
|
Se questo valore viene usato, le directory aggiunte usando il AddDllDirectory o la funzione SetDllDirectory vengono cercate la DLL e le relative dipendenze. Se sono state aggiunte più directory, l'ordine in cui viene eseguita la ricerca delle directory non è specificato. Le directory nel percorso di ricerca standard non vengono cercate. Questo valore non può essere combinato con LOAD_WITH_ALTERED_SEARCH_PATH.
Windows 7, Windows Server 2008 R2, Windows Vista e Windows Server 2008: Questo valore richiede KB2533623 da installare. Windows Server 2003 e Windows XP: Questo valore non è supportato. |
|
Se questo valore viene usato e lpFileName specifica un percorso assoluto, il sistema usa la strategia di ricerca di file alternativa descritta nella sezione Osservazioni per trovare moduli eseguibili associati che il modulo specificato causa il caricamento. Se questo valore viene usato e lpFileName specifica un percorso relativo, il comportamento non è definito.
Se questo valore non viene utilizzato o se lpFileName non specifica un percorso, il sistema utilizza la strategia di ricerca standard descritta nella sezione Osservazioni per trovare moduli eseguibili associati che il modulo specificato causa il caricamento. Questo valore non può essere combinato con alcun flag di LOAD_LIBRARY_SEARCH. |
|
Specifica che la firma digitale dell'immagine binaria deve essere controllata in fase di caricamento.
Questo valore richiede Windows 8.1, Windows 10 o versione successiva. |
|
Se questo valore viene usato, il caricamento di una DLL per l'esecuzione dalla directory corrente è consentito solo se si trova in una directory nell'elenco Caricamento sicuro. |
Valore restituito
Se la funzione ha esito positivo, il valore restituito è un handle per il modulo caricato.
Se la funzione ha esito negativo, il valore restituito è NULL. Per ottenere informazioni estese sull'errore, chiamare GetLastError.
Osservazioni
La funzione
loadLibraryEx può caricare un modulo DLL senza chiamare la funzione dllmaindella DLL. - LoadLibraryEx può caricare un modulo in modo ottimizzato per il caso in cui il modulo non verrà mai eseguito, caricando il modulo come se fosse un file di dati.
- LoadLibraryEx è possibile trovare moduli e moduli associati usando una delle due strategie di ricerca oppure eseguire ricerche in un set di directory specifico del processo.
Il processo chiamante può usare l'handle restituito da LoadLibraryEx per identificare il modulo nelle chiamate al GetProcAddress, FindResourcee funzioni di LoadResource.
Per abilitare o disabilitare i messaggi di errore visualizzati dal caricatore durante il caricamento della DLL, usare la funzione SetErrorMode
Non è possibile chiamare LoadLibraryEx da DllMain. Per altre informazioni, vedere la sezione Osservazioni in DllMain.
Visual C++: Il compilatore Visual C++ supporta una sintassi che consente di dichiarare variabili locali del thread: _declspec(thread). Se si usa questa sintassi in una DLL, non sarà possibile caricare la DLL in modo esplicito usando LoadLibraryEx nelle versioni di Windows precedenti a Windows Vista. Se la DLL verrà caricata in modo esplicito, è necessario usare le funzioni di archiviazione locale del thread anziché _declspec(thread). Per un esempio, vedere Using Thread Local Storage in a Dynamic Link Library.
Caricamento di una DLL come file di dati o risorsa immagine
I valori LOAD_LIBRARY_AS_DATAFILE, LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVEe LOAD_LIBRARY_AS_IMAGE_RESOURCE influiscono sul conteggio dei riferimenti per processo e sul caricamento del modulo specificato. Se uno di questi valori viene specificato per il parametro dwFlags, il caricatore verifica se il modulo è già stato caricato dal processo come DLL eseguibile. In tal caso, significa che il modulo è già mappato nello spazio indirizzi virtuale del processo chiamante. In questo caso, LoadLibraryEx restituisce un handle alla DLL e incrementa il conteggio dei riferimenti dll. Se il modulo DLL non è già stato caricato come DLL, il sistema esegue il mapping del modulo come file di dati o immagine e non come DLL eseguibile. In questo caso, LoadLibraryEx restituisce un handle per i dati caricati o il file di immagine, ma non incrementa il conteggio dei riferimenti per il modulo e non rende visibile il modulo a funzioni come CreateToolhelp32Snapshot o EnumProcessModules.Se LoadLibraryEx viene chiamato due volte per lo stesso file con LOAD_LIBRARY_AS_DATAFILE, LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVEo LOAD_LIBRARY_AS_IMAGE_RESOURCE, vengono creati due mapping separati per il file.
Quando si usa il valore LOAD_LIBRARY_AS_IMAGE_RESOURCE, il modulo viene caricato come immagine usando l'espansione dell'allineamento della sezione PE (Portable Executable). Gli indirizzi virtuali relativi non devono essere mappati agli indirizzi del disco, quindi le risorse possono essere recuperate più rapidamente dal modulo. Se si specifica LOAD_LIBRARY_AS_IMAGE_RESOURCE si impedisce ad altri processi di modificare il modulo durante il caricamento.
A meno che un'applicazione non dipenda da caratteristiche specifiche del mapping delle immagini, il valore di LOAD_LIBRARY_AS_IMAGE_RESOURCE deve essere usato con LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE o LOAD_LIBRARY_AS_DATAFILE. In questo modo il caricatore può scegliere se caricare il modulo come risorsa immagine o un file di dati, selezionando quale opzione consente al sistema di condividere le pagine in modo più efficace. Le funzioni delle risorse, ad esempio FindResource possono usare entrambi i mapping.
Per determinare come è stato caricato un modulo, usare una delle macro seguenti per testare l'handle restituito da LoadLibraryEx.
#define LDR_IS_DATAFILE(handle) (((ULONG_PTR)(handle)) & (ULONG_PTR)1)
#define LDR_IS_IMAGEMAPPING(handle) (((ULONG_PTR)(handle)) & (ULONG_PTR)2)
#define LDR_IS_RESOURCE(handle) (LDR_IS_IMAGEMAPPING(handle) || LDR_IS_DATAFILE(handle))
Nella tabella seguente vengono descritte queste macro.
Macro | Descrizione |
---|---|
LDR_IS_DATAFILE( handle) | Se questa macro restituisce TRUE, il modulo è stato caricato come file di dati (LOAD_LIBRARY_AS_DATAFILE o LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE). |
LDR_IS_IMAGEMAPPING( handle) | Se questa macro restituisce TRUE, il modulo è stato caricato come file di immagine (LOAD_LIBRARY_AS_IMAGE_RESOURCE). |
LDR_IS_RESOURCE( handle) | Se questa macro restituisce TRUE, il modulo è stato caricato come file di dati o come file di immagine. |
Usare la funzione
ricerca di DLL e dipendenze
Il percorso di ricerca è il set di directory in cui viene eseguita la ricerca di una DLL. La funzione LoadLibraryEx può cercare una DLL usando un percorso di ricerca standard o un percorso di ricerca modificato oppure può usare un percorso di ricerca specifico del processo stabilito con le funzioni SetDefaultDllDirectories e AddDllDirectory. Per un elenco di directory e l'ordine in cui vengono cercati, vedere Dynamic-Link Ordine di ricerca della libreria.La funzione LoadLibraryEx
- Il nome file viene specificato senza un percorso e il nome del file di base non corrisponde al nome del file di base di un modulo caricato e nessuno dei flag LOAD_LIBRARY_SEARCH viene usato.
- Viene specificato un percorso, ma non viene utilizzato LOAD_WITH_ALTERED_SEARCH_PATH.
- L'applicazione non ha specificato un percorso di ricerca DLL predefinito per il processo usando SetDefaultDllDirectories.
Se lpFileName specifica un percorso relativo, l'intero percorso relativo viene aggiunto a ogni token nel percorso di ricerca della DLL. Per caricare un modulo da un percorso relativo senza cercare altri percorsi, usare GetFullPathName per ottenere un percorso nonrelative e chiamare LoadLibraryEx con il percorso nonrelative. Se il modulo viene caricato come file di dati e il percorso relativo inizia con "." o "..", il percorso relativo viene considerato come percorso assoluto.
Se lpFileName specifica un percorso assoluto e dwFlags è impostato su LOAD_WITH_ALTERED_SEARCH_PATH, LoadLibraryEx usa il percorso di ricerca modificato. Il comportamento non è definito quando viene impostato LOAD_WITH_ALTERED_SEARCH_PATH flag e lpFileName specifica un percorso relativo.
La funzione SetDllDirectory può essere usata per modificare il percorso di ricerca. Questa soluzione è preferibile rispetto all'uso di SetCurrentDirectory o impostare come hardcoded il percorso completo della DLL. Tenere tuttavia presente che l'uso di SetDllDirectory disabilita in modo efficace la modalità di ricerca DLL sicura mentre la directory specificata si trova nel percorso di ricerca e non è thread-safe. Se possibile, è consigliabile usare AddDllDirectory per modificare un percorso di ricerca di processo predefinito. Per altre informazioni, vedere Dynamic-Link Library Search Order.
Un'applicazione può specificare le directory in cui cercare una singola chiamata LoadLibraryEx usando i flag LOAD_LIBRARY_SEARCH_*. Se si specificano più LOAD_LIBRARY_SEARCH flag, le directory vengono cercate nell'ordine seguente:
- Directory contenente la DLL (LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR). Questa directory viene cercata solo per le dipendenze della DLL da caricare.
- Directory dell'applicazione (LOAD_LIBRARY_SEARCH_APPLICATION_DIR).
- I percorsi aggiunti in modo esplicito al percorso di ricerca dell'applicazione con la funzione AddDllDirectory
( LOAD_LIBRARY_SEARCH_USER_DIRS ) o la funzioneSetDllDirectory . Se sono stati aggiunti più percorsi, l'ordine in cui vengono cercati i percorsi non è specificato. - Directory System32 (LOAD_LIBRARY_SEARCH_SYSTEM32).
Windows 7, Windows Server 2008 R2, Windows Vista e Windows Server 2008: I flag LOAD_LIBRARY_SEARCH_ sono disponibili nei sistemi in cui è installato KB2533623. Per determinare se i flag sono disponibili, usare GetProcAddress per ottenere l'indirizzo della AddDllDirectory, RemoveDllDirectoryo funzione SetDefaultDllDirectories. Se GetProcAddress ha esito positivo, i flag di LOAD_LIBRARY_SEARCH_ possono essere usati con LoadLibraryEx.
Se l'applicazione ha usato la funzione SetDefaultDllDirectories per stabilire un percorso di ricerca DLL per il processo e nessuno dei flag LOAD_LIBRARY_SEARCH_* vengono usati, la funzione LoadLibraryEx usa il percorso di ricerca DLL del processo anziché il percorso di ricerca standard.
Se viene specificato un percorso e all'applicazione è associato un file di reindirizzamento, la funzione LoadLibraryEx
Se si chiama LoadLibraryEx con il nome di un assembly senza specifica del percorso e l'assembly è elencato nel manifesto compatibile con il sistema, la chiamata viene reindirizzata automaticamente all'assembly side-by-side.
osservazioni sulla sicurezza
LOAD_LIBRARY_AS_DATAFILE non impedisce ad altri processi di modificare il modulo durante il caricamento. Poiché ciò può rendere l'applicazione meno sicura, è consigliabile usare LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE anziché LOAD_LIBRARY_AS_DATAFILE durante il caricamento di un modulo come file di dati, a meno che non sia necessario usare in modo specifico LOAD_LIBRARY_AS_DATAFILE. Se si specifica LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE si impedisce ad altri processi di modificare il modulo durante il caricamento. Non specificare LOAD_LIBRARY_AS_DATAFILE e LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE nella stessa chiamata.Non usare la funzione SearchPath
Non fare ipotesi sulla versione del sistema operativo basata su un LoadLibraryEx chiamata che cerca una DLL. Se l'applicazione è in esecuzione in un ambiente in cui la DLL non è presente legittimamente, ma una versione dannosa della DLL si trova nel percorso di ricerca, è possibile caricare la versione dannosa della DLL. Usare invece le tecniche consigliate descritte in Recupero della versione di sistema.
Per una discussione generale sui problemi di sicurezza delle DLL, vedere Dynamic-Link Library Security.
Esempi
Nell'esempio di codice seguente viene illustrata una chiamata a LoadLibraryExA.
//Load the FMAPI DLL
hLib = ::LoadLibraryEx(L"fmapi.dll", NULL, NULL);
if ( !hLib )
{
wprintf(L"Could not load fmapi.dll, Error #%d.\n", GetLastError());
return;
}
Per un esempio aggiuntivo, vedere Ricerca di testo per i numeri di codice di errore.
Nota
L'intestazione libloaderapi.h definisce LoadLibraryEx 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 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 |
Vedere anche
Funzioni della libreria Dynamic-Link
ordine di ricerca della libreria
di sicurezza della libreria