Share via

Función GetShortField (wdbgexts.h)

  • Artículo

La función GetShortField lee el valor de un miembro de una estructura si su tamaño es menor o igual que 8 bytes, o inicializa una estructura para que se pueda leer más adelante. Esta función no está pensada para usarse directamente; InitTypeRead o InitTypeReadPhysical y ReadField deben usarse en su lugar.

Sintaxis

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

Parámetros

[in] TypeAddress

El significado de este parámetro depende del valor de StoreAddress.

Si StoreAddress es distinto de cero:

Especifica la dirección de la estructura en la memoria del destino. Esta dirección se usa para las llamadas posteriores cuando StoreAddress es cero.

Si StoreAddress es cero:

TypeAddress se omite. El valor de TypeAddress de la última llamada cuando StoreAddress era distinto de cero se usa para especificar la dirección de la estructura en la memoria del destino.

[in] Name

El significado de este parámetro depende del valor de StoreAddress.

Si StoreAddress es distinto de cero:

Especifica el nombre del tipo de la estructura en TypeAddress.

Si StoreAddress es cero:

Especifica el nombre del miembro de la estructura que se va a leer. La dirección y el tipo de la estructura se recuerdan desde una llamada anterior a esta función con StoreAddress no igual a cero. Los submembrados se pueden especificar mediante una ruta de acceso separada por puntos, por ejemplo, "myfield.mysubfield".

[in] StoreAddress

Especifica el modo de esta función.

Si StoreAddress es distinto de cero:

Hace que esta función inicialice una estructura para leer sus miembros. Se recuerda la dirección y el nombre de tipo de la estructura.

Si el valor de bit 0x2 se establece en StoreAddress, la dirección TypeAddress se considera una dirección física; de lo contrario, se considera una dirección virtual.

Si StoreAddress es cero:

Hace que esta función lea un miembro de una estructura inicializada previamente.

Valor devuelto

Código devuelto Descripción
Si StoreAddress es distinto de cero:
 Si la función se ejecuta correctamente, devuelve el valor cero. Si se produce un error en la función porque el autor de la llamada pasó un valor cero como TypeAddress, devuelve el valor MEMORY_READ_ERROR (definido en Wdbgexts.h). Si se produce un error en la función por cualquier otro motivo, devuelve un código de error IG_DUMP_SYMBOL_INFO.
Si StoreAddress es cero:
 Si la función se realiza correctamente, devuelve el valor del campo especificado en la estructura inicializada anteriormente. La estructura es la inicializada en una llamada anterior a GetShortField. El campo es el especificado por el parámetro Name de la llamada actual a GetShortField. El valor devuelto se convierte en ULONG64. Si se produce un error en la función, devuelve el valor cero.

Comentarios

Cuando se llama a GetShortField con un valor storeAddress distinto de cero, inicializa la estructura ubicada en la dirección especificada por TypeAddress. Solo se puede inicializar una estructura a la vez. Si se llama a GetShortField más de una vez con un valor StoreAddress distinto de cero, solo se inicializa la estructura especificada en la llamada más reciente. Cuando se llama a GetShortField con StoreAddress igual a cero, obtiene acceso a la estructura inicializada más recientemente, lee en esa estructura el campo especificado por Name y devuelve el valor de ese campo.

No es necesario llamar a esta función directamente. Las macros InitTypeRead e InitTypeReadPhysical llaman a esta función con StoreAddress distinto de cero para preparar una estructura para leer sus miembros. La macro ReadField llama a esta función con StoreAddress (y TypeAddress) igual a cero, para leer miembros de la estructura.

Tenga en cuenta que esta función almacena TypeAddress y Name mediante variables locales estáticas y, dado que esta función se define en WdbgExts.h, el preprocesador de C creará una nueva instancia de esta función para cada DLL y TypeAddress y Name solo estarán disponibles dentro de un único archivo de origen. Es decir, la estructura debe inicializarse en el mismo archivo de origen desde el que se leen los miembros.
 
