IDebugAdvanced3::FindSourceFileAndToken メソッド (dbgeng.h)

[アーティクル]
08/07/2023

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 より前のソースパス内のすべての要素は、検索から除外されます。最初の要素のインデックスは 0 です。 StartElement がソースパス内の要素の数以上の場合は、ファイリングシステムが直接チェックされます。

このパラメーターを FoundElement と共に使用して、ソースパス内の複数の一致をチェックできます。

フラグ DEBUG_FIND_SOURCE_TOKEN_LOOKUPが Flags に設定されている場合、StartElement は無視されます。

[in] ModAddr

ソースファイルが関連付けられているターゲット内のモジュールのメモリ割り当て内の場所を指定します。 ModAddr は、検索結果をキャッシュしたり、ソースサーバーにファイルを照会したりするために使用されます。 ModAddr には NULL を指定できます。

フラグ DEBUG_FIND_SOURCE_TOKEN_LOOKUPが Flags に設定されている場合、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 であるか、フラグにDEBUG_SRCFILE_SYMBOL_TOKENが含まれている場合、この情報は返されません。

[out, optional] Buffer

見つかったファイルの名前を受け取ります。ファイルがソースサーバー上にない場合、これはローカルソースキャッシュ内のファイルの名前です。フラグ DEBUG_FIND_SOURCE_FULL_PATHが設定されている場合、これはファイルの完全な正規パス名です。それ以外の場合は、ファイルの検索に使用された File の末尾とソースパス内のディレクトリの連結です。

フラグ DEBUG_SRCFILE_SYMBOL_TOKENが Flags に設定されている場合、Buffer はファイルトークン FileToken に関連付けられている File という名前の変数の値を受け取ります。

Buffer が NULL の場合、この情報は返されません。

[in] BufferSize

バッファー バッファーのサイズを文字数で指定します。このサイズには、'\0' 終端文字のスペースが含まれます。 Buffer が NULL の場合、このパラメーターは無視されます。

[out, optional] FoundSize

ファイル名のサイズを文字数で指定します。このサイズには、'\0' 終端文字のスペースが含まれます。 foundSize が NULL の場合、この情報は返されません。

戻り値

このメソッドは、エラー値を返す場合もあります。詳細については、「戻り値」を参照してください。

リターンコード	説明
S_OK	メソッドは正常に実行されました。
S_FALSE	メソッドは正常に実行されました。ただし、バッファーバッファーが小さすぎてファイル名または変数の値を保持できなかったため、バッファーに収まるように文字列が切り捨てられました。

注釈

フラグ DEBUG_SRCFILE_SYMBOL_TOKENが Flags で設定されている場合、このメソッドはソースパス上のファイルを検索しません。代わりに、 FileToken で提供されるファイルトークンに関連付けられている変数を検索します。これらの変数については、「言語仕様 1」のトピックを参照してください。たとえば、変数 SRCSRVCMD の値を取得するには--ソース管理からソースファイルを抽出するコマンド ( GetSourceFileInformation のDEBUG_SRCFILE_SYMBOL_TOKEN_SOURCE_COMMAND_WIDE関数によっても返されます)、 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 メソッドでは使用できません。