Método IDebugAdvanced3::FindSourceFileAndToken (dbgeng.h)

Artigo
03/08/2023

O método FindSourceFileAndToken retorna o nome de arquivo de um arquivo de origem no caminho de origem ou retorna o valor de uma variável associada a um token de arquivo.

Sintaxe

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
);

Parâmetros

[in] StartElement

Especifica o índice de um elemento dentro do caminho de origem do qual começar a pesquisar. Todos os elementos no caminho de origem antes de StartElement são excluídos da pesquisa. O índice do primeiro elemento é zero. Se StartElement for maior ou igual ao número de elementos no caminho de origem, o sistema de arquivamento será verificado diretamente.

Esse parâmetro pode ser usado com FoundElement para marcar para várias correspondências no caminho de origem.

StartElement será ignorado se o sinalizador DEBUG_FIND_SOURCE_TOKEN_LOOKUP estiver definido em Sinalizadores.

[in] ModAddr

Especifica um local dentro da alocação de memória do módulo no destino ao qual o arquivo de origem está relacionado. ModAddr é usado para armazenar em cache os resultados da pesquisa e ao consultar servidores de origem para o arquivo. ModAddr pode ser NULL.

ModAddr será ignorado se o sinalizador DEBUG_FIND_SOURCE_TOKEN_LOOKUP estiver definido em Sinalizadores. E ele não será usado para consultar servidores de origem se FileToken não for NULL.

[in] File

Especifica o caminho e o nome do arquivo a ser pesquisado.

Se o sinalizador DEBUG_FIND_SOURCE_TOKEN_LOOKUP estiver definido, o arquivo já será especificado pelo token em FileToken. Nesse caso, File especifica o nome de uma variável no servidor de origem relacionada ao arquivo. A variável deve começar e terminar com o sinal de porcentagem ( % ), por exemplo, %SRCSRVCMD%. O valor dessa variável é retornado.

[in] Flags

Especifica os sinalizadores que controlam o comportamento desse método. Para obter uma descrição desses sinalizadores, consulte Comentários.

[in, optional] FileToken

Especifica um token de arquivo que representa um arquivo em um servidor de origem. Um token de arquivo pode ser obtido definindo Qual DEBUG_SRCFILE_SYMBOL_TOKEN no método GetSourceFileInformation.

Se o sinalizador DEBUG_FIND_SOURCE_TOKEN_LOOKUP estiver definido, FileToken não deverá ser NULL.

[in] FileTokenSize

Especifica o tamanho em bytes do token FileToken . Se FileToken for NULL, esse parâmetro será ignorado.

[out, optional] FoundElement

Recebe o índice do elemento dentro do caminho de origem que continha o arquivo. Se o arquivo foi encontrado diretamente no sistema de arquivamento (não usando o caminho de origem), -1 será retornado para FoundElement. Se FoundElement for NULL ou Sinalizadores contiverem DEBUG_SRCFILE_SYMBOL_TOKEN, essas informações não serão retornadas.

[out, optional] Buffer

Recebe o nome do arquivo que foi encontrado. Se o arquivo não estiver em um servidor de origem, esse será o nome do arquivo no cache de origem local. Se o sinalizador DEBUG_FIND_SOURCE_FULL_PATH estiver definido, esse será o nome completo do caminho canônico para o arquivo. Caso contrário, é a concatenação do diretório no caminho de origem com a parte final do Arquivo que foi usada para localizar o arquivo.

Se o sinalizador DEBUG_SRCFILE_SYMBOL_TOKEN estiver definido em Sinalizadores, Buffer receberá o valor da variável chamada File associada ao token de arquivo FileToken.

Se Buffer for NULL, essas informações não serão retornadas.

[in] BufferSize

Especifica o tamanho em caracteres do buffer de buffer . Esse tamanho inclui o espaço para o caractere de terminação '\0'. Se Buffer for NULL, esse parâmetro será ignorado.

[out, optional] FoundSize

Especifica o tamanho em caracteres do nome do arquivo. Esse tamanho inclui o espaço para o caractere de terminação '\0'. Se foundSize for NULL, essas informações não serão retornadas.