Las macros ReadField y ReadFieldStr leen un campo cuyo tamaño es inferior a 8 bytes de una estructura inicializada con InitTypeRead o InitTypeReadPhysical. 
#define ReadField(Field) \
    GetShortField(0, #Field, 0)

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

Parámetros

FieldStr

Valor devuelto

Si esta macro se realiza correctamente, devuelve el valor del campo especificado en la estructura inicializada anteriormente. La estructura es la inicializada en una llamada anterior a InitTypeRead, InitTypeStrRead, InitTypeReadPhysical, InitTypeStrReadPhysical o GetShortField. El campo es el especificado por el parámetro Field o FieldStr de ReadField. El valor devuelto se convierte en ULONG64. Si se produce un error en la función, devuelve el valor cero.

El parámetro Field es el nombre del miembro. Para ReadField, el preprocesador de C convertirá el parámetro en una cadena. Para ReadFieldStr, se espera que Field ya sea una cadena ASCII. Por ejemplo, los dos comandos siguientes son idénticos y leen el mismo miembro de una estructura inicializada anteriormente:

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

Los submembrados se pueden leer mediante una ruta de acceso separada por puntos, por ejemplo, "myField.mySubfield".

Nota Dado que estas macros usan la función GetShortField , deben llamarse desde el mismo archivo de código fuente que las macros que inicializan la estructura para su lectura. Para obtener más información, consulte GetShortField.
 
Si va a escribir una extensión WdbgExts, incluya wdbgexts.h. Si va a escribir una extensión DbgEng que llama a esta función, incluya wdbgexts.h antes de dbgeng.h (consulte Escribir código de extensión de DbgEng para obtener más información).

La macro InitTypeRead inicializa una estructura para que sus miembros se puedan leer mediante ReadField.

#define InitTypeRead(
    Addr,
    Type
);

Parámetros

Addr

Especifica la dirección de la estructura en la memoria virtual del destino.

Tipo

Especifica el nombre del tipo de la estructura. El preprocesador C convertirá Type en una cadena.

Valor devuelto

Si esta macro se realiza correctamente, devuelve el valor cero. Si se produce un error porque el autor de la llamada pasó un valor cero como Addr, devuelve el valor MEMORY_READ_ERROR (definido en Wdbgexts.h). Si se produce un error por cualquier otro motivo, devuelve un código de error IG_DUMP_SYMBOL_INFO.

Las macros InitTypeReadPhysical e InitTypeStrReadPhysical inicializan una estructura en memoria física para que sus miembros se puedan leer mediante ReadField.

#define InitTypeReadPhysical(
    Addr,
    Type,
    TypeStr
);

Parámetros

Addr

Especifica la dirección de la estructura en la memoria física del destino.

Tipo

Especifica el nombre del tipo de la estructura. El preprocesador C convertirá Type en una cadena.

TypeStr

Especifica el nombre del tipo de la estructura. Se espera que TypeStr sea una cadena ASCII.

Valor devuelto

Si esta macro se realiza correctamente, devuelve el valor cero. Si se produce un error porque el autor de la llamada pasó un valor cero como Addr, devuelve el valor MEMORY_READ_ERROR (definido en Wdbgexts.h). Si se produce un error por cualquier otro motivo, devuelve un código de error IG_DUMP_SYMBOL_INFO.

La macro InitTypeRead inicializa una estructura para que sus miembros se puedan leer mediante ReadField.

#define InitTypeRead(
    Addr,
    TypeStr
);

Parámetros

Addr

Especifica la dirección de la estructura en la memoria virtual del destino.

Tipo

Especifica el nombre del tipo de la estructura. Se espera que TypeStr sea una cadena ASCII.

Valor devuelto

Si esta macro se realiza correctamente, devuelve el valor cero. Si se produce un error porque el autor de la llamada pasó un valor cero como Addr, devuelve el valor MEMORY_READ_ERROR (definido en Wdbgexts.h). Si se produce un error por cualquier otro motivo, devuelve un código de error de IG_DUMP_SYMBOL_INFO.

Requisitos

Requisito Value
Plataforma de destino Escritorio
Encabezado wdbgexts.h (include Wdbgexts.h, Dbgeng.h)

Consulte también

InitTypeRead

InitTypeReadPhysical

ReadField