IDebugSymbols3::FindSourceFile-Methode (dbgeng.h)

Artikel
02/06/2025

Die FindSourceFile Methode durchsucht den Quellpfad nach einer angegebenen Quelldatei.

Syntax

HRESULT FindSourceFile(
  [in]            ULONG  StartElement,
  [in]            PCSTR  File,
  [in]            ULONG  Flags,
  [out, optional] PULONG FoundElement,
  [out, optional] PSTR   Buffer,
  [in]            ULONG  BufferSize,
  [out, optional] PULONG FoundSize
);

Parameter

[in] StartElement

Gibt den Index eines Elements innerhalb des Quellpfads an, aus dem die Suche gestartet werden soll. Alle Elemente im Quellpfad vor StartElement- werden von der Suche ausgeschlossen. Der Index des ersten Elements ist Null. Wenn StartElement- größer oder gleich der Anzahl der Elemente im Quellpfad ist, wird das Ablagesystem direkt überprüft.

Dieser Parameter kann mit FoundElement- verwendet werden, um im Quellpfad nach mehreren Übereinstimmungen zu suchen.

[in] File

Gibt den Pfad und Dateinamen der zu suchden Datei an.

[in] Flags

Gibt die Suchkennzeichnungen an. Eine Beschreibung dieser Flags finden Sie unter DEBUG_FIND_SOURCE_XXX.

Die Kennzeichnung DEBUG_FIND_SOURCE_TOKEN_LOOKUP sollte nicht festgelegt werden. Das Flag DEBUG_FIND_SOURCE_NO_SRCSRV wird ignoriert, da diese Methode keine Quellserver in die Suche einschließt.

[out, optional] FoundElement

Empfängt den Index des Elements innerhalb des Quellpfads, der die Datei enthält. Wenn die Datei direkt im Ablagesystem gefunden wurde (ohne den Quellpfad zu verwenden), wird -1 an FoundElement-zurückgegeben. Wenn FoundElement-NULL-ist, werden diese Informationen nicht zurückgegeben.

[out, optional] Buffer

Empfängt den Pfad und den Namen der gefundenen Datei. Wenn das Flag DEBUG_FIND_SOURCE_FULL_PATH festgelegt ist, ist dies der vollständige kanonische Pfadname für die Datei. Andernfalls handelt es sich um die Verkettung des Verzeichnisses im Quellpfad mit dem Tail von File, die zum Suchen der Datei verwendet wurde. Wenn Puffer-NULL-ist, werden diese Informationen nicht zurückgegeben.

[in] BufferSize

Gibt die Größe des Puffer- Puffers in Zeichen an.

[out, optional] FoundSize

Gibt die Größe der Datei in Zeichen an. Wenn FoundSizeNULL-ist, werden diese Informationen nicht zurückgegeben.

Rückgabewert

Diese Methode kann auch Fehlerwerte zurückgeben. Weitere Informationen finden Sie unter Rückgabewerte.

Rückgabecode	Beschreibung
S_OK	Die Methode war erfolgreich.
E_NOINTERFACE	Datei- wurde im Quellpfad nicht gefunden.

Bemerkungen

Das Modul verwendet die folgenden Schritte - in der Reihenfolge -, um nach der Datei zu suchen:

Für jedes Verzeichnis im Quellpfad wird versucht, eine Überlappung zwischen dem Ende des Verzeichnispfads und dem Anfang des Dateipfads zu finden. Wenn der Quellpfad beispielsweise ein Verzeichnis C:\a\b\c\d und Datei- "c\d\e\samplefile.c" enthält, ist die Datei "C:\a\b\c\d\e\samplefile.c" eine Übereinstimmung.
Wenn die Kennzeichnung DEBUG_FIND_SOURCE_BEST_MATCH festgelegt ist, wird die Übereinstimmung mit der längsten Überlappung zurückgegeben. andernfalls wird die erste Übereinstimmung zurückgegeben.
Für jedes Verzeichnis im Quellpfad wird Datei- an das Verzeichnis angefügt. Wenn keine Übereinstimmung gefunden wird, wird dieser Vorgang wiederholt, und jedes Mal, wenn das erste Verzeichnis vom Anfang des Dateipfads entfernt wird. Wenn der Quellpfad beispielsweise ein Verzeichnis "C:\a\b" enthält und Datei "c\d\e\samplefile.c" lautet, ist die Datei "C:\a\b\e\samplefile.c" eine Übereinstimmung.
Die erste gefundene Übereinstimmung wird zurückgegeben.
Datei- wird direkt im Ablagesystem nachschlagen.

Hinweis Alle Quellserver im Quellpfad werden ignoriert. Um die Quellserver in die Suche einzuschließen, verwenden Sie FindSourceFileAndToken mit einer Moduladresse, die in ModAddr-angegeben ist.

Weitere Informationen zur Verwendung des Quellpfads finden Sie unter Verwenden von Quelldateien. Eine Übersicht über den Quellpfad und dessen Syntax finden Sie unter Quellpfad.