IDebugSymbols：：FindSourceFile 方法 (dbgeng.h)

项目
02/23/2024

FindSourceFile 方法在源路径中搜索指定的源文件。

语法

HRESULT FindSourceFile(
  [in]            ULONG  StartElement,
  [in]            PCSTR  File,
  [in]            ULONG  Flags,
  [out, optional] PULONG FoundElement,
  [out, optional] PSTR   Buffer,
  [in]            ULONG  BufferSize,
  [out, optional] PULONG FoundSize
);

参数

[in] StartElement

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

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

[in] File

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

[in] Flags

指定搜索标志。有关这些标志的说明，请参阅 DEBUG_FIND_SOURCE_XXX。

不应设置DEBUG_FIND_SOURCE_TOKEN_LOOKUP标志。将忽略DEBUG_FIND_SOURCE_NO_SRCSRV标志，因为此方法不包括搜索中的源服务器。

[out, optional] FoundElement

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

[out, optional] Buffer

接收找到的文件的路径和名称。如果设置了标志DEBUG_FIND_SOURCE_FULL_PATH，则这是文件的完整规范路径名称。否则，它是源路径中目录与用于查找文件的 File 尾部的串联。如果 Buffer 为 NULL，则不返回此信息。

[in] BufferSize

指定 缓冲区 的大小（以字符为单位）。

[out, optional] FoundSize

指定文件名称的大小（以字符为单位）。如果 FoundSize 为 NULL，则不返回此信息。

返回值

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

返回代码	说明
S_OK	方法成功。
E_NOINTERFACE	在源路径上找不到文件。

注解

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

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