IDebugAdvanced2：：FindSourceFileAndToken 方法 (dbgeng.h)

项目
02/23/2024

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标志，则这是文件的完整规范路径名称。否则，源路径中的目录与用于查找文件的结尾连接。

如果在 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 方法中使用。