SymFindFileInPathW 函数 (dbghelp.h)

项目
02/29/2024

查找符号文件或可执行映像。

语法

BOOL IMAGEAPI SymFindFileInPathW(
  [in]           HANDLE                   hprocess,
  [in, optional] PCWSTR                   SearchPath,
  [in]           PCWSTR                   FileName,
  [in, optional] PVOID                    id,
  [in]           DWORD                    two,
  [in]           DWORD                    three,
  [in]           DWORD                    flags,
  [out]          PWSTR                    FoundFile,
  [in, optional] PFINDFILEINPATHCALLBACKW callback,
  [in, optional] PVOID                    context
);

参数

[in] hprocess

最初传递给 SymInitialize 函数的进程句柄。

[in, optional] SearchPath

搜索路径。这可以是用分号分隔的多个路径。它可以包括目录和符号服务器。如果此参数为 NULL，则该函数使用使用 SymSetSearchPath 或 SymInitialize 函数设置的搜索路径。

[in] FileName

文件的名称。可以指定路径;但是，仅使用文件名。

[in, optional] id

三个标识参数中的第一个 (请参阅备注) 。

[in] two

三个标识参数中的第二个 (请参阅备注) 。

[in] three

三个标识参数中的第三个 (请参阅备注) 。

[in] flags

id 参数的格式。此参数的取值可为下列值之一：

值	含义
SSRVOPT_DWORD 0x0002	id 参数为 DWORD。
SSRVOPT_DWORDPTR 0x0004	id 参数是指向 DWORD 的指针。
SSRVOPT_GUIDPTR 0x0008	id 参数是指向 GUID 的指针。

[out] FoundFile

指向接收符号文件的完全限定路径的缓冲区的指针。此缓冲区必须至少MAX_PATH个字符。

[in, optional] callback

SymFindFileInPathProc 回调函数。

[in, optional] context

用户定义的值或 NULL。此值只是传递给回调函数。此参数通常由应用程序用来传递指向数据结构的指针，该数据结构为回调函数提供一些上下文。

返回值

如果服务器找到有效的符号文件，则返回 TRUE;否则，它将返回 FALSE，GetLastError 返回一个值，该值指示不返回符号文件的原因。

注解

标识参数的填充方式如下：

如果 DbgHelp 正在查找 .pdb 文件， 则 id 参数指定在原始映像的 codeview 调试目录中找到的 PDB 签名。参数 2 指定 PDB 期限。参数 3 未使用，并且设置为零。
如果 DbgHelp 正在查找任何其他类型的映像，例如可执行文件或 .dbg 文件，则 id 参数将指定在其 PE 标头中找到的原始映像的 TimeDateStamp。参数 2 指定 SizeOfImage 字段，也从 PE 标头中提取。参数 3 未使用，并且设置为零。

所有这些值都可以通过调用 SymSrvGetFileIndexInfo 来获取。

搜索目录时，此函数不会默认验证符号标识符是否匹配。若要确保找到匹配的符号文件，请使用 SYMOPT_EXACT_SYMBOLS调用 SymSetOptions 函数。

所有 DbgHelp 函数（例如此函数）都是单线程的。因此，从多个线程调用此函数可能会导致意外行为或内存损坏。若要避免这种情况，必须将多个线程中的所有并发调用同步到此函数。

若要调用此函数的 Unicode 版本，请定义 DBGHELP_TRANSLATE_TCHAR。

注意

dbghelp.h 标头将 SymFindFileInPath 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。