IDebugAdvanced3::FindSourceFileAndToken-Methode (dbgeng.h)

Artikel
08/07/2023

Die FindSourceFileAndToken-Methode gibt den Dateinamen einer Quelldatei im Quellpfad zurück oder gibt den Wert einer Variablen zurück, die einem Dateitoken zugeordnet ist.

Syntax

HRESULT FindSourceFileAndToken(
  [in]            ULONG   StartElement,
  [in]            ULONG64 ModAddr,
  [in]            PCSTR   File,
  [in]            ULONG   Flags,
  [in, optional]  PVOID   FileToken,
  [in]            ULONG   FileTokenSize,
  [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, von dem aus die Suche gestartet werden soll. Alle Elemente im Quellpfad vor StartElement werden von der Suche ausgeschlossen. Der Index des ersten Elements ist 0. 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.

StartElement wird ignoriert, wenn das Flag DEBUG_FIND_SOURCE_TOKEN_LOOKUP in Flags festgelegt ist.

[in] ModAddr

Gibt einen Speicherort innerhalb der Speicherzuordnung des Moduls in dem Ziel an, mit dem die Quelldatei verknüpft ist. ModAddr wird zum Zwischenspeichern der Suchergebnisse und beim Abfragen von Quellservern nach der Datei verwendet. ModAddr kann NULL sein.

ModAddr wird ignoriert, wenn das Flag DEBUG_FIND_SOURCE_TOKEN_LOOKUP in Flags festgelegt ist. Und es wird nicht zum Abfragen von Quellservern verwendet, wenn FileToken nicht NULL ist.

[in] File

Gibt den Pfad und Den Dateinamen der zu durchsuchenden Datei an.

Wenn das Flag DEBUG_FIND_SOURCE_TOKEN_LOOKUP festgelegt ist, wird die Datei bereits durch das Token in FileToken angegeben. In diesem Fall gibt File den Namen einer Variablen auf dem Quellserver an, der sich auf die Datei bezieht. Die Variable muss mit dem Prozentzeichen ( % ) beginnen und enden, z. B. %SRCSRVCMD%. Der Wert dieser Variablen wird zurückgegeben.

[in] Flags

Gibt die Flags an, die das Verhalten dieser Methode steuern. Eine Beschreibung dieser Flags finden Sie unter Hinweise.

[in, optional] FileToken

Gibt ein Dateitoken an, das eine Datei auf einem Quellserver darstellt. Ein Dateitoken kann abgerufen werden, indem Sie in der Methode GetSourceFileInformation die Einstellung Für DEBUG_SRCFILE_SYMBOL_TOKEN festlegen.

Wenn das Flag DEBUG_FIND_SOURCE_TOKEN_LOOKUP festgelegt ist, darf FileToken nicht NULL sein.

[in] FileTokenSize

Gibt die Größe des FileToken-Tokens in Bytes an. Wenn FileTokenNULL ist, wird dieser Parameter ignoriert.

[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), wird -1 an FoundElement zurückgegeben. Wenn FoundElementNULL ist oder Flags DEBUG_SRCFILE_SYMBOL_TOKEN enthalten, werden diese Informationen nicht zurückgegeben.

[out, optional] Buffer

Empfängt den Namen der gefundenen Datei. Wenn sich die Datei nicht auf einem Quellserver befindet, ist dies der Name der Datei im lokalen Quellcache. Wenn das Flag DEBUG_FIND_SOURCE_FULL_PATH festgelegt ist, ist dies der vollständige kanonische Pfadname für die Datei. Andernfalls ist es die Verkettung des Verzeichnisses im Quellpfad mit dem Ende der Datei , die zum Suchen der Datei verwendet wurde.

Wenn das Flag DEBUG_SRCFILE_SYMBOL_TOKEN in Flags festgelegt ist, empfängtBuffer den Wert der Variablen mit dem Namen FileToken , die dem Dateitoken FileToken zugeordnet ist.

Wenn PufferNULL ist, werden diese Informationen nicht zurückgegeben.

[in] BufferSize

Gibt die Größe des Pufferpuffers in Zeichen an. Diese Größe enthält den Platz für das "\0"-Endzeichen. Wenn BufferNULL ist, wird dieser Parameter ignoriert.

[out, optional] FoundSize

Gibt die Größe des Dateinamens in Zeichen an. Diese Größe enthält den Platz für das "\0"-Endzeichen. 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.
S_FALSE	Die Methode war erfolgreich. Der Pufferpuffer war jedoch zu klein, um den Dateinamen oder Variablenwert aufzunehmen, sodass die Zeichenfolge abgeschnitten wurde, um in den Puffer zu passen.

Hinweise

Wenn das Flag DEBUG_SRCFILE_SYMBOL_TOKEN in Flags festgelegt ist, sucht diese Methode nicht nach einer Datei im Quellpfad. Stattdessen sucht es eine Variable, die dem in FileToken bereitgestellten Dateitoken zugeordnet ist. Diese Variablen sind im Thema Sprachspezifikation 1 dokumentiert. Wenn Sie beispielsweise den Wert der Variablen SRCSRVCMD abrufen möchten , um die Quelldatei aus der Quellcodeverwaltung zu extrahieren (auch von der DEBUG_SRCFILE_SYMBOL_TOKEN_SOURCE_COMMAND_WIDE-Funktion getSourceFileInformation zurückgegeben), legen Sie File auf %SRCSRVCMD% fest.

Die Engine verwendet die folgenden Schritte– in der Reihenfolge –, um nach der Datei zu suchen:

Wenn der Quellpfad Quellserver enthält und das Flag DEBUG_FIND_SOURCE_NO_SRCSRV nicht festgelegt ist, wird zuerst der Quellserver im Quellpfad durchsucht.
Die erste gefundene Übereinstimmung wird zurückgegeben.
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 das Verzeichnis C:\a\b\c\d und Die Datei c\d\e\foo.c enthält, ist die Datei C:\a\b\c\d\e\foo.c eine Übereinstimmung.
Wenn das Flag 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 Prozess wiederholt und jedes Mal, wenn das erste Verzeichnis vom Anfang des Dateipfads entfernt wird. Wenn der Quellpfad beispielsweise das Verzeichnis C:\a\b und Die Datei c\d\e\foo.c enthält, ist die Datei C:\a\b\e\foo.c eine Übereinstimmung.
Die erste gefundene Übereinstimmung wird zurückgegeben.
Die Dateidatei wird direkt im Ablagesystem gesucht.

Weitere Informationen zu Quelldateien finden Sie unter Verwenden von Quelldateien. Eine Übersicht über den Quellpfad und seine Syntax finden Sie unter Quellpfad.

Die DEBUG_FIND_SOURCE_XXX-Bitflags werden verwendet, um das Verhalten der Methoden FindSourceFile und FindSourceFileAndToken bei der Suche nach Quelldateien zu steuern.

Die Flags können eine beliebige Kombination von Werten aus der folgenden Tabelle sein.

Dauerhaft	BESCHREIBUNG
DEBUG_FIND_SOURCE_FULL_PATH	Geben Sie immer den vollständigen kanonischen Pfadnamen für die gefundene Datei zurück. Wenn nicht festgelegt ist und der Quellpfad relative Verzeichnisse enthält, können relative Pfadnamen zurückgegeben werden.
DEBUG_FIND_SOURCE_BEST_MATCH	Suchen Sie weiter, nachdem eine Übereinstimmung gefunden wurde, um nach einer besseren Übereinstimmung zu suchen.
DEBUG_FIND_SOURCE_NO_SRCSRV	Schließen Sie keine Quellserver in die Suche ein.
DEBUG_FIND_SOURCE_TOKEN_LOOKUP	Gibt eine Variable zurück, die einem Dateitoken zugeordnet ist. Wenn dieses Flag festgelegt ist, werden die anderen Flags ignoriert. Dieses Flag kann nicht in der FindSourceFile-Methode verwendet werden.