IDebugAdvanced3：：FindSourceFileAndToken 方法 (dbgeng.h)

發行項
02/25/2024

FindSourceFileAndToken 方法會傳回來源路徑上來源檔案的檔名，或傳回與檔案令牌相關聯的變數值。

語法

HRESULT FindSourceFileAndToken(
  [in]            ULONG   StartElement,
  [in]            ULONG64 ModAddr,
  [in]            PCSTR   File,
  [in]            ULONG   Flags,
  [in, optional]  PVOID   FileToken,
  [in]            ULONG   FileTokenSize,
  [out, optional] PULONG  FoundElement,
  [out, optional] PSTR    Buffer,
  [in]            ULONG   BufferSize,
  [out, optional] PULONG  FoundSize
);

參數

[in] StartElement

指定來源路徑中開始搜尋的專案索引。 在 StartElement 之前來源路徑中的所有元素都會從搜尋中排除。第一個專案的索引為零。如果 StartElement 大於或等於來源路徑中的元素數目，則會直接檢查文件系統。

此參數可以搭配 FoundElement 使用，以檢查來源路徑中的多個相符專案。

如果在 Flags 中設定旗標DEBUG_FIND_SOURCE_TOKEN_LOOKUP，則會忽略 StartElement。

[in] ModAddr

指定來源檔案相關目標中模組記憶體配置內的位置。 ModAddr 用於快取搜尋結果，以及查詢檔案的來源伺服器時。 ModAddr 可以是 NULL。

如果在 Flags 中設定旗標DEBUG_FIND_SOURCE_TOKEN_LOOKUP，則會忽略 ModAddr。如果 FileToken 不是 NULL，則不會用於查詢來源伺服器。

[in] File

指定要搜尋之檔案的路徑和檔名。

如果設定旗標DEBUG_FIND_SOURCE_TOKEN_LOOKUP，則檔案已經由 FileToken 中的令牌指定。在此情況下， File 會指定與檔案相關的來源伺服器上變數的名稱。變數的開頭和結尾必須是百分比符號 ( % ) ，例如 %SRCSRVCMD%。 傳回此變數的值。

[in] Flags

指定控制此方法行為的旗標。如需這些旗標的描述，請參閱。

[in, optional] FileToken

指定代表來源伺服器上的檔案的檔案令牌。您可以藉由在 GetSourceFileInformation 方法中將 [要DEBUG_SRCFILE_SYMBOL_TOKEN的檔案令牌] 設定為取得。

如果設定旗標 DEBUG_FIND_SOURCE_TOKEN_LOOKUP，FileToken 不得為 NULL。

[in] FileTokenSize

指定 FileToken 令牌位元組的大小。如果 FileToken 為 NULL，則會忽略此參數。

[out, optional] FoundElement

在包含檔案的來源路徑內，接收專案的索引。如果檔案直接在文件系統上找到， (不使用來源路徑) ，則會將 -1 傳回 FoundElement。如果 FoundElement 為 NULL 或 Flags 包含DEBUG_SRCFILE_SYMBOL_TOKEN，則不會傳回這項資訊。

[out, optional] Buffer

接收找到的檔名。如果檔案不在來源伺服器上，這是本機來源快取中的檔名。如果設定旗標DEBUG_FIND_SOURCE_FULL_PATH，這是檔案的完整標準路徑名稱。否則，它是來源路徑中目錄的串連，以及用來尋找檔案的檔案尾端。

如果在 Flags 中設定旗標DEBUG_SRCFILE_SYMBOL_TOKEN，Buffer 就會接收名為 File 與檔案令牌 FileToken 相關聯的變數值。

如果 Buffer 是 NULL，則不會傳回這項資訊。

[in] BufferSize

指定 緩衝區 緩衝區的字元大小。此大小包含『\0』終止字元的空間。如果 Buffer 是 NULL，則會忽略此參數。

[out, optional] FoundSize

指定檔案名的字元大小。此大小包含『\0』終止字元的空間。如果 foundSize 為 NULL，則不會傳回此資訊。

傳回值

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

傳回碼	描述
S_OK	此方法成功。
S_FALSE	此方法成功。不過，緩衝區緩衝區太小而無法保存檔名或變數值，因此會截斷字串以符合緩衝區。

備註

在 Flags 中設定旗標DEBUG_SRCFILE_SYMBOL_TOKEN時，此方法不會搜尋來源路徑上的檔案。相反地，它會查閱與 FileToken 中提供的檔案令牌相關聯的變數。這些變數記載於語言規格 1 主題中。例如，若要擷取變數 SRCSRVCMD 的值--命令，從原始檔控制擷取原始檔 (也會由 GetSourceFileInformation) --set File 設為 %SRCSRVCMD% DEBUG_SRCFILE_SYMBOL_TOKEN_SOURCE_COMMAND_WIDE 傳回。

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

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

如需原始程式檔的詳細資訊，請參閱使用原始程序檔。如需來源路徑及其語法的概觀，請參閱來源路徑。

DEBUG_FIND_SOURCE_XXX 位旗標可用來控制搜尋來源檔案時 FindSourceFile 和 FindSourceFileAndToken 方法的行為。

旗標可以是下表中值的任何組合。

常數	描述
DEBUG_FIND_SOURCE_FULL_PATH	一律傳回找到檔案的完整標準路徑名稱。如果未設定，且來源路徑包含相對目錄，則可以傳回相對路徑名稱。
DEBUG_FIND_SOURCE_BEST_MATCH	在找到相符項目之後繼續搜尋，以尋找更好的相符專案。
DEBUG_FIND_SOURCE_NO_SRCSRV	請勿在搜尋中包含來源伺服器。
DEBUG_FIND_SOURCE_TOKEN_LOOKUP	傳回與檔案令牌相關聯的變數。如果設定此旗標，則會忽略其他旗標。這個旗標不能用於 FindSourceFile 方法中。