SymFindFileInPathW-Funktion (dbghelp.h)

Artikel
11/20/2024

Sucht eine Symboldatei oder ein ausführbares Bild.

Syntax

BOOL IMAGEAPI SymFindFileInPathW(
  [in]           HANDLE                   hprocess,
  [in, optional] PCWSTR                   SearchPath,
  [in]           PCWSTR                   FileName,
  [in, optional] PVOID                    id,
  [in]           DWORD                    two,
  [in]           DWORD                    three,
  [in]           DWORD                    flags,
  [out]          PWSTR                    FoundFile,
  [in, optional] PFINDFILEINPATHCALLBACKW callback,
  [in, optional] PVOID                    context
);

Parameter

[in] hprocess

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

[in, optional] SearchPath

Der Suchpfad. Dies kann mehrere Pfade sein, die durch Semikolons getrennt werden. Sie kann sowohl Verzeichnisse als auch Symbolserver enthalten. Wenn dieser Parameter NULL-ist, verwendet die Funktion den Suchpfad, der mithilfe der SymSetSearchPath oder SymInitialize Funktion festgelegt wurde.

[in] FileName

Der Name der Datei. Sie können einen Pfad angeben; Allerdings wird nur der Dateiname verwendet.

[in, optional] id

Die ersten von drei identifizierenden Parametern (siehe Hinweise).

[in] two

Die zweite von drei identifizierenden Parametern (siehe Hinweise).

[in] three

Das dritte von drei identifizierenden Parametern (siehe Hinweise).

[in] flags

Das Format der id Parameter. Dieser Parameter kann einer der folgenden Werte sein:

Wert	Bedeutung
SSRVOPT_DWORD 0x0002	Der parameter id ist ein DWORD-.
SSRVOPT_DWORDPTR 0x0004	Die ID Parameter ist ein Zeiger auf ein DWORD-.
SSRVOPT_GUIDPTR 0x0008	Die ID Parameter ist ein Zeiger auf eine GUID-.

[out] FoundFile

Ein Zeiger auf einen Puffer, der den vollqualifizierten Pfad zur Symboldatei empfängt. Dieser Puffer muss mindestens MAX_PATH Zeichen sein.

[in, optional] callback

Eine SymFindFileInPathProc Rückruffunktion.

[in, optional] context

Ein benutzerdefinierter Wert oder NULL-. Dieser Wert wird einfach an die Rückruffunktion übergeben. Dieser Parameter wird in der Regel von einer Anwendung verwendet, um einen Zeiger an eine Datenstruktur zu übergeben, die einen Kontext für die Rückruffunktion bereitstellt.

Rückgabewert

Wenn der Server eine gültige Symboldatei findet, wird TRUE-zurückgegeben; andernfalls wird FALSE zurückgegeben, und GetLastError gibt einen Wert zurück, der angibt, warum die Symboldatei nicht zurückgegeben wurde.

Bemerkungen

Die identifizierenden Parameter werden wie folgt ausgefüllt:

Wenn DbgHelp nach einer PDB-Datei sucht, gibt die -ID Parameter die PDB-Signatur an, wie sie im Codeview-Debugverzeichnis des ursprünglichen Bilds zu finden ist. Der Parameter zwei gibt das PDB-Alter an. Der Parameter drei wird nicht verwendet und auf Null festgelegt.
Wenn DbgHelp nach einem anderen Bildtyp sucht, z. B. eine ausführbare Datei oder DBG-Datei, gibt der parameter id den TimeDateStamp des ursprünglichen Bilds an, wie in seinem PE-Header zu finden. Parameter zwei gibt das SizeOfImage-Feld an, das auch aus dem PE-Header extrahiert wird. Der Parameter drei wird nicht verwendet und auf Null festgelegt.

Alle diese Werte können durch Aufrufen SymSrvGetFileIndexInfoabgerufen werden.

Beim Durchsuchen eines Verzeichnisses überprüft diese Funktion nicht, ob die Symbolbezeichner standardmäßig übereinstimmen. Um sicherzustellen, dass sich die übereinstimmenden Symboldateien befinden, rufen Sie die SymSetOptions--Funktion mit SYMOPT_EXACT_SYMBOLS auf.

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.

Anmerkung

Der dbghelp.h-Header definiert SymFindFileInPath 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.