estrutura SYM_DUMP_PARAM (wdbgexts.h)

Artigo
08/08/2023

A IG_DUMP_SYMBOL_INFO operação Ioctl fornece informações sobre o tipo de símbolo. Ao chamar Ioctl com IoctlType definido como IG_DUMP_SYMBOL_INFO, IpvData deve conter uma instância da estrutura SYM_DUMP_PARAM.

Sintaxe

typedef struct _SYM_DUMP_PARAM {
  ULONG                    size;
  PUCHAR                   sName;
  ULONG                    Options;
  ULONG64                  addr;
  PFIELD_INFO              listLink;
  union {
    PVOID Context;
    PVOID pBuffer;
  };
  PSYM_DUMP_FIELD_CALLBACK CallbackRoutine;
  ULONG                    nFields;
  PFIELD_INFO              Fields;
  ULONG64                  ModBase;
  ULONG                    TypeId;
  ULONG                    TypeSize;
  ULONG                    BufferSize;
  ULONG                    fPointer : 2;
  ULONG                    fArray : 1;
  ULONG                    fStruct : 1;
  ULONG                    fConstant : 1;
  ULONG                    Reserved : 27;
} SYM_DUMP_PARAM, *PSYM_DUMP_PARAM;

Membros

size

Especifica o tamanho, em bytes, dessa estrutura. Ele deve ser definido como sizeof(SYM_DUMP_PARAM).

sName

Especifica o nome do símbolo a ser pesquisado.

Options

Especifica os sinalizadores que determinam o comportamento desta operação Ioctl . Para obter uma descrição desses sinalizadores, consulte Comentários.

addr

Especifica o endereço do símbolo.

listLink

Especifica o campo que contém o próximo item em uma lista vinculada. Se o símbolo for uma entrada em uma lista vinculada, essa operação Ioctl poderá iterar sobre os itens na lista usando o campo especificado aqui como o ponteiro para o próximo item na lista. O tipo dessa estrutura é FIELD_INFO.

A função de retorno de chamada especificada no membro fieldCallBack dessa estrutura é chamada, durante esta operação Ioctl , para cada item na lista. Quando ele é chamado, ele é passado essa estrutura linkList com os membros preenchidos para a entrada de lista junto com o conteúdo do membro Context .

DBG_DUMP_LIST deve ser definido em Opções para informar este Ioctl para iterar na lista.

Context

Especifica um ponteiro que é passado para a função de retorno de chamada no membro CallbackRoutine e para as funções de retorno de chamada no membro fieldCallBack dos membros linkList e Fields .

pBuffer

Especifica um buffer que recebe informações sobre o símbolo. Esse buffer só será usado se o sinalizador DBG_DUMP_COPY_TYPE_DATA estiver definido em Opções. O tamanho desse buffer é especificado em BufferSize.

CallbackRoutine

Especifica uma função de retorno de chamada que é chamada pelo mecanismo. O mecanismo fornece à função de retorno de chamada informações sobre o símbolo e seus membros.

nFields

Especifica o número de entradas na matriz Fields .

Fields

Especifica uma matriz de estruturas de FIELD_INFO que controlam o comportamento dessa operação para membros individuais do símbolo especificado. Consulte FIELD_INFO para obter detalhes.

ModBase

Recebe o local na memória do destino do início do módulo que contém o símbolo.

TypeId

Recebe a ID de tipo do símbolo.

TypeSize

Recebe o tamanho, em bytes, do símbolo na memória do destino.

BufferSize

Especifica o tamanho, em bytes, do buffer pBuffer .

fPointer

Recebe um valor booliano que indica se o símbolo é um ponteiro. fPointer será FALSE se o símbolo não for um ponteiro. Ele será 1 se o símbolo for um ponteiro de 32 bits e 3 se o símbolo for um ponteiro de 64 bits.

fArray

Recebe um valor booliano que indica se o símbolo é uma matriz. fArray será FALSE se o símbolo não for uma matriz e TRUE se for.

fStruct

Recebe um valor booliano que indica se o símbolo é uma estrutura. fStruct será FALSE se o símbolo não for uma estrutura e TRUE se for.

fConstant

Recebe um valor booliano que indica se o símbolo é uma constante. fConstant será FALSE se o símbolo não for uma constante e TRUE se for.

Reserved

Comentários

Os parâmetros para a operação Ioctl IG_DUMP_SYMBOL_INFO são os membros da estrutura SYM_DUMP_PARAM.

Esta operação Ioctl pesquisa as informações do módulo para o símbolo, carregando símbolos de módulo, se possível.

Se nFields for zero e DBG_DUMP_CALL_FOR_EACH estiver definido em Opções, a função de retorno de chamada especificada em CallbackRoutine será chamada para cada campo no símbolo.

Se nFields não for zero e DBG_DUMP_CALL_FOR_EACH for definido em Opções, os retornos de chamada serão feitos apenas para esses campos que correspondem ao membro fName de um dos elementos Fields . Se um campo corresponder a um membro fName e o membro fieldCallBack não for NULL, a função de retorno de chamada em fieldCallBack será chamada; se for NULL, a função de retorno de chamada em CallbackRoutine será chamada.

