Método IDebugSymbols::FindSourceFile (dbgeng.h)

Artigo
08/07/2023

O método FindSourceFile pesquisa o caminho de origem para um arquivo de origem especificado.

Sintaxe

HRESULT FindSourceFile(
  [in]            ULONG  StartElement,
  [in]            PCSTR  File,
  [in]            ULONG  Flags,
  [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.

[in] File

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

[in] Flags

Especifica os sinalizadores de pesquisa. Para obter uma descrição desses sinalizadores, consulte DEBUG_FIND_SOURCE_XXX.

O sinalizador DEBUG_FIND_SOURCE_TOKEN_LOOKUP não deve ser definido. O sinalizador DEBUG_FIND_SOURCE_NO_SRCSRV é ignorado porque esse método não inclui servidores de origem na pesquisa.

[out, optional] FoundElement

Recebe o índice do elemento dentro do caminho de origem que contém 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, essas informações não serão retornadas.

[out, optional] Buffer

Recebe o caminho e o nome do arquivo encontrado. 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 Buffer for NULL, essas informações não serão retornadas.

[in] BufferSize

Especifica o tamanho, em caracteres , do buffer de buffer.

[out, optional] FoundSize

Especifica o tamanho, em caracteres, do nome do arquivo. 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.
E_NOINTERFACE	O arquivo não foi encontrado no caminho de origem.

Comentários

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

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\samplefile.c, o arquivo C:\a\b\c\d\e\samplefile.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\samplefile.c, o arquivo C:\a\b\e\samplefile.c será uma correspondência.
A primeira correspondência encontrada é retornada.
O arquivo é pesquisado diretamente no sistema de arquivamento.

Nota Todos os servidores de origem no caminho de origem são ignorados. Para incluir os servidores de origem na pesquisa, use FindSourceFileAndToken com um endereço de módulo especificado em ModAddr.

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