Метод IDebugAdvanced3::FindSourceFileAndToken (dbgeng.h)

Статья
02/06/2025

Метод 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 исключены из поиска. Индекс первого элемента равен нулю. Если StartElement больше или равно количеству элементов в пути к источнику, система подачи проверяется непосредственно.

Этот параметр можно использовать с FoundElement для проверки нескольких совпадений в пути к источнику.

StartElement игнорируется, если флаг DEBUG_FIND_SOURCE_TOKEN_LOOKUP установлен в Флаги.

[in] ModAddr

Указывает расположение в выделении памяти модуля в целевом объекте, к которому связан исходный файл. ModAddr используется для кэширования результатов поиска и при запросе исходных серверов для файла. ModAddr можно NULL.

МодАддр игнорируется, если флаг DEBUG_FIND_SOURCE_TOKEN_LOOKUP установлен в Флаги. И он не используется для запроса исходных серверов, если FileToken не NULL.

[in] File

Указывает путь и имя файла для поиска.

Если установлен флаг DEBUG_FIND_SOURCE_TOKEN_LOOKUP, файл уже указан маркером в FileToken. В этом случае файл указывает имя переменной на исходном сервере, связанном с файлом. Переменная должна начинаться и заканчиваться знаком процента (%), например, %SRCSRVCMD%. Возвращается значение этой переменной.

[in] Flags

Указывает флаги, управляющие поведением этого метода. Описание этих флагов см. в разделе "Примечания".

[in, optional] FileToken

Указывает маркер файла, представляющий файл на исходном сервере. Маркер файла можно получить, задав DEBUG_SRCFILE_SYMBOL_TOKEN в методе GetSourceFileInformation.

Если установлен флаг DEBUG_FIND_SOURCE_TOKEN_LOOKUP, FileToken не должно быть NULL.

[in] FileTokenSize

Задает размер в байтах маркера FileToken. Если FileTokenNULL, этот параметр игнорируется.

[out, optional] FoundElement

Получает индекс элемента в исходном пути, содержавшемся в файле. Если файл был найден непосредственно в системе подачи (не используя исходный путь), -1 возвращается в FoundElement. Если FoundElementзначение NULL или флаг и содержат DEBUG_SRCFILE_SYMBOL_TOKEN, эти сведения не возвращаются.

[out, optional] Buffer

Получает имя найденного файла. Если файл не находится на исходном сервере, это имя файла в локальном кэше источника. Если установлен флаг DEBUG_FIND_SOURCE_FULL_PATH, это полное каноническое имя файла. В противном случае это объединение каталога в пути к источнику с хвостом файла, который использовался для поиска файла.

Если флаг DEBUG_SRCFILE_SYMBOL_TOKEN задан в Flags, Buffer получает значение переменной с именем File, связанной с маркером файла FileToken.

Если буферnull, эти сведения не возвращаются.

[in] BufferSize

Задает размер символов буфера . Этот размер включает пробел для завершающего символа \0. Если буферnull, этот параметр игнорируется.

[out, optional] FoundSize

Задает размер в символах имени файла. Этот размер включает пробел для завершающего символа \0. Если foundSizenull, эти сведения не возвращаются.

Возвращаемое значение

Этот метод также может возвращать значения ошибок. Дополнительные сведения см. в возвращаемых значений.

Возвращаемый код	Описание
S_OK	Метод был успешным.
S_FALSE	Метод был успешным. Однако буфер буфера слишком мал для хранения имени файла или значения переменной, поэтому строка была усечена для размещения в буфере.

Замечания

Если флаг DEBUG_SRCFILE_SYMBOL_TOKEN задан в Flags, этот метод не ищет файл в исходном пути. Вместо этого он ищет переменную, связанную с маркером файла, предоставленным в FileToken. Эти переменные описаны в разделе спецификации языка 1. Например, чтобы получить значение переменной SRCSRVCMD- команда для извлечения исходного файла из системы управления версиями (также возвращается функцией DEBUG_SRCFILE_SYMBOL_TOKEN_SOURCE_COMMAND_WIDE getSourceFileInformation)-set File для %SRCSRVCMD%.

Подсистема использует следующие шаги для поиска файла:

Если исходный путь содержит все исходные серверы и флаг DEBUG_FIND_SOURCE_NO_SRCSRV не задан, исходный сервер в исходном пути сначала выполняется поиск.
Возвращается первое совпадение.
Для каждого каталога в исходном пути выполняется попытка найти перекрытие между концом пути к каталогу и началом пути к файлу. Например, если исходный путь содержит каталог C:\a\a\b\c\d и File является c\d\e\foo.c, файл C:\a\a\c\d\e\foo.c является совпадением.
Если установлен флаг DEBUG_FIND_SOURCE_BEST_MATCH, возвращается совпадение с самым длинным перекрытием; в противном случае возвращается первое совпадение.
Для каждого каталога в пути к источнику файл добавляется в каталог. Если совпадение не найдено, этот процесс повторяется и каждый раз, когда первый каталог удаляется с начала пути к файлу. Например, если исходный путь содержит каталог C:\a\b и Файл является 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.