SymFindFileInPath-Funktion (dbghelp.h)

Artikel
02/26/2024

Sucht eine Symboldatei oder ein ausführbares Image.

Syntax

BOOL IMAGEAPI SymFindFileInPath(
  [in]           HANDLE                  hprocess,
  [in, optional] PCSTR                   SearchPath,
  [in]           PCSTR                   FileName,
  [in, optional] PVOID                   id,
  [in]           DWORD                   two,
  [in]           DWORD                   three,
  [in]           DWORD                   flags,
  [out]          PSTR                    FoundFile,
  [in, optional] PFINDFILEINPATHCALLBACK callback,
  [in, optional] PVOID                   context
);

Parameter

[in] hprocess

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

[in, optional] SearchPath

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

[in] FileName

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

[in, optional] id

Der erste von drei identifizierenden Parametern (siehe Hinweise).

[in] two

Der zweite von drei identifizierenden Parametern (siehe Hinweise).

[in] three

Der dritte von drei identifizierenden Parametern (siehe Hinweise).

[in] flags

Das Format des id-Parameters . Dieser Parameter kann einen der folgenden Werte annehmen.

Wert	Bedeutung
SSRVOPT_DWORD 0x0002	Der ID-Parameter ist ein DWORD.The id parameter is a DWORD.
SSRVOPT_DWORDPTR 0x0004	Der id-Parameter ist ein Zeiger auf ein DWORD.
SSRVOPT_GUIDPTR 0x0008	Der 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 enthalten.

[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 nach einer gültigen Symboldatei sucht, gibt er TRUE zurück. Andernfalls wird FALSE zurückgegeben, und GetLastError gibt einen Wert zurück, der angibt, warum die Symboldatei nicht zurückgegeben wurde.

Hinweise

Die identifizierenden Parameter werden wie folgt ausgefüllt:

Wenn DbgHelp nach einer PDB-Datei sucht, gibt der Id-Parameter die PDB-Signatur an, die im Codeview-Debugverzeichnis des ursprünglichen Images gefunden wird. Parameter 2 gibt das PDB-Alter an. Parameter 3 ist nicht verwendet und auf 0 festgelegt.
Wenn DbgHelp nach einem anderen Imagetyp sucht, z. B. nach einer ausführbaren Datei oder einer DBG-Datei, gibt der Id-Parameter den TimeDateStamp des ursprünglichen Bilds an, wie er im PE-Header gefunden wird. Parameter 2 gibt das Feld SizeOfImage an, das ebenfalls aus dem PE-Header extrahiert wird. Parameter 3 ist nicht verwendet und auf 0 festgelegt.

Alle diese Werte können durch Aufrufen von SymSrvGetFileIndexInfo abgerufen 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 an diese Funktion gerichtete Aufrufe mehrerer Threads wahrscheinlich zu unerwartetem Verhalten oder einer Beschädigung des Speichers. Um dies zu vermeiden, müssen Sie alle an diese Funktion gerichteten gleichzeitigen Aufrufe mehrerer Threads synchronisieren.

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