Os sinalizadores de bits DBG_DUMP_XXX são usados pelo membro Options da estrutura SYM_DUMP_PARAM para controlar o comportamento da operação IoctlIG_DUMP_SYMBOL_INFO.

Os sinalizadores a seguir podem estar presentes.

Sinalizador	Efeito
DBG_DUMP_NO_INDENT	Os membros não são recuados na saída.
DBG_DUMP_NO_OFFSET	Os deslocamentos não são impressos.
DBG_DUMP_VERBOSE	Saída detalhada.
DBG_DUMP_CALL_FOR_EACH	Uma função de retorno de chamada é chamada para cada membro.
DBG_DUMP_LIST	O símbolo é uma entrada em uma lista vinculada e a operação Ioctl IG_DUMP_SYMBOL_INFO iterará nessa lista. A descrição do membro que aponta para o próximo item na lista é especificada pelo membro linkList da estrutura SYM_DUMP_PARAM.
DBG_DUMP_NO_PRINT	Nada é impresso (somente funções de retorno de chamada são chamadas e cópias de dados são executadas).
DBG_DUMP_GET_SIZE_ONLY	A operação Ioctl retorna apenas o tamanho do símbolo; ele não imprimirá informações de membro ou funções de retorno de chamada.
DBG_DUMP_COMPACT_OUT	As linhas novas não são impressas após cada membro.
DBG_DUMP_ARRAY	O símbolo é uma matriz. O número de elementos na matriz é especificado pelo tamanho listLink-> membro da estrutura SYM_DUMP_PARAM.
DBG_DUMP_ADDRESS_OF_FIELD	O valor do agregador é, na verdade, o endereço do membro listLink->fName da estrutura SYM_DUMP_PARAM e não o início do símbolo.
DBG_DUMP_ADDRESS_AT_END	O valor do agregador é, na verdade, o endereço no final do símbolo e não o início do símbolo.
DBG_DUMP_COPY_TYPE_DATA	O valor do símbolo é copiado para o pBuffer membro. Isso só pode ser usado para tipos primitivos, por exemplo, ULONG ou PVOID, que não podem ser usados com estruturas.
DBG_DUMP_READ_PHYSICAL	O valor do símbolo será lido diretamente da memória física do destino.
DBG_DUMP_FUNCTION_FORMAT	Ao formatar um símbolo que tenha um tipo de função, o formato de função será usado, por exemplo, `function(arg1, arg2, ...)`
DBG_DUMP_BLOCK_RECURSE	Recursar por meio de estruturas aninhadas; mas não siga os ponteiros.

Além disso, o resultado da macro DBG_DUMP_RECUR_LEVEL(Level) pode ser adicionado ao conjunto de bits para especificar a profundidade das estruturas a serem recursas. O nível pode ser um número entre 0 e 15.

Os sinalizadores de bits DBG_DUMP_FIELD_XXX são usados pelo membro fOptions da estrutura FIELD_INFO para controlar o comportamento da operação IoctlIG_DUMP_SYMBOL_INFO.

Os sinalizadores a seguir podem estar presentes.

Sinalizador	Efeito
DBG_DUMP_FIELD_CALL_BEFORE_PRINT	A função de retorno de chamada é chamada antes de imprimir o membro.
DBG_DUMP_FIELD_NO_CALLBACK_REQ	Nenhuma função de retorno de chamada é chamada.
DBG_DUMP_FIELD_RECUR_ON_THIS	Submembers do membro são processados.
DBG_DUMP_FIELD_FULL_NAME	fName deve corresponder completamente, em vez de apenas ter um prefixo correspondente, para que o membro seja processado.
DBG_DUMP_FIELD_ARRAY	Imprimir elementos de matriz de um membro da matriz.
DBG_DUMP_FIELD_COPY_FIELD_DATA	O valor do membro é copiado para pBuffer.
DBG_DUMP_FIELD_RETURN_ADDRESS	Durante um retorno de chamada ou quando Ioctl retorna, o FIELD_INFO. O membro do endereço contém o endereço do membro do símbolo. Se nenhum endereço for fornecido para o tipo, FIELD_INFO. O endereço contém o deslocamento total do membro desde o início do tipo.
DBG_DUMP_FIELD_SIZE_IN_BITS	Para um campo de bits, retorne o deslocamento e o tamanho em bits em vez de bytes.
DBG_DUMP_FIELD_NO_PRINT	Não imprima esse membro (somente a função de retorno de chamada é chamada e as cópias de dados são executadas).
DBG_DUMP_FIELD_DEFAULT_STRING DBG_DUMP_FIELD_WCHAR_STRING DBG_DUMP_FIELD_MULTI_STRING DBG_DUMP_FIELD_GUID_STRING	Se o membro for um ponteiro, ele será impresso como uma cadeia de caracteres, cadeia de caracteres ANSI, cadeia de caracteres WCHAR, CADEIA DE CARACTERES MULTI ou GUID.