SymFindFileInPath 函数 (dbghelp.h)

项目
02/29/2024

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

语法

BOOL IMAGEAPI SymFindFileInPath(
  [in]           HANDLE                  hprocess,
  [in, optional] PCSTR                   SearchPath,
  [in]           PCSTR                   FileName,
  [in, optional] PVOID                   id,
  [in]           DWORD                   two,
  [in]           DWORD                   three,
  [in]           DWORD                   flags,
  [out]          PSTR                    FoundFile,
  [in, optional] PFINDFILEINPATHCALLBACK 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 参数将指定原始映像的 TimeDateStamp，如其 PE 标头中所示。参数 2 指定也从 PE 标头中提取的 SizeOfImage 字段。参数 3 未使用，并设置为零。

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

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

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

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