LoadLibraryW-Funktion (libloaderapi.h)

Lädt das angegebene Modul in den Adressraum des aufrufenden Prozesses. Das angegebene Modul kann dazu führen, dass andere Module geladen werden.

Verwenden Sie für zusätzliche Ladeoptionen die LoadLibraryEx--Funktion.

Syntax

HMODULE LoadLibraryW(
  [in] LPCWSTR lpLibFileName
);

Parameter

[in] lpLibFileName

Der Name des Moduls. Dies kann ein Bibliotheksmodul (eine .dll Datei) oder ein ausführbares Modul (eine .exe Datei) sein. Wenn es sich bei dem angegebenen Modul um ein ausführbares Modul handelt, werden statische Importe nicht geladen; Stattdessen wird das Modul geladen, als ob LoadLibraryEx mit dem DONT_RESOLVE_DLL_REFERENCES-Flag.

Der angegebene Name ist der Dateiname des Moduls und ist nicht mit dem Namen verknüpft, der im Bibliotheksmodul selbst gespeichert ist, wie durch das schlüsselwort LIBRARY in der Moduldefinitionsdatei (.def) angegeben.

Wenn die Zeichenfolge einen vollständigen Pfad angibt, durchsucht die Funktion nur diesen Pfad für das Modul.

Wenn die Zeichenfolge einen relativen Pfad oder einen Modulnamen ohne Pfad angibt, verwendet die Funktion eine standardmäßige Suchstrategie, um das Modul zu finden; weitere Informationen finden Sie in den Anmerkungen.

Wenn die Funktion das Modul nicht finden kann, schlägt die Funktion fehl. Achten Sie beim Angeben eines Pfads darauf, dass Umgekehrte Schrägstriche (\) und keine Schrägstriche (/) verwendet werden. Weitere Informationen zu Pfaden finden Sie unter Benennen einer Datei oder eines Verzeichnisses.

Wenn die Zeichenfolge einen Modulnamen ohne Pfad angibt und die Dateinamenerweiterung weggelassen wird, fügt die Funktion die Standardbibliothekserweiterung ".DLL" an den Modulnamen an. Um zu verhindern, dass die Funktion ".DLL" an den Modulnamen anfügen kann, fügen Sie ein nachfolgendes Punktzeichen (.) in die Modulnamenzeichenfolge ein.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für das Modul.

Wenn die Funktion fehlschlägt, ist der Rückgabewert NULL. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

Verwenden Sie die SetErrorMode--Funktion, um Fehlermeldungen zu aktivieren oder zu deaktivieren, die vom Ladeprogramm während der DLL-Ladevorgänge angezeigt werden.

LoadLibrary kann verwendet werden, um ein Bibliotheksmodul in den Adressraum des Prozesses zu laden und ein Handle zurückzugeben, das in GetProcAddress verwendet werden kann, um die Adresse einer DLL-Funktion abzurufen. LoadLibrary- können auch zum Laden anderer ausführbarer Module verwendet werden. Beispielsweise kann die Funktion eine .exe Datei angeben, um ein Handle abzurufen, das in FindResource- oder LoadResource-verwendet werden kann. Verwenden Sie LoadLibrary- jedoch nicht, um eine .exe Datei auszuführen. Verwenden Sie stattdessen die funktion CreateProcess.

Wenn es sich bei dem angegebenen Modul um eine DLL handelt, die noch nicht für den Aufrufvorgang geladen ist, ruft das System die dll-DllMain--Funktion mit dem wert DLL_PROCESS_ATTACH auf. Wenn DllMainTRUEzurückgibt, gibt LoadLibrary ein Handle an das Modul zurück. Wenn DllMainFALSE-zurückgibt, entlädt das System die DLL aus dem Adressraum des Prozesses und LoadLibrary gibt NULL-zurück. Es ist nicht sicher, LoadLibrary von DllMainaufzurufen. Weitere Informationen finden Sie im Abschnitt "Hinweise" in DllMain.

Modulhandles sind nicht global oder vererbbar. Ein Aufruf von LoadLibrary durch einen Prozess erzeugt keinen Handle, den ein anderer Prozess verwenden kann, z. B. beim Aufrufen GetProcAddress. Der andere Prozess muss einen eigenen Aufruf an LoadLibrary- für das Modul vornehmen, bevor GetProcAddressaufgerufen wird.

