Debugging Tools for Windows

FindSourceFileAndToken

The FindSourceFileAndToken and FindSourceFileAndTokenWide methods returns the filename of a source file on the source path or return the value of a variable associated with a file token.

HRESULT
  IDebugAdvanced2::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
    );

HRESULT
  IDebugAdvanced3::FindSourceFileAndTokenWide(
    IN ULONG  StartElement,
    IN ULONG64  ModAddr,
    IN PCWSTR  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
    );

#ifdef UNICODE
#define FindSourceFileAndTokenT FindSourceFileAndTokenWide
#else
#define FindSourceFileAndTokenT FindSourceFileAndToken
#endif

Parameters

StartElement

Specifies the index of an element within the source path to start searching from. All elements in the source path before StartElement are excluded from the search. The index of the first element is zero. If StartElement is greater than or equal to the number of elements in the source path, the filing system is checked directly.

This parameter can be used with FoundElement to check for multiple matches in the source path.

StartElement is ignored if the flag DEBUG_FIND_SOURCE_TOKEN_LOOKUP is set in Flags.

ModAddr

Specifies a location within the memory allocation of the module in the target to which the source file is related. ModAddr is used for caching the search results and when querying source servers for the file. ModAddr can be NULL.

ModAddr is ignored if the flag DEBUG_FIND_SOURCE_TOKEN_LOOKUP is set in Flags. And it is not used for querying source servers if FileToken is not NULL.

File

Specifies the path and filename of the file to search for.

If the flag DEBUG_FIND_SOURCE_TOKEN_LOOKUP is set, the file is already specified by the token in FileToken. In this case, File specifies the name of a variable on the source server related to the file. The variable must begin and end with the percent sign ( % ), for example, %SRCSRVCMD%. The value of this variable is returned.

Flags

Specifies the flags that control the behavior of this method. For a description of these flags, see DEBUG_FIND_SOURCE_XXX.

FileToken

Specifies a file token representing a file on a source server. A file token can be obtained by setting Which to DEBUG_SRCFILE_SYMBOL_TOKEN in the method GetSourceFileInformation.

If the flag DEBUG_FIND_SOURCE_TOKEN_LOOKUP is set, FileToken must not be NULL.

FileTokenSize

Specifies the size in bytes of the FileToken token. If FileToken is NULL, this parameter is ignored.

FoundElement

Receives the index of the element within the source path that contained the file. If the file was found directly on the filing system (not using the source path), -1 is returned to FoundElement. If FoundElement is NULL or Flags contain DEBUG_SRCFILE_SYMBOL_TOKEN, this information is not returned.

Buffer

Receives the name of the file that was found. If the file is not on a source server, this is the name of the file in the local source cache. If the flag DEBUG_FIND_SOURCE_FULL_PATH is set, this is the full canonical path name for the file. Otherwise, it is the concatenation of the directory in the source path with the tail of File that was used to find the file.

If the flag DEBUG_SRCFILE_SYMBOL_TOKEN is set in Flags, Buffer receives the value of the variable named File associated with the file token FileToken.

If Buffer is NULL, this information is not returned.

BufferSize

Specifies the size in characters of the Buffer buffer. If Buffer is NULL, this parameter is ignored.

FoundSize

Specifies the size in characters of the name of the file. If foundSize is NULL, this information is not returned.

Return Value

S_OK: The method was successful.
S_FALSE: The method was successful. However, the Buffer buffer was too small to hold the file name or variable value, so the string was truncated to fit in the buffer.

This method may also return error values. See Return Values for more details.

Interface Version

FindSourceFileAndToken is available in IDebugAdvanced2 and later versions. FindSourceFileAndTokenWide is available in IDebugAdvanved3 and later versions.

Comments

When the flag DEBUG_SRCFILE_SYMBOL_TOKEN is set in Flags, this method does not search for a file on the source path. Instead, it looks up a variable associated with the file token provided in FileToken. These variables are documented in the file sdk\srcsrv\Srcsrv.doc in the Debugging Tools for Windows installation. For example, to retrieve the value of the variable SRCSRVCMD—the command to extract the source file from source control (also returned by the DEBUG_SRCFILE_SYMBOL_TOKEN_SOURCE_COMMAND_WIDE function of GetSourceFileInformation)—set File to %SRCSRVCMD%.

The engine uses the following steps—in order—to search for the file:

If the source path contains any source servers and the flag DEBUG_FIND_SOURCE_NO_SRCSRV is not set, the source server in the source path is searched first.
The first match found is returned.
For each directory in the source path, an attempt is made to find an overlap between the end of the directory path and the beginning of the file path. For example, if the source path contains a directory C:\a\b\c\d and File is c\d\e\foo.c, the file C:\a\b\c\d\e\foo.c is a match.
If the flag DEBUG_FIND_SOURCE_BEST_MATCH is set, the match with the longest overlap is returned; otherwise, the first match is returned.
For each directory in the source path, File is appended to the directory. If no match is found, this process is repeated and each time the first directory is removed from the beginning of the file path. For example, if the source path contains a directory C:\a\b and File is c\d\e\foo.c, the file C:\a\b\e\foo.c is a match.
The first match found is returned.
The file File is looked up directly on the filing system.

For more information about source files, see Using Source Files. For an overview of the source path and its syntax, see Source Path.

Requirements