Funzione LoadLibraryW (libloaderapi.h)
Carica il modulo specificato nello spazio indirizzi del processo chiamante. Il modulo specificato può causare il caricamento di altri moduli.
Per altre opzioni di caricamento, usare la funzione LoadLibraryEx
Sintassi
HMODULE LoadLibraryW(
[in] LPCWSTR lpLibFileName
);
Parametri
[in] lpLibFileName
Nome del modulo. Può trattarsi di 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 LoadLibraryEx con il flag DONT_RESOLVE_DLL_REFERENCES.
Il nome specificato è il nome file del modulo e non è correlato al nome archiviato nel modulo di libreria stesso, come specificato dalla parola chiave LIBRARY
Se la stringa specifica un percorso completo, la funzione cerca solo il percorso del modulo.
Se la stringa specifica un percorso relativo o un nome di modulo senza un percorso, la funzione usa una strategia di ricerca standard per trovare il modulo; per altre informazioni, vedere la sezione Osservazioni.
Se la funzione non riesce a trovare il modulo, la funzione ha esito negativo. Quando si specifica un percorso, assicurarsi di usare le barre rovesciata (\), non le barre (/). Per altre informazioni sui percorsi, vedere Naming a File or Directory.
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.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è un handle per il modulo.
Se la funzione ha esito negativo, il valore restituito è NULL. Per ottenere informazioni estese sull'errore, chiamare GetLastError.
Osservazioni
Per abilitare o disabilitare i messaggi di errore visualizzati dal caricatore durante il caricamento della DLL, usare la funzione SetErrorMode
LoadLibrary può essere usato per caricare un modulo di libreria nello spazio degli indirizzi del processo e restituire un handle che può essere usato in GetProcAddress per ottenere l'indirizzo di una funzione DLL.
LoadLibrary può essere usato anche per caricare altri moduli eseguibili. Ad esempio, la funzione può specificare un file di .exe per ottenere un handle che può essere usato in FindResource o LoadResource. Non usare tuttavia LoadLibrary per eseguire un file di .exe. Usare invece la funzione CreateProcess
Se il modulo specificato è una DLL non già caricata per il processo chiamante, il sistema chiama la funzione DllMain della DLL con il valore DLL_PROCESS_ATTACH. Se DllMain restituisce TRUE, LoadLibrary restituisce un handle al modulo. Se DllMain restituisce FALSE, il sistema scarica la DLL dallo spazio indirizzi del processo e LoadLibrary restituisce NULL. Non è sicuro chiamare LoadLibrary da DllMain. Per altre informazioni, vedere la sezione Osservazioni in DllMain.
Gli handle di modulo non sono globali o ereditabili. Una chiamata a LoadLibrary da un processo non produce un handle che un altro processo può usare, ad esempio chiamando GetProcAddress. L'altro processo deve effettuare la propria chiamata a LoadLibrary per il modulo prima di chiamare GetProcAddress.
Se lpFileName non include un percorso e sono presenti più moduli caricati con lo stesso nome di base ed estensione, la funzione restituisce un handle al modulo caricato per primo.
Se non viene specificata alcuna estensione di file nel parametro lpFileName, viene aggiunta l'estensione della libreria predefinita .dll. Tuttavia, la stringa del nome file può includere un carattere di punto finale (.) per indicare che il nome del modulo non ha estensione. Quando non viene specificato alcun percorso, la funzione cerca moduli caricati il cui nome di base corrisponde al nome di base del modulo da caricare. Se il nome corrisponde, il caricamento ha esito positivo. In caso contrario, la funzione cerca il file.
La prima directory cercata è la directory contenente il file di immagine usato per creare il processo chiamante. Per altre informazioni, vedere la funzione CreateProcess). In questo modo è possibile trovare file DLL (Dynamic Link Library) privati associati a un processo senza aggiungere la directory installata del processo alla variabile di ambiente PATH. Se viene specificato un percorso relativo, l'intero percorso relativo viene aggiunto a ogni token nell'elenco dei percorsi di ricerca dll. Per caricare un modulo da un percorso relativo senza cercare altri percorsi, usare GetFullPathName per ottenere un percorso nonrelative e chiamare LoadLibrary con il percorso nonrelative. Per altre informazioni sull'ordine di ricerca dll, vedere Dynamic-Link Library Search Order.
Il percorso di ricerca può essere modificato usando la funzione SetDllDirectory. Questa soluzione è consigliata invece di usare SetCurrentDirectory o impostare come hardcoded il percorso completo della DLL.
Se viene specificato un percorso e esiste un file di reindirizzamento per l'applicazione, la funzione cerca il modulo nella directory dell'applicazione. Se il modulo esiste nella directory dell'applicazione, LoadLibrary ignora il percorso specificato e carica il modulo dalla directory dell'applicazione. Se il modulo non esiste nella directory dell'applicazione, LoadLibrary carica il modulo dalla directory specificata. Per altre informazioni, vedere reindirizzamento della libreria a collegamento dinamico.
Se si chiama LoadLibrary con il nome di un assembly senza specifica del percorso e l'assembly viene elencato nel manifesto compatibile con il sistema, la chiamata viene reindirizzata automaticamente all'assembly side-by-side.
Il sistema gestisce un conteggio dei riferimenti per processo in tutti i moduli caricati. La chiamata LoadLibrary incrementa il conteggio dei riferimenti. La chiamata alla funzione FreeLibrary o FreeLibraryAndExitThread decrementa il conteggio dei riferimenti. Il sistema scarica un modulo quando il numero di riferimenti raggiunge zero o quando il processo termina (indipendentemente dal conteggio dei riferimenti).
Windows Server 2003 e Windows XP: 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 LoadLibrary 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.
osservazioni sulla sicurezza
Non usare la funzione SearchPathNon fare ipotesi sulla versione del sistema operativo in base a un LoadLibrary 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.
Esempi
Per un esempio, vedere Using Run-Time Dynamic Linking.
Nota
L'intestazione libloaderapi.h definisce LoadLibrary 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 |
Vedere anche
Funzioni della libreria Dynamic-Link