IDebugAdvanced3：：FindSourceFileAndToken 方法（dbgeng.h）

2025-04-09

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 中的令牌指定。在这种情况下，文件指定与该文件相关的源服务器上的变量的名称。变量必须以百分号（ % 例如 %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 或标志包含DEBUG_SRCFILE_SYMBOL_TOKEN，则不会返回此信息。

[out, optional] Buffer

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

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

如果 缓冲区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 函数返回）--set 文件%SRCSRVCMD%。

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

如果源路径包含任何源服务器，并且未设置标志DEBUG_FIND_SOURCE_NO_SRCSRV，则首先搜索源路径中的源服务器。
返回找到的第一个匹配项。
对于源路径中的每个目录，将尝试查找目录路径末尾与文件路径开头之间的重叠。例如，如果源路径包含目录 C：\a\b\c\d，文件为 c\d\e\foo.c，则文件 C：\a\b\c\d\e\foo.c 是匹配项。
如果设置了标志DEBUG_FIND_SOURCE_BEST_MATCH，则返回与最长重叠的匹配项;否则，将返回第一个匹配项。
对于源路径中的每个目录，文件追加到目录中。如果未找到匹配项，此过程将重复，每次从文件路径的开头删除第一个目录。例如，如果源路径包含目录 C：\a\b， 而文件 为 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 方法中使用。