IDebugSymbols3::GetSourceEntriesByLineWide method (dbgeng.h)

Article
07/26/2023

The GetSourceEntriesByLineWide method queries symbol information and returns locations in the target's memory that correspond to lines in a source file.

Syntax

HRESULT GetSourceEntriesByLineWide(
  [in]            ULONG                      Line,
  [in]            PCWSTR                     File,
  [in]            ULONG                      Flags,
  [out, 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, 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
S_OK	The method was successful.
S_FALSE	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.
E_NOINTERFACE	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)