IDebugSymbols::FindSourceFile 方法 (dbgeng.h)

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。 如果 FoundElementNULL,则不返回此信息。

[out, optional] Buffer

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

[in] BufferSize

指定 缓冲区 的大小(以字符为单位)。

[out, optional] FoundSize

指定文件名称的大小(以字符为单位)。 如果 FoundSizeNULL,则不返回此信息。

返回值

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

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

注解

引擎使用以下步骤(按顺序)搜索文件:

  1. 对于源路径中的每个目录,尝试查找目录路径末尾和文件路径开头之间的重叠。 例如,如果源路径包含目录 C:\a\b\c\d, 而 File 为 c\d\e\samplefile.c,则文件 C:\a\b\c\d\e\samplefile.c 是匹配项。

    如果设置了标志DEBUG_FIND_SOURCE_BEST_MATCH,则返回重叠时间最长的匹配项;否则,将返回第一个匹配项。

  2. 对于源路径中的每个目录, 文件 将追加到目录中。 如果未找到匹配项,则重复此过程,每次从文件路径的开头删除第一个目录时。 例如,如果源路径包含目录 C:\a\b,而 File 为 c\d\e\samplefile.c,则文件 C:\a\b\e\samplefile.c 为匹配项。

    返回找到的第一个匹配项。

  3. 文件 直接在归档系统上查找。
注意 将忽略源路径中的任何源服务器。 若要在搜索中包含源服务器,请将 FindSourceFileAndTokenModAddr 中指定的模块地址一起使用。
 
有关使用源路径的详细信息,请参阅 使用源文件。 有关源路径及其语法的概述,请参阅 源路径

要求

要求
目标平台 桌面
标头 dbgeng.h (包括 Dbgeng.h)

另请参阅

DEBUG_FIND_SOURCE_XXX

FindSourceFileAndToken

GetSourceFileLineOffsets

GetSourcePathElement

IDebugSymbols

IDebugSymbols2

IDebugSymbols3