IDebugAdvanced3::FindSourceFileAndTokenWide method (dbgeng.h)
The FindSourceFileAndTokenWide method returns the filename of a source file on the source path or return the value of a variable associated with a file token.
Syntax
HRESULT 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] PWSTR Buffer,
[in] ULONG BufferSize,
[out, optional] PULONG FoundSize
);
Parameters
[in] 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.
[in] 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.
[in] 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.
[in] Flags
Specifies the flags that control the behavior of this method. For a description of these flags, see DEBUG_FIND_SOURCE_XXX.
[in, optional] 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.
[in] FileTokenSize
Specifies the size in bytes of the FileToken token. If FileToken is NULL, this parameter is ignored.
[out, optional] 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.
[out, optional] 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.
[in] BufferSize
Specifies the size in characters of the Buffer buffer. This size includes the space for the '\0' terminating character. If Buffer is NULL, this parameter is ignored.
[out, optional] FoundSize
Specifies the size in characters of the name of the file. This size includes the space for the '\0' terminating character. If foundSize is NULL, this information is not returned.
Return value
This method may also return error values. See Return Values for more details.
| Return code | Description |
|---|---|
|
The method was successful. |
|
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. |
Remarks
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 topic Language Specification 1. 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.
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Desktop |
| Header | dbgeng.h (include Dbgeng.h) |