Wenn lpFileName keinen Pfad enthält und mehrere geladene Module mit demselben Basisnamen und derselben Erweiterung vorhanden sind, gibt die Funktion ein Handle an das Modul zurück, das zuerst geladen wurde.

Wenn im parameter lpFileName keine Dateinamenerweiterung angegeben wird, wird die Standardbibliothekserweiterung .dll angefügt. Die Dateinamenzeichenfolge kann jedoch ein nachfolgendes Punktzeichen (.) enthalten, um anzugeben, dass der Modulname keine Erweiterung hat. Wenn kein Pfad angegeben wird, sucht die Funktion nach geladenen Modulen, deren Basisname dem Basisnamen des zu ladenden Moduls entspricht. Wenn der Name übereinstimmt, wird die Ladevorgang erfolgreich ausgeführt. Andernfalls sucht die Funktion nach der Datei.

Das erste durchsuchte Verzeichnis ist das Verzeichnis, das die Bilddatei enthält, die zum Erstellen des aufrufenden Prozesses verwendet wird (weitere Informationen finden Sie unter der CreateProcess-Funktion). Dadurch können private DLL-Dateien (Dynamic Link Library) gefunden werden, die einem Prozess zugeordnet sind, ohne das installierte Verzeichnis des Prozesses zur PATH-Umgebungsvariable hinzuzufügen. Wenn ein relativer Pfad angegeben wird, wird der gesamte relative Pfad an jedes Token in der DLL-Suchpfadliste angefügt. Um ein Modul aus einem relativen Pfad zu laden, ohne einen anderen Pfad zu durchsuchen, verwenden Sie GetFullPathName-, um einen nichtrelativen Pfad abzurufen und LoadLibrary- mit dem nichtrelativen Pfad aufzurufen. Weitere Informationen zur DLL-Suchreihenfolge finden Sie unter Dynamic-Link Bibliothekssuchreihenfolge.

Der Suchpfad kann mithilfe der funktion SetDllDirectory geändert werden. Diese Lösung wird empfohlen, statt SetCurrentDirectory- zu verwenden oder den vollständigen Pfad zur DLL zu codieren.

Wenn ein Pfad angegeben ist und eine Umleitungsdatei für die Anwendung vorhanden ist, sucht die Funktion im Verzeichnis der Anwendung nach dem Modul. Wenn das Modul im Verzeichnis der Anwendung vorhanden ist, ignoriert LoadLibrary den angegebenen Pfad ignoriert und das Modul aus dem Verzeichnis der Anwendung lädt. Wenn das Modul nicht im Verzeichnis der Anwendung vorhanden ist, lädt LoadLibrary das Modul aus dem angegebenen Verzeichnis. Weitere Informationen finden Sie unter Dynamic Link Library Redirection.

Wenn Sie LoadLibrary mit dem Namen einer Assembly ohne Pfadspezifikation aufrufen und die Assembly im systemkompatiblen Manifest aufgeführt wird, wird der Aufruf automatisch an die parallele Assembly umgeleitet.

Das System verwaltet eine Prozessverweisanzahl für alle geladenen Module. Das Aufrufen LoadLibrary erhöht die Referenzanzahl. Durch Aufrufen der FreeLibrary oder FreeLibraryAndExitThread--Funktion wird die Verweisanzahl erhöht. Das System entlädt ein Modul, wenn die Referenzanzahl null erreicht oder der Prozess beendet wird (unabhängig von der Referenzanzahl).

Windows Server 2003 und Windows XP: Der Visual C++-Compiler unterstützt eine Syntax, mit der Sie threadlokale Variablen deklarieren können: _declspec(Thread). Wenn Sie diese Syntax in einer DLL verwenden, können Sie die DLL nicht explizit mit LoadLibrary- in Windows-Versionen vor Windows Vista laden. Wenn Die DLL explizit geladen wird, müssen Sie die lokalen Threadspeicherfunktionen anstelle von _declspec(Thread)verwenden. Ein Beispiel finden Sie unter Verwenden des lokalen Threadspeichers in einer Dynamic Link Library.