IDebugSymbols3::GetSourceEntriesByLine method (dbgeng.h)
The GetSourceEntriesByLine method queries symbol information and returns locations in the target's memory that correspond to lines in a source file.
Syntax
HRESULT GetSourceEntriesByLine(
[in] ULONG Line,
[in] PCSTR File,
[in] ULONG Flags,
[out, writes, optional] PDEBUG_SYMBOL_SOURCE_ENTRY Entries,
[in] ULONG EntriesCount,
[out, optional] PULONG EntriesAvail
);
Parameters
[in] Line
Specifies the line in the source file for which to query. The number for the first line is 1.
[in] File
Specifies the source file. The symbols for each module in the target are queried for this file.
[in] Flags
Specifies bit flags that control the behavior of this method. Flags can be any combination of values from the following table.
| Value | Description |
|---|---|
| DEBUG_GSEL_NO_SYMBOL_LOADS |
The debugger engine will only search for the file among the modules whose symbols have already been loaded. Symbols for the other modules will not be loaded.
If this option is not set, the debugger engine will load the symbols for all modules until it finds the file specified in File. |
| DEBUG_GSEL_ALLOW_LOWER | Include all the lines in File before Line in the result. |
| DEBUG_GSEL_ALLOW_HIGHER | Include all the lines in File after Line in the result. |
| DEBUG_GSEL_NEAREST_ONLY | Only return at most one result. If DEBUG_GSEL_ALLOW_LOWER or DEBUG_GSEL_ALLOW_HIGHER are set, the returned result will be for a line close to Line but cannot be Line if there is no symbol information for that line. |
To use the default set of flags, set Flags to DEBUG_GSEL_DEFAULT. This has all the flags in the previous table turned off.
[out, writes, optional] Entries
Receives the locations in the target's memory that correspond to the source lines queried for. Each entry in this array is of type DEBUG_SYMBOL_SOURCE_ENTRY and contains the source line number along with a location in the target's memory.
[in] EntriesCount
Specifies the number of entries in the Entries array.
[out, optional] EntriesAvail
Receives the number of locations that match the query found in the target's memory.
Return value
These methods can also return error values. See Return Values for more details.
| Return code | Description |
|---|---|
|
The method was successful. |
|
The method was successful. However, the Entries array was not large enough to hold all the results that matched the query and the extra results were discarded. |
|
The query yielded no results. This includes the case where the symbol information was not available for the specified file. |
Remarks
These methods can be used by debugger applications to fetch locations in the target's memory for setting breakpoints or matching source code with disassembled instructions. For example, setting the flags DEBUG_GSEL_ALLOW_HIGHER and DEBUG_GSEL_NEAREST_ONLY will return the target's memory location for the first piece of code starting at the specified line.
For more information about source files, see Using Source Files.
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Desktop |
| Header | dbgeng.h (include Dbgeng.h) |