Função GetShortField (wdbgexts.h)

Artigo
02/29/2024

A função GetShortField lê o valor de um membro em uma estrutura se seu tamanho for menor ou igual a 8 bytes ou inicializará uma estrutura para que possa ser lida posteriormente. Essa função não se destina a ser usada diretamente; InitTypeRead ou InitTypeReadPhysical e ReadField devem ser usados.

Sintaxe

ULONG64 GetShortField(
  [in] IN ULONG64 TypeAddress,
  [in] IN LPCSTR  Name,
  [in] IN USHORT  StoreAddress
);

Parâmetros

[in] TypeAddress

O significado desse parâmetro depende do valor de StoreAddress.

Se StoreAddress não for zero:

Especifica o endereço da estrutura na memória do destino. Esse endereço é usado para chamadas subsequentes quando StoreAddress é zero.

Se StoreAddress for zero:

TypeAddress é ignorado. O valor de TypeAddress da última chamada quando StoreAddress não era zero é usado para especificar o endereço da estrutura na memória do destino.

[in] Name

O significado desse parâmetro depende do valor de StoreAddress.

Se StoreAddress não for zero:

Especifica o nome do tipo da estrutura em TypeAddress.

Se StoreAddress for zero:

Especifica o nome do membro na estrutura a ser lida. O endereço e o tipo da estrutura são lembrados de uma chamada anterior para essa função com StoreAddress não igual a zero. Submembers podem ser especificados usando um caminho separado por período, por exemplo, "myfield.mysubfield".

[in] StoreAddress

Especifica o modo dessa função.

Se StoreAddress não for zero:

Faz com que essa função inicialize uma estrutura para ler seus membros. O endereço e o nome do tipo da estrutura são lembrados.

Se o valor do bit 0x2 for definido em StoreAddress, o endereço TypeAddress será considerado um endereço físico; caso contrário, ele é considerado um endereço virtual.

Se StoreAddress for zero:

Faz com que essa função leia um membro de uma estrutura inicializada anteriormente.

Retornar valor

Código de retorno	Descrição
*Se StoreAddress* não for zero:**	Se a função for bem-sucedida, ela retornará o valor zero. Se a função falhar porque o chamador passou um valor zero como TypeAddress, ele retornará o valor MEMORY_READ_ERROR (definido em Wdbgexts.h). Se a função falhar por qualquer outro motivo, ela retornará um código de erro IG_DUMP_SYMBOL_INFO.
*Se StoreAddress* for zero:**	Se a função for bem-sucedida, ela retornará o valor do campo especificado na estrutura inicializada anteriormente. A estrutura é a inicializada em uma chamada anterior para GetShortField. O campo é aquele especificado pelo parâmetro Name da chamada atual para GetShortField. O valor retornado é convertido em ULONG64. Se a função falhar, ela retornará o valor zero.

Comentários

Quando GetShortField é chamado com um valor StoreAddress diferente de zero, ele inicializa a estrutura localizada no endereço especificado por TypeAddress. Somente uma estrutura pode ser inicializada por vez. Se GetShortField for chamado mais de uma vez com um valor StoreAddress diferente de zero, somente a estrutura especificada na chamada mais recente será inicializada. Quando GetShortField é chamado com StoreAddress igual a zero, ele acessa a estrutura inicializada mais recentemente, lê nessa estrutura o campo especificado por Name e retorna o valor desse campo.

Essa função não precisa ser chamada diretamente. As macros InitTypeRead e InitTypeReadPhysical chamam essa função com StoreAddress diferente de zero para preparar uma estrutura para ler seus membros. A macro ReadField chama essa função com StoreAddress (e TypeAddress) igual a zero para ler membros da estrutura.

Observe que essa função armazena o TypeAddress e o Name usando variáveis locais estáticas e, como essa função é definida em WdbgExts.h, o pré-processador C criará uma nova instância dessa função para cada DLL e TypeAddress e Name só estarão disponíveis em um único arquivo de origem. Em outras palavras, a estrutura deve ser inicializada no mesmo arquivo de origem do qual os membros são lidos.

As macros ReadField e ReadFieldStr leem um campo cujo tamanho é inferior a 8 bytes de uma estrutura inicializada com InitTypeRead ou InitTypeReadPhysical.

