Função StackWalk (dbghelp.h)

Obtém um rastreamento de pilha.

Sintaxe

BOOL IMAGEAPI StackWalk(
  [in]           DWORD                          MachineType,
  [in]           HANDLE                         hProcess,
  [in]           HANDLE                         hThread,
  [in, out]      LPSTACKFRAME                   StackFrame,
  [in, out]      PVOID                          ContextRecord,
  [in, optional] PREAD_PROCESS_MEMORY_ROUTINE   ReadMemoryRoutine,
  [in, optional] PFUNCTION_TABLE_ACCESS_ROUTINE FunctionTableAccessRoutine,
  [in, optional] PGET_MODULE_BASE_ROUTINE       GetModuleBaseRoutine,
  [in, optional] PTRANSLATE_ADDRESS_ROUTINE     TranslateAddress
);

Parâmetros

[in] MachineType

O tipo de arquitetura do computador para o qual o rastreamento de pilha é gerado. Esse parâmetro pode usar um dos valores a seguir.

[in] hProcess

Um identificador para o processo para o qual o rastreamento de pilha é gerado. Se o chamador fornecer um ponteiro de retorno de chamada válido para o parâmetro ReadMemoryRoutine , esse valor não precisará ser um identificador de processo válido. Pode ser um token exclusivo e consistentemente o mesmo para todas as chamadas para a função StackWalk64 . Se o manipulador de símbolos for usado com StackWalk64, use os mesmos identificadores de processo para as chamadas para cada função.

[in] hThread

Um identificador para o thread para o qual o rastreamento de pilha é gerado. Se o chamador fornecer um ponteiro de retorno de chamada válido para o parâmetro ReadMemoryRoutine , esse valor não precisará ser um identificador de thread válido. Pode ser um token exclusivo e consistentemente o mesmo para todas as chamadas para a função StackWalk64 .

[in, out] StackFrame

Um ponteiro para uma estrutura STACKFRAME64 . Essa estrutura receberá informações para o próximo quadro, se a chamada de função for bem-sucedida.

[in, out] ContextRecord

Um ponteiro para uma estrutura CONTEXT . Esse parâmetro é necessário somente quando o parâmetro MachineType não é IMAGE_FILE_MACHINE_I386. No entanto, é recomendável que esse parâmetro contenha um registro de contexto válido. Isso permite que o StackWalk64 lide com uma maior variedade de situações.

Esse contexto pode ser modificado, portanto, não passe um registro de contexto que não deve ser modificado.

[in, optional] ReadMemoryRoutine

Uma rotina de retorno de chamada que fornece serviços de leitura de memória. Quando a função StackWalk64 precisa ler a memória do espaço de endereço do processo, o retorno de chamada ReadProcessMemoryProc64 é usado.

Se esse parâmetro for NULL, a função usará uma rotina padrão. Nesse caso, o parâmetro hProcess deve ser um identificador de processo válido.

Se esse parâmetro não for NULL, o aplicativo deverá implementar e registrar uma função de retorno de chamada do manipulador de símbolos que manipula CBA_READ_MEMORY.

[in, optional] FunctionTableAccessRoutine

Uma rotina de retorno de chamada que fornece acesso à tabela de funções em tempo de execução para o processo. Esse parâmetro é necessário porque a função StackWalk64 não tem acesso à tabela de funções em tempo de execução do processo. Para obter mais informações, consulte FunctionTableAccessProc64.

O manipulador de símbolos fornece funções que carregam e acessam a tabela em tempo de execução. Se essas funções forem usadas, SymFunctionTableAccess64 poderá ser passado como um parâmetro válido.

[in, optional] GetModuleBaseRoutine

Uma rotina de retorno de chamada que fornece uma base de módulo para qualquer endereço virtual especificado. Este parâmetro é necessário. Para obter mais informações, consulte GetModuleBaseProc64.

O manipulador de símbolos fornece funções que carregam e mantêm informações de módulo. Se essas funções forem usadas, SymGetModuleBase64 poderá ser passado como um parâmetro válido.

[in, optional] TranslateAddress

Uma rotina de retorno de chamada que fornece tradução de endereço para endereços de 16 bits. Para obter mais informações, consulte TranslateAddressProc64.

A maioria dos chamadores do StackWalk64 pode passar NULL com segurança para esse parâmetro.

Retornar valor

Se a função for bem-sucedida, o valor retornado será TRUE.

Se a função falhar, o valor retornado será FALSE. Observe que o StackWalk64 geralmente não define o último código de erro.

Comentários

A função StackWalk64 fornece um método portátil para obter um rastreamento de pilha. O uso da função StackWalk64 é recomendado ao escrever sua própria função devido a todas as complexidades associadas à movimentação de pilha em plataformas. Além disso, há opções do compilador que fazem com que a pilha apareça de forma diferente, dependendo de como o módulo é compilado. Usando essa função, seu aplicativo tem um rastreamento de pilha portátil que continua funcionando à medida que o compilador e o sistema operacional mudam.

A primeira chamada para essa função falhará se os membros AddrPC, AddrFrame e AddrStack da estrutura STACKFRAME64 passada no parâmetro StackFrame não forem inicializados.

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.

Essa função substitui a função StackWalk . Para obter mais informações, consulte Suporte de plataforma atualizado. StackWalk é definido da seguinte maneira em DbgHelp.h.

#if !defined(_IMAGEHLP_SOURCE_) && defined(_IMAGEHLP64)
#define StackWalk StackWalk64
#else
BOOL
IMAGEAPI
StackWalk(
    DWORD MachineType,
    __in HANDLE hProcess,
    __in HANDLE hThread,
    __inout LPSTACKFRAME StackFrame,
    __inout PVOID ContextRecord,
    __in_opt PREAD_PROCESS_MEMORY_ROUTINE ReadMemoryRoutine,
    __in_opt PFUNCTION_TABLE_ACCESS_ROUTINE FunctionTableAccessRoutine,
    __in_opt PGET_MODULE_BASE_ROUTINE GetModuleBaseRoutine,
    __in_opt PTRANSLATE_ADDRESS_ROUTINE TranslateAddress
    );

#endif

Requisitos

Confira também

CONTEXTO

Funções DbgHelp

FunctionTableAccessProc64

GetModuleBaseProc64

ReadProcessMemoryProc64

STACKFRAME64

TranslateAddressProc64