通过

getShortField 函数 (wdbgexts.h)

  • 项目

GetShortField 函数读取结构中成员的值（如果其大小小于或等于 8 个字节），或初始化结构以便稍后可以读取。 此函数不应直接使用;应改用 InitTypeRead 或 InitTypeReadPhysical 和 ReadField 。

语法

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

参数

[in] TypeAddress

此参数的含义取决于 StoreAddress 的值。

如果 StoreAddress 不为零：

指定目标内存中结构的地址。 当 StoreAddress 为零时，此地址用于后续调用。

如果 StoreAddress 为零：

忽略 TypeAddress 。 StoreAddress 为非零时，上次调用的 TypeAddress 值用于指定目标内存中结构的地址。

[in] Name

此参数的含义取决于 StoreAddress 的值。

如果 StoreAddress 不为零：

在 TypeAddress 中指定结构类型的名称。

如果 StoreAddress 为零：

指定要读取的结构中成员的名称。 通过 StoreAddress 不等于零的此函数的上一次调用，会记住结构的地址和类型。 可以使用句点分隔的路径（例如“myfield.mysubfield”）指定子成员。

[in] StoreAddress

指定此函数的模式。

如果 StoreAddress 不为零：

使此函数初始化 结构以读取其成员。 会记住结构的地址和类型名称。

如果在 StoreAddress 中设置0x2位值，则 地址 TypeAddress 被视为物理地址;否则，它被视为虚拟地址。

如果 StoreAddress 为零：

使此函数从以前初始化的 结构中读取成员。

返回值

返回代码 说明
如果 StoreAddress 不为零：
 如果函数成功，则返回值零。 如果函数因调用方将零值作为 TypeAddress 传递而失败，它将返回 Wdbgexts.h) 中定义的值MEMORY_READ_ERROR (。 如果函数因任何其他原因而失败，它将返回 IG_DUMP_SYMBOL_INFO错误代码。
如果 StoreAddress 为 零：
 如果函数成功，它将返回先前初始化的结构中指定字段的值。 结构是在上一次对 GetShortField 的调用中初始化的结构。 字段是由对 GetShortField 的当前调用的 Name 参数指定的字段。 返回值将强制转换为ULONG64。 如果函数失败，它将返回值零。

注解

当使用非零 StoreAddress 值调用 GetShortField 时，它将初始化位于 TypeAddress 指定的地址处的结构。 一次只能初始化一个结构。 如果使用非零 StoreAddress 值多次调用 GetShortField，则仅初始化在最近调用中指定的结构。 当调用 GetShortField 且 StoreAddress 等于零时，它将访问最近初始化的结构，在该结构中读取 Name 指定的字段，并返回该字段的值。

不需要直接调用此函数。 宏 InitTypeRead 和 InitTypeReadPhysical 使用 StoreAddress 非零调用此函数，以准备一个结构来读取其成员。 宏 ReadField 使用 StoreAddress (和 TypeAddress) 等于零调用此函数，以从 结构中读取成员。

请注意， 由于此函数使用静态局部变量存储 TypeAddress 和 Name ，并且此函数是在 WdbgExts.h 中定义的，因此 C 预处理器将为每个 DLL 创建此函数的新实例，并且 TypeAddress 和 Name 仅在单个源文件中可用。 换句话说，结构必须在从中读取成员的同一源文件中初始化。
 
ReadField 和 ReadFieldStr 宏从使用 InitTypeRead 或InitTypeReadPhysical 初始化的结构中读取大小小于 8 字节的字段。 
#define ReadField(Field) \
    GetShortField(0, #Field, 0)

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

参数

FieldStr

返回值

如果此宏成功，它将返回先前初始化的结构中指定字段的值。 结构是在上次调用 InitTypeRead、InitTypeStrRead、InitTypeReadPhysical、InitTypeStrReadPhysical 或 GetShortField 时初始化的结构。 字段是由 ReadField 的 Field 或 FieldStr 参数指定的字段。 返回值将强制转换为ULONG64。 如果函数失败，它将返回值零。

参数 Field 是成员的名称。 对于 ReadField，C 预处理器会将 参数转换为字符串。 对于 ReadFieldStr，Field 应已是 ASCII 字符串。 例如，以下两个命令是相同的，并且从以前初始化的结构中读取相同的成员：

  • ReadField ( myField ) ;
  • ReadFieldStr (“myField”) ;

可以使用句点分隔的路径（例如“myField.mySubfield”）读取子成员。

注意 由于这些宏使用 GetShortField 函数，因此必须从初始化结构以供读取的宏所在的同一源代码文件中调用它们。 有关详细信息，请参阅 GetShortField。
 
如果要编写 WdbgExts 扩展，请包含 wdbgexts.h。 如果要编写调用此函数的 DbgEng 扩展，请在 dbgeng.h 之前包括 wdbgexts.h， (请参阅编写 DbgEng 扩展代码了解) 的详细信息。

InitTypeRead 宏初始化结构，以便可以使用 ReadField 读取其成员。

#define InitTypeRead(
    Addr,
    Type
);

参数

Addr

指定目标虚拟内存中结构的地址。

类型

指定结构类型的名称。 C 预处理器会将 Type 转换为字符串。

返回值

如果此宏成功，则返回值零。 如果由于调用方将零值作为 Addr 传递而失败，它将返回 Wdbgexts.h) 中定义的值MEMORY_READ_ERROR (。 如果由于任何其他原因失败，则返回 IG_DUMP_SYMBOL_INFO错误代码。

InitTypeReadPhysical 和 InitTypeStrReadPhysical 宏初始化物理内存中的结构，以便可以使用 ReadField 读取其成员。

#define InitTypeReadPhysical(
    Addr,
    Type,
    TypeStr
);

参数

Addr

指定目标物理内存中结构的地址。

类型

指定结构类型的名称。 C 预处理器会将 Type 转换为字符串。

TypeStr

指定结构类型的名称。 TypeStr 应为 ASCII 字符串。

返回值

如果此宏成功，则返回值零。 如果由于调用方将零值作为 Addr 传递而失败，它将返回 Wdbgexts.h) 中定义的值MEMORY_READ_ERROR (。 如果由于任何其他原因失败，则返回 IG_DUMP_SYMBOL_INFO错误代码。

InitTypeRead 宏初始化结构，以便可以使用 ReadField 读取其成员。

#define InitTypeRead(
    Addr,
    TypeStr
);

参数

Addr

指定目标虚拟内存中结构的地址。

类型

指定结构类型的名称。 TypeStr 应为 ASCII 字符串。

返回值

如果此宏成功，则返回值零。 如果由于调用方将零值作为 Addr 传递而失败，它将返回 Wdbgexts.h) 中定义的值MEMORY_READ_ERROR (。 如果由于任何其他原因失败，则返回 IG_DUMP_SYMBOL_INFO错误代码。

要求

要求 值
目标平台 桌面
标头 wdbgexts.h (包括 Wdbgexts.h、Dbgeng.h)

另请参阅

InitTypeRead

InitTypeReadPhysical

ReadField