GetShortField 函数 (wdbgexts.h)

GetShortField 函数读取结构中成员的值(如果其大小小于或等于 8 个字节)或初始化结构,以便稍后可以读取。 此函数不应直接使用;应改用 InitTypeReadInitTypeReadPhysicalReadField

语法

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 不等于零。 可以使用句点分隔的路径指定子members,例如“myfield.mysubfield”。

[in] StoreAddress

指定此函数的模式。

如果 StoreAddress 为非零:

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

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

如果 StoreAddress 为零:

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

返回值

返回代码 描述
如果 StoreAddress 为非零:
如果函数成功,则返回值零。 如果函数失败,因为调用方 TypeAddress传递了零个值,则返回值MEMORY_READ_ERROR(在 Wdbgexts.h 中定义)。 如果函数因任何其他原因而失败,它将返回 IG_DUMP_SYMBOL_INFO 错误代码
如果 StoreAddress 为零:
如果函数成功,它将返回先前初始化的结构中指定字段的值。 结构是在上一次调用 GetShortField中初始化的结构。 该字段是由当前调用 GetShortFieldName 参数指定的字段。 返回值转换为ULONG64。 如果函数失败,则返回值零。

言论

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

不需要直接调用此函数。 宏 InitTypeReadInitTypeReadPhysical 调用此函数,StoreAddress 非零来准备用于读取其成员的结构。 宏 ReadField 调用此函数,StoreAddressTypeAddress)等于零,以便从结构中读取成员。

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

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

参数

FieldFieldStr

返回值

如果此宏成功,它将返回先前初始化的结构中指定字段的值。 该结构是在上一次调用 InitTypeReadInitTypeStrReadInitTypeReadPhysicalInitTypeStrReadPhysicalGetShortField中初始化的结构。 该字段是由 ReadFieldFieldFieldStr 参数指定的字段。 返回值转换为ULONG64。 如果函数失败,则返回值零。

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

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

可以使用句点分隔的路径(例如“myField.mySubfield”)读取子member。

Note 由于这些宏使用 GetShortField 函数,因此必须从初始化读取结构的宏调用它们。 有关详细信息,请参阅 GetShortField
 
如果要编写 WdbgExts 扩展,请包括 wdbgexts.h。 如果要编写调用此函数的 DbgEng 扩展,请在 dbgeng.h 之前包括 wdbgexts.h(有关详细信息,请参阅 编写 DbgEng 扩展代码)。

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

#define InitTypeRead(
    Addr,
    Type
);

参数

Addr

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

类型

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

返回值

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

InitTypeReadPhysicalInitTypeStrReadPhysical 宏在物理内存中初始化结构,以便可以使用 ReadField读取其成员。

#define InitTypeReadPhysical(
    Addr,
    Type,
    TypeStr
);

参数

Addr

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

类型

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

TypeStr

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

返回值

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

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

#define InitTypeRead(
    Addr,
    TypeStr
);

参数

Addr

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

类型

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

返回值

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

要求

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

另请参阅

InitTypeRead

InitTypeReadPhysical

ReadField