IDebugAdvanced2：：FindSourceFileAndToken 方法 (dbgeng.h)

發行項
02/23/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 DEBUG_SRCFILE_SYMBOL_TOKEN_SOURCE_COMMAND_WIDE) --set File 設為 %SRCSRVCMD% 傳回。

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

如果來源路徑包含任何來源伺服器，而且未設定旗標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 方法中。