Função SymFindFileInPath (dbghelp.h)

Artigo
08/23/2023

Localiza um arquivo de símbolo ou uma imagem executável.

Sintaxe

BOOL IMAGEAPI SymFindFileInPath(
  [in]           HANDLE                  hprocess,
  [in, optional] PCSTR                   SearchPath,
  [in]           PCSTR                   FileName,
  [in, optional] PVOID                   id,
  [in]           DWORD                   two,
  [in]           DWORD                   three,
  [in]           DWORD                   flags,
  [out]          PSTR                    FoundFile,
  [in, optional] PFINDFILEINPATHCALLBACK callback,
  [in, optional] PVOID                   context
);

Parâmetros

[in] hprocess

Um identificador para o processo que foi originalmente passado para a função SymInitialize .

[in, optional] SearchPath

O caminho de pesquisa. Pode ser vários caminhos separados por ponto e vírgula. Ele pode incluir diretórios e servidores de símbolos. Se esse parâmetro for NULL, a função usará o conjunto de caminhos de pesquisa usando a função SymSetSearchPath ou SymInitialize .

[in] FileName

O nome do arquivo. Você pode especificar um caminho; no entanto, somente o nome do arquivo é usado.

[in, optional] id

O primeiro dos três parâmetros de identificação (consulte Comentários).

[in] two

O segundo de três parâmetros de identificação (consulte Comentários).

[in] three

O terceiro dos três parâmetros de identificação (consulte Comentários).

[in] flags

O formato do parâmetro id . Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
SSRVOPT_DWORD 0x0002	O parâmetro id é um DWORD.
SSRVOPT_DWORDPTR 0x0004	O parâmetro id é um ponteiro para um DWORD.
SSRVOPT_GUIDPTR 0x0008	O parâmetro id é um ponteiro para um GUID.

[out] FoundFile

Um ponteiro para um buffer que recebe o caminho totalmente qualificado para o arquivo de símbolo. Esse buffer deve ser pelo menos MAX_PATH caracteres.

[in, optional] callback

Uma função de retorno de chamada SymFindFileInPathProc .

[in, optional] context

Um valor definido pelo usuário ou NULL. Esse valor é simplesmente passado para a função de retorno de chamada. Esse parâmetro normalmente é usado por um aplicativo para passar um ponteiro para uma estrutura de dados que fornece algum contexto para a função de retorno de chamada.

Retornar valor

Se o servidor localizar um arquivo de símbolo válido, ele retornará TRUE; caso contrário, ele retorna FALSE e GetLastError retorna um valor que indica por que o arquivo de símbolo não foi retornado.

Comentários

Os parâmetros de identificação são preenchidos da seguinte maneira:

Se DbgHelp estiver procurando um arquivo .pdb, o parâmetro id especificará a assinatura PDB, conforme encontrado no diretório de depuração de exibição de código da imagem original. O parâmetro dois especifica a idade do PDB. O parâmetro três não é utilizado e definido como zero.
Se DbgHelp estiver procurando qualquer outro tipo de imagem, como um arquivo executável ou um arquivo .dbg, o parâmetro id especifica o TimeDateStamp da imagem original, conforme encontrado em seu cabeçalho PE. O parâmetro dois especifica o campo SizeOfImage, também extraído do cabeçalho PE. O parâmetro três não é utilizado e definido como zero.

Todos esses valores podem ser obtidos chamando SymSrvGetFileIndexInfo.

Ao pesquisar um diretório, essa função não verifica se os identificadores de símbolo correspondem por padrão. Para garantir que os arquivos de símbolo correspondentes estejam localizados, chame a função SymSetOptions com SYMOPT_EXACT_SYMBOLS.

Todas as funções DbgHelp, como esta, são threaded único. Portanto, chamadas de mais de um thread para essa função provavelmente resultarão em comportamento inesperado ou corrupção de memória. Para evitar isso, você deve sincronizar todas as chamadas simultâneas de mais de um thread para essa função.

Para chamar a versão Unicode dessa função, defina DBGHELP_TRANSLATE_TCHAR.