IDebugAdvanced3::FindSourceFileAndTokenWide-Methode (dbgeng.h)

Artikel
02/06/2025

Die FindSourceFileAndTokenWide 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 FindSourceFileAndTokenWide(
  [in]            ULONG   StartElement,
  [in]            ULONG64 ModAddr,
  [in]            PCWSTR  File,
  [in]            ULONG   Flags,
  [in, optional]  PVOID   FileToken,
  [in]            ULONG   FileTokenSize,
  [out, optional] PULONG  FoundElement,
  [out, optional] PWSTR   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.

StartElement- wird ignoriert, wenn das Kennzeichen DEBUG_FIND_SOURCE_TOKEN_LOOKUP in Flagsfestgelegt ist.

[in] ModAddr

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

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

[in] File

Gibt den Pfad und Dateinamen der zu suchden Datei an.

Wenn das Flag DEBUG_FIND_SOURCE_TOKEN_LOOKUP festgelegt ist, wird die Datei bereits durch das Token in FileTokenangegeben. In diesem Fall gibt File den Namen einer Variablen auf dem Quellserver im Zusammenhang mit der Datei an. 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 DEBUG_FIND_SOURCE_XXX.

[in, optional] FileToken

Gibt ein Dateitoken an, das eine Datei auf einem Quellserver darstellt. Ein Dateitoken kann durch Festlegen von Which DEBUG_SRCFILE_SYMBOL_TOKEN in der Methode GetSourceFileInformationabgerufen werden.

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

[in] FileTokenSize

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

[out, optional] FoundElement

Empfängt den Index des Elements innerhalb des Quellpfads, der die Datei enthielt. Wenn die Datei direkt im Ablagesystem gefunden wurde (ohne den Quellpfad zu verwenden), wird -1 an FoundElementzurückgegeben. Wenn FoundElement-NULL- 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 handelt es sich um die Verkettung des Verzeichnisses im Quellpfad mit dem Tail von File, die zum Suchen der Datei verwendet wurde.

Wenn das Flag DEBUG_SRCFILE_SYMBOL_TOKEN in Flagsfestgelegt ist, empfängt Buffer den Wert der Variablen namens File zugeordnet FileToken.

Wenn Puffer-NULL-ist, werden diese Informationen nicht zurückgegeben.

[in] BufferSize

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

[out, optional] FoundSize

Gibt die Größe in Zeichen des Namens der Datei an. Diese Größe enthält den Abstand für das Endzeichen '\0'. 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 Puffer Puffer war jedoch zu klein, um den Dateinamen oder Variablenwert zu halten, sodass die Zeichenfolge abgeschnitten wurde, damit sie in den Puffer passt.

Bemerkungen

Wenn das Flag DEBUG_SRCFILE_SYMBOL_TOKEN in Flagsfestgelegt wird, sucht diese Methode nicht nach einer Datei im Quellpfad. Stattdessen wird eine Variable nachgeschlagen, die dem in FileTokenbereitgestellten Dateitoken zugeordnet ist. Diese Variablen sind im Thema Sprachspezifikation 1dokumentiert. Um beispielsweise den Wert der Variablen SRCSRVCMD abzurufen, um die Quelldatei aus der Quellcodeverwaltung zu extrahieren (wird auch von der DEBUG_SRCFILE_SYMBOL_TOKEN_SOURCE_COMMAND_WIDE Funktion von GetSourceFileInformation)-set File auf %SRCSRVCMD%zurückgegeben.

Das Modul 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 der Quellserver im Quellpfad zuerst 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 ein Verzeichnis C:\a\b\c\d und Datei "c\d\e\foo.c" enthält, ist die Datei "C:\a\b\c\d\e\foo.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 und Datei c\d\e\foo.c ist, ist die Datei C:\a\b\e\foo.c eine Übereinstimmung.
Die erste gefundene Übereinstimmung wird zurückgegeben.
Die Datei Datei wird direkt im Ablagesystem nachschlagen.

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