SymLoadModuleExW-Funktion (dbghelp.h)

Artikel
11/20/2024

Lädt die Symboltabelle für das angegebene Modul.

Syntax

DWORD64 IMAGEAPI SymLoadModuleExW(
  [in] HANDLE        hProcess,
  [in] HANDLE        hFile,
  [in] PCWSTR        ImageName,
  [in] PCWSTR        ModuleName,
  [in] DWORD64       BaseOfDll,
  [in] DWORD         DllSize,
  [in] PMODLOAD_DATA Data,
  [in] DWORD         Flags
);

Parameter

[in] hProcess

Ein Handle an den Prozess, der ursprünglich an die SymInitialize-Funktion übergeben wurde.

[in] hFile

Ein Handle für die Datei für das ausführbare Image. Dieses Argument wird hauptsächlich von Debuggern verwendet, bei denen der Debugger das aus einem Debuggingereignis abgerufene Dateihandle übergibt. Ein Wert von NULL- gibt an, dass hFile- nicht verwendet wird.

[in] ImageName

Der Name des ausführbaren Images. Dieser Name kann einen teilweisen Pfad, einen vollständigen Pfad oder gar keinen Pfad enthalten. Wenn die Datei nicht mit dem angegebenen Namen gefunden werden kann, wird der Suchpfad des Symbols verwendet.

[in] ModuleName

Ein Verknüpfungsname für das Modul. Wenn der Zeigerwert NULL-ist, erstellt die Bibliothek mithilfe des Basisnamens der Symboldatei einen Namen.

[in] BaseOfDll

Die Ladeadresse des Moduls. Wenn der Wert null ist, ruft die Bibliothek die Ladeadresse aus der Symboldatei ab. Die in der Symboldatei enthaltene Ladeadresse ist nicht unbedingt die tatsächliche Ladeadresse. Debugger und andere Anwendungen mit einer tatsächlichen Ladeadresse sollten beim Aufrufen dieser Funktion die echte Ladeadresse verwenden.

Wenn es sich bei dem Bild um eine PDB-Datei handelt, kann dieser Parameter nicht null sein.

[in] DllSize

Die Größe des Moduls in Byte. Wenn der Wert null ist, ruft die Bibliothek die Größe aus der Symboldatei ab. Die in der Symboldatei enthaltene Größe ist nicht unbedingt die tatsächliche Größe. Debugger und andere Anwendungen mit einer tatsächlichen Größe sollten beim Aufrufen dieser Funktion die tatsächliche Größe verwenden.

Wenn es sich bei dem Bild um eine PDB-Datei handelt, kann dieser Parameter nicht null sein.

[in] Data

Ein Zeiger auf eine MODLOAD_DATA Struktur, die andere Kopfzeilen als die standard-PE-Kopfzeile darstellt. Dieser Parameter ist optional und kann NULL-werden.

[in] Flags

Dieser Parameter kann null oder mindestens einer der folgenden Werte sein. Wenn dieser Parameter null ist, lädt die Funktion die Module und die Symbole für das Modul.

Wert	Bedeutung
SLMFLAG_NO_SYMBOLS 0x4	Lädt das Modul, aber nicht die Symbole für das Modul.
SLMFLAG_VIRTUAL 0x1	Erstellt ein virtuelles Modul namens ModuleName an der Adresse, die in BaseOfDll-angegeben ist. Rufen Sie zum Hinzufügen von Symbolen zu diesem Modul die SymAddSymbol--Funktion auf.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert die Basisadresse des geladenen Moduls.

Wenn die Funktion fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen abzurufen.

Wenn das Modul bereits geladen ist, ist der Rückgabewert null und GetLastError- gibt ERROR_SUCCESS zurück.

Bemerkungen

Der Symbolhandler erstellt einen Eintrag für das Modul, und wenn die Option zum Laden von verzögerten Symbolen deaktiviert ist, wird versucht, die Symbole zu laden. Wenn das Laden von verzögerten Symbolen aktiviert ist, wird das Modul als verzögert markiert, und die Symbole werden erst geladen, wenn ein Verweis auf ein Symbol im Modul erfolgt. Daher sollten Sie die SymGetModuleInfo64--Funktion immer aufrufen, nachdem Sie SymLoadModuleExaufgerufen haben.

Verwenden Sie zum Entladen der Symboltabelle die SymUnloadModule64--Funktion.

Alle DbgHelp-Funktionen, z. B. diese, sind single threaded. Daher führen Aufrufe von mehr als einem Thread zu dieser Funktion wahrscheinlich zu unerwartetem Verhalten oder Speicherbeschädigung. Um dies zu vermeiden, müssen Sie alle gleichzeitigen Aufrufe von mehr als einem Thread mit dieser Funktion synchronisieren.

Um die Unicode-Version dieser Funktion aufzurufen, definieren Sie DBGHELP_TRANSLATE_TCHAR.

Beispiele

Ein Beispiel finden Sie unter Laden eines Symbolmoduls.

Anmerkung

Der dbghelp.h-Header definiert SymLoadModuleEx als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.