IDebugAdvanced3：：FindSourceFileAndToken 方法 (dbgeng.h)

项目
08/07/2023

FindSourceFileAndToken 方法在源路径上返回源文件的文件名，或返回与文件令牌关联的变量的值。

语法

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
);

参数

[in] StartElement

指定源路径中要从其开始搜索的元素的索引。 StartElement 之前源路径中的所有元素都会从搜索中排除。第一个元素的索引为零。如果 StartElement 大于或等于源路径中的元素数，则直接检查归档系统。

此参数可与 FoundElement 一起使用，以检查源路径中的多个匹配项。

如果在 Flags 中设置了DEBUG_FIND_SOURCE_TOKEN_LOOKUP标志，则忽略 StartElement。

[in] ModAddr

指定与源文件相关的目标中模块的内存分配中的位置。 ModAddr 用于缓存搜索结果以及查询文件的源服务器时。 ModAddr 可以为 NULL。

如果在 Flags 中设置了DEBUG_FIND_SOURCE_TOKEN_LOOKUP标志，则忽略 ModAddr。如果 FileToken 不为 NULL，则它不用于查询源服务器。

[in] File

指定要搜索的文件的路径和文件名。

如果设置了标志DEBUG_FIND_SOURCE_TOKEN_LOOKUP，则文件已由 FileToken 中的令牌指定。在这种情况下， File 指定源服务器上与文件相关的变量的名称。变量必须以百分号开头和结尾，% ( ) ，例如 %SRCSRVCMD%。 返回此变量的值。

[in] Flags

指定控制此方法行为的标志。有关这些标志的说明，请参阅备注。

[in, optional] FileToken

指定表示源服务器上的文件的文件标记。可以通过在 GetSourceFileInformation 方法中设置“要DEBUG_SRCFILE_SYMBOL_TOKEN”来获取文件令牌。

如果设置了标志DEBUG_FIND_SOURCE_TOKEN_LOOKUP， 则 FileToken 不得为 NULL。

[in] FileTokenSize

指定 FileToken 标记的大小（以字节为单位）。如果 FileToken 为 NULL，则忽略此参数。

[out, optional] FoundElement

接收包含文件的源路径中元素的索引。如果文件直接在归档系统上找到， (不使用源路径) ，则 -1 将返回到 FoundElement。如果 FoundElement 为 NULL 或 Flags 包含DEBUG_SRCFILE_SYMBOL_TOKEN，则不会返回此信息。

[out, optional] Buffer

接收找到的文件的名称。如果文件不在源服务器上，则这是本地源缓存中文件的名称。如果设置了标志DEBUG_FIND_SOURCE_FULL_PATH，则这是文件的完整规范路径名称。否则，它是源路径中目录与用于查找文件的 File 尾部的串联。

如果在 Flags 中设置了DEBUG_SRCFILE_SYMBOL_TOKEN标志，则 Buffer 将接收与文件令牌 FileToken 关联的名为 File 的变量的值。

如果 Buffer 为 NULL，则不返回此信息。

[in] BufferSize

指定 缓冲区 的大小（以字符为单位）。此大小包括“\0”终止字符的空间。如果 Buffer 为 NULL，则忽略此参数。

[out, optional] FoundSize

指定文件名称的大小（以字符为单位）。此大小包括“\0”终止字符的空间。如果 foundSize 为 NULL，则不返回此信息。

返回值

此方法也可能返回错误值。有关更多详细信息，请参阅返回值。

返回代码	说明
S_OK	方法成功。
S_FALSE	方法成功。但是，缓冲区缓冲区太小，无法容纳文件名或变量值，因此字符串被截断以适合缓冲区。

注解

在 Flags 中设置标志DEBUG_SRCFILE_SYMBOL_TOKEN时，此方法不会搜索源路径上的文件。相反，它会查找与 FileToken 中提供的文件令牌关联的变量。语言规范 1 主题中记录了这些变量。例如，若要检索变量 SRCSRVCMD 的值（用于从源代码管理中提取源文件的命令 (GetSourceFileInformation) 的 DEBUG_SRCFILE_SYMBOL_TOKEN_SOURCE_COMMAND_WIDE 函数也返回），请将 File 设置为 %SRCSRVCMD%。

引擎使用以下步骤（按顺序）搜索文件：

如果源路径包含任何源服务器，并且未设置DEBUG_FIND_SOURCE_NO_SRCSRV标志，则首先搜索源路径中的源服务器。
返回找到的第一个匹配项。
对于源路径中的每个目录，尝试查找目录路径末尾和文件路径开头之间的重叠。例如，如果源路径包含目录 C：\a\b\c\d， 而 File 为 c\d\e\foo.c，则文件 C：\a\b\c\d\e\foo.c 是匹配项。
如果设置了标志DEBUG_FIND_SOURCE_BEST_MATCH，则返回重叠时间最长的匹配项;否则，将返回第一个匹配项。
对于源路径中的每个目录，文件将追加到目录中。如果未找到匹配项，则重复此过程，每次从文件路径的开头删除第一个目录时。例如，如果源路径包含目录 C：\a\b，而 File 为 c\d\e\foo.c，则文件 C：\a\b\e\foo.c 为匹配项。
返回找到的第一个匹配项。
文件文件直接在归档系统上查找。

有关源文件的详细信息，请参阅使用源文件。有关源路径及其语法的概述，请参阅源路径。

DEBUG_FIND_SOURCE_XXX 位标志用于控制搜索源文件时 FindSourceFile 和 FindSourceFileAndToken 方法的行为。

标志可以是下表中值的任意组合。

一直	说明
DEBUG_FIND_SOURCE_FULL_PATH	始终返回找到的文件的完整规范路径名称。如果未设置，并且源路径包含相对目录，则可以返回相对路径名称。
DEBUG_FIND_SOURCE_BEST_MATCH	找到匹配项后继续搜索，以查找更好的匹配项。
DEBUG_FIND_SOURCE_NO_SRCSRV	不要在搜索中包含源服务器。
DEBUG_FIND_SOURCE_TOKEN_LOOKUP	返回与文件令牌关联的变量。如果设置了此标志，则忽略其他标志。此标志不能在 FindSourceFile 方法中使用。