IDebugSymbols2：：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 是相符的。
會傳回找到的第一個相符專案。
檔案會直接在文件系統上查閱。