IDebugSymbols3：：FindSourceFile 方法 (dbgeng.h)

發行項
02/23/2024

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。如果 FoundElement 為 NULL，則不會傳回此資訊。

[out, optional] Buffer

接收找到檔案的路徑和名稱。如果已設定旗標DEBUG_FIND_SOURCE_FULL_PATH，這是檔案的完整標準路徑名稱。否則，它是來源路徑中目錄與用來尋找檔案之檔案結尾的串連。如果 Buffer 為 NULL，則不會傳回此資訊。

[in] BufferSize

指定 緩衝區 緩衝區的大小，以字元為單位。

[out, optional] FoundSize

指定檔案名稱的大小，以字元為單位。如果 FoundSize 為 NULL，則不會傳回此資訊。

傳回值

這個方法也可能傳回錯誤值。如需詳細資訊，請參閱傳回值。

傳回碼	描述
S_OK	此方法成功。
E_NOINTERFACE	來源路徑上找不到檔案。

備註

引擎會使用下列步驟來依序搜尋檔案：

針對來源路徑中的每個目錄，嘗試尋找目錄路徑結尾與檔案路徑開頭之間的重疊。例如，如果來源路徑包含目錄 C：\a\b\c\d 且 File 是 c\d\e\samplefile.c，則檔案 C：\a\b\c\d\e\samplefile.c 是相符的。
如果設定旗標DEBUG_FIND_SOURCE_BEST_MATCH，則會傳回與最長重疊的相符專案;否則會傳回第一個相符專案。
針對來源路徑中的每個目錄，檔案會附加至目錄。如果找不到相符專案，就會重複此程式，而且每次從檔案路徑的開頭移除第一個目錄時。例如，如果來源路徑包含目錄 C：\a\ b，File 是 c\d\e\samplefile.c，則 C：\a\b\e\samplefile.c 檔案會相符。
會傳回找到的第一個相符專案。
檔案會直接在文件系統上查閱。