Retornar valor

Esse método também pode retornar valores de erro. Consulte Valores retornados para obter mais detalhes.

Código de retorno	Descrição
S_OK	O método foi bem-sucedido.
S_FALSE	O método foi bem-sucedido. No entanto , o buffer buffer era muito pequeno para manter o nome do arquivo ou o valor da variável, portanto, a cadeia de caracteres foi truncada para caber no buffer.

Comentários

Quando o sinalizador DEBUG_SRCFILE_SYMBOL_TOKEN é definido em Sinalizadores, esse método não pesquisa um arquivo no caminho de origem. Em vez disso, ele pesquisa uma variável associada ao token de arquivo fornecido no FileToken. Essas variáveis estão documentadas no tópico Especificação da Linguagem 1. Por exemplo, para recuperar o valor da variável SRCSRVCMD– o comando para extrair o arquivo de origem do controle do código-fonte (também retornado pela função DEBUG_SRCFILE_SYMBOL_TOKEN_SOURCE_COMMAND_WIDE de GetSourceFileInformation)-- defina Arquivo como %SRCSRVCMD%.

O mecanismo usa as seguintes etapas, na ordem, para pesquisar o arquivo:

Se o caminho de origem contiver servidores de origem e o sinalizador DEBUG_FIND_SOURCE_NO_SRCSRV não estiver definido, o servidor de origem no caminho de origem será pesquisado primeiro.
A primeira correspondência encontrada é retornada.
Para cada diretório no caminho de origem, é feita uma tentativa de localizar uma sobreposição entre o final do caminho do diretório e o início do caminho do arquivo. Por exemplo, se o caminho de origem contiver um diretório C:\a\b\c\d e File for c\d\e\foo.c, o arquivo C:\a\b\c\d\e\foo.c será uma correspondência.
Se o sinalizador DEBUG_FIND_SOURCE_BEST_MATCH estiver definido, a correspondência com a sobreposição mais longa será retornada; caso contrário, a primeira correspondência será retornada.
Para cada diretório no caminho de origem, File é acrescentado ao diretório. Se nenhuma correspondência for encontrada, esse processo será repetido e cada vez que o primeiro diretório for removido do início do caminho do arquivo. Por exemplo, se o caminho de origem contiver um diretório C:\a\b e File for c\d\e\foo.c, o arquivo C:\a\b\e\foo.c será uma correspondência.
A primeira correspondência encontrada é retornada.
O arquivo Arquivo é pesquisado diretamente no sistema de arquivamento.

Para obter mais informações sobre arquivos de origem, consulte Usando arquivos de origem. Para obter uma visão geral do caminho de origem e sua sintaxe, consulte Caminho de origem.

Os sinalizadores de bits DEBUG_FIND_SOURCE_XXX são usados para controlar o comportamento dos métodos FindSourceFile e FindSourceFileAndToken ao pesquisar arquivos de origem.

Os sinalizadores podem ser qualquer combinação de valores da tabela a seguir.

Constante	Descrição
DEBUG_FIND_SOURCE_FULL_PATH	Sempre retorne o nome completo do caminho canônico para o arquivo encontrado. Se não estiver definido e o caminho de origem contiver diretórios relativos, os nomes de caminho relativo poderão ser retornados.
DEBUG_FIND_SOURCE_BEST_MATCH	Continue pesquisando depois que uma correspondência for encontrada para procurar uma correspondência melhor.
DEBUG_FIND_SOURCE_NO_SRCSRV	Não inclua servidores de origem na pesquisa.
DEBUG_FIND_SOURCE_TOKEN_LOOKUP	Retornar uma variável associada a um token de arquivo. Se esse sinalizador for definido, os outros sinalizadores serão ignorados. Esse sinalizador não pode ser usado no método FindSourceFile .

O valor DEBUG_FIND_SOURCE_DEFULT define o conjunto padrão de sinalizadores, o que significa que todos os sinalizadores na tabela anterior estão desativados.