symFindFileInPath 函式 (dbghelp.h)

發行項
02/26/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

The first of three identifying parameters (see Remarks).

[in] two

三個識別參數中的第二個 (請參閱) 。

[in] three

The third of three identifying parameters (see Remarks).

[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 簽章。參數二指定 PDB 存留期。未使用參數 3 ，並將設定為零。
如果 DbgHelp 正在尋找其他類型的映像，例如可執行檔或 .dbg 檔案， 則 id 參數會指定原始映像的 TimeDateStamp，如其 PE 標頭中所找到。參數二會指定 SizeOfImage 欄位，也會從 PE 標頭擷取。未使用參數 3 ，並將設定為零。

呼叫 SymSrvGetFileIndexInfo 即可取得所有這些值。

搜尋目錄時，此函式預設不會驗證符號識別碼是否相符。若要確保找到相符的符號檔，請使用 SYMOPT_EXACT_SYMBOLS呼叫 SymSetOptions 函式。

所有 DbgHelp 函式，例如此函式都是單個線程。因此，從一個以上的線程呼叫此函式可能會導致非預期的行為或記憶體損毀。若要避免這種情況，您必須將所有並行呼叫從一個以上的線程同步至此函式。

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