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

Статья
08/07/2023

Метод 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.

Параметр ModAddr игнорируется, если флаг DEBUG_FIND_SOURCE_TOKEN_LOOKUP установлен в разделе Флаги. Кроме того, он не используется для запросов к исходным серверам, если FileToken не имеет значение NULL.

[in] File

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

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

[in] Flags

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

[in, optional] FileToken

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

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

[in] FileTokenSize

Указывает размер маркера FileToken в байтах. Если FileToken имеет значение NULL, этот параметр игнорируется.

[out, optional] FoundElement

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

[out, optional] Buffer

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

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

Если параметр Buffer имеет значение NULL, эти сведения не возвращаются.

[in] BufferSize

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

[out, optional] FoundSize

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

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

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

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

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

Для поиска файла подсистема выполняет следующие действия (по порядку).

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