SymFindFileInPath 函式（dbghelp.h）

定位符號檔案或可執行影像。

語法

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
);

Parameters

[in] hprocess

一個原本傳遞給 SymInitialize 函式的程序的 handle 。

[in, optional] SearchPath

搜尋路徑。這可能是多條路徑，中間用分號分隔。它可以包含目錄和符號伺服器。若此參數為 NULL，函式會使用 SymSetSearchPath 或 SymInitialize 函式的搜尋路徑集合。

[in] FileName

檔案的檔名。你可以指定一條路徑;但僅使用檔名。

[in, optional] id

三個識別參數中的第一個（見備註）。

[in] two

三個識別參數中的第二個（見備註）。

[in] three

三個識別參數中的第三個（見備註）。

[in] flags

id 參數的 格式。此參數可以是下列其中一個值。

價值	Meaning
SSRVOPT_DWORD 0x0002	ID 參數是 DWORD。
SSRVOPT_DWORDPTR 0x0004	ID 參數是指向 DWORD 的指標。
SSRVOPT_GUIDPTR 0x0008	id 參數是指向 GUID 的指標。

[out] FoundFile

一個指向緩衝區的指標，該緩衝區接收到符號檔案的完全限定路徑。此緩衝區必須至少為MAX_PATH+1個字元。

[in, optional] callback

一個 SymFindFileInPathProc 回調函式。

[in, optional] context

使用者定義的值或 NULL。 這個值會直接傳遞給回調函式。這個參數通常被應用程式用來傳遞指標到提供回調函式上下文的資料結構。

返回值

如果伺服器找到有效的符號檔，則會回傳 TRUE;否則，它會回傳 FALSE ，而 GetLastError 會回傳一個值，說明為何該符號檔案未被回傳。

備註

識別參數填寫如下：

若 DbgHelp 尋找 .pdb 檔案， id 參數會指定原始影像 codeview 除錯目錄中的 PDB 簽章。參數二指定 PDB 的年齡。參數三未被使用，設為零。
若 DbgHelp 尋找其他類型的影像，如可執行檔或 .dbg 檔案， id 參數會指定原始影像的 PE 標頭中的 TimeDateStamp。參數二指定 SizeOfImage 欄位，該欄位同樣從 PE 標頭擷取。參數三未被使用，設為零。

所有這些值都可以透過呼叫 SymSrvGetFileIndexInfo 來取得。

在搜尋目錄時，這個函式不會驗證符號識別碼預設是否相符。為了確保匹配的符號檔案被找到，請呼叫帶有 SYMOPT_EXACT_SYMBOLS 的 SymSetOptions 函式。

所有 DbgHelp 函式，例如這個，都是單執行緒。因此，來自多個執行緒對此函式的呼叫，很可能導致意外行為或記憶體損毀。為避免此情況，您必須將多個執行緒的所有同時呼叫同步至此函式。

要呼叫此函式的 Unicode 版本，請定義 DBGHELP_TRANSLATE_TCHAR。