#define ReadField(Field) \
    GetShortField(0, #Field, 0)

#define ReadFieldStr(FieldStr) \
    GetShortField(0, FieldStr, 0)

Parâmetros

FieldFieldStr

Valor retornado

Se essa macro for bem-sucedida, ela retornará o valor do campo especificado na estrutura inicializada anteriormente. A estrutura é a inicializada em uma chamada anterior para InitTypeRead, InitTypeStrRead, InitTypeReadPhysical, InitTypeStrReadPhysical ou GetShortField. O campo é aquele especificado pelo parâmetro Field ou FieldStr de ReadField. O valor retornado é convertido em ULONG64. Se a função falhar, ela retornará o valor zero.

O parâmetro Field é o nome do membro. Para ReadField, o pré-processador C transformará o parâmetro em uma cadeia de caracteres. Para ReadFieldStr, espera-se que Field já seja uma cadeia de caracteres ASCII. Por exemplo, os dois comandos a seguir são idênticos e leem o mesmo membro de uma estrutura inicializada anteriormente:

ReadField( myField );
ReadFieldStr( "myField" );

Os submembers podem ser lidos usando um caminho separado por período, por exemplo, "myField.mySubfield".

Nota Como essas macros usam a função GetShortField , elas devem ser chamadas do mesmo arquivo de código-fonte que as macros que inicializam a estrutura para leitura. Para obter mais detalhes, consulte GetShortField.

Se você estiver escrevendo uma extensão WdbgExts, inclua wdbgexts.h. Se você estiver escrevendo uma extensão DbgEng que chama essa função, inclua wdbgexts.h antes de dbgeng.h (consulte Escrevendo código de extensão DbgEng para obter detalhes).

A macro InitTypeRead inicializa uma estrutura para que seus membros possam ser lidos usando ReadField.

#define InitTypeRead(
    Addr,
    Type
);

Parâmetros

Addr

Especifica o endereço da estrutura na memória virtual do destino.

Tipo

Especifica o nome do tipo da estrutura. O pré-processador C transformará Type em uma cadeia de caracteres.

Retorna um valor

Se essa macro for bem-sucedida, ela retornará o valor zero. Se falhar porque o chamador passou um valor zero como Addr, ele retornará o valor MEMORY_READ_ERROR (definido em Wdbgexts.h). Se falhar por qualquer outro motivo, ele retornará um código de erro IG_DUMP_SYMBOL_INFO.

As macros InitTypeReadPhysical e InitTypeStrReadPhysical inicializam uma estrutura na memória física para que seus membros possam ser lidos usando ReadField.

#define InitTypeReadPhysical(
    Addr,
    Type,
    TypeStr
);

Parâmetros

Addr

Especifica o endereço da estrutura na memória física do destino.

Tipo

Especifica o nome do tipo da estrutura. O pré-processador C transformará Type em uma cadeia de caracteres.

TypeStr

Especifica o nome do tipo da estrutura. Espera-se que TypeStr seja uma cadeia de caracteres ASCII.

Retorna um valor

A macro InitTypeRead inicializa uma estrutura para que seus membros possam ser lidos usando ReadField.

#define InitTypeRead(
    Addr,
    TypeStr
);

Parâmetros

Addr

Especifica o endereço da estrutura na memória virtual do destino.

Tipo

Especifica o nome do tipo da estrutura. Espera-se que TypeStr seja uma cadeia de caracteres ASCII.

Retorna um valor

Requisitos

Requisito	Valor
Plataforma de Destino	Área de Trabalho
Cabeçalho	wdbgexts.h (inclua Wdbgexts.h, Dbgeng.h)

Confira também

InitTypeRead

InitTypeReadPhysical

ReadField

Função GetShortField (wdbgexts.h)

Sintaxe

Parâmetros

Se StoreAddress não for zero:

Se StoreAddress for zero:

Se StoreAddress não for zero:

Se StoreAddress for zero:

Se StoreAddress não for zero:

Se StoreAddress for zero:

Retornar valor

Comentários

Parâmetros

Valor retornado

Requisitos

Confira também

Comentários

Comentários

Recursos adicionais