SYM_DUMP_PARAM 结构 (wdbgexts.h)

项目
08/08/2023

IG_DUMP_SYMBOL_INFO Ioctl 操作提供有关符号类型的信息。在将 IoctlType 设置为 IG_DUMP_SYMBOL_INFO 的情况下调用 Ioctl 时， IpvData 应包含 SYM_DUMP_PARAM 结构的实例。

语法

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;

成员

size

指定此结构的大小（以字节为单位）。它应设置为 sizeof(SYM_DUMP_PARAM)。

sName

指定要查找的符号的名称。

Options

指定用于确定此 Ioctl 操作行为的标志。有关这些标志的说明，请参阅备注。

addr

指定符号的地址。

listLink

指定包含链接列表中的下一项的字段。如果符号是链接列表中的条目，则此 Ioctl 操作可以使用此处指定为指向列表中下一项的指针的字段循环访问列表中的项。此结构的类型 FIELD_INFO。

在此 Ioctl 操作期间，将为此列表中的每个项调用在此结构的 fieldCallBack 成员中指定的回调函数。调用它时，将传递此 linkList 结构，其中包含为列表条目填充的成员以及 Context 成员的内容。

应在 “选项” 中设置DBG_DUMP_LIST，以告知此 Ioctl 循环访问列表。

Context

指定一个指针，该指针传递到 CallbackRoutine 成员中的回调函数和 linkList 和 Fields 成员的 fieldCallBack 成员中的回调函数。

pBuffer

指定接收符号相关信息的缓冲区。仅当在 “选项”中设置了DBG_DUMP_COPY_TYPE_DATA标志时，才使用此缓冲区。缓冲区的大小在 BufferSize 中指定。

CallbackRoutine

指定由引擎调用的回调函数。引擎为回调函数提供符号及其成员的相关信息。

nFields

指定 Fields 数组中的条目数。

Fields

指定 FIELD_INFO 结构的数组，这些结构控制指定符号的各个成员的此操作的行为。有关详细信息，请参阅FIELD_INFO。

ModBase

接收包含符号的模块开头的目标内存中的位置。

TypeId

接收符号的类型 ID。

TypeSize

接收目标内存中符号的大小（以字节为单位）。

BufferSize

指定 pBuffer 缓冲区的大小（以字节为单位）。

fPointer

接收一个布尔值，该值指示符号是否为指针。如果符号不是指针，fPointer 为 FALSE。如果符号是 32 位指针，则为 1;如果符号为 64 位指针，则为 3。

fArray

接收一个布尔值，该值指示符号是否为数组。如果符号不是数组，则 fArray 为 FALSE;如果为 TRUE，则为 TRUE。

fStruct

接收一个布尔值，该值指示符号是否为结构。如果符号不是结构，fStruct 为 FALSE;如果为 TRUE，则为 TRUE。

fConstant

接收一个布尔值，该值指示符号是否为常量。如果符号不是常量，则 fConstant 为 FALSE;如果为 TRUE，则为 TRUE。

Reserved

注解

IG_DUMP_SYMBOL_INFO Ioctl 操作的参数是SYM_DUMP_PARAM结构的成员。

此 Ioctl 操作查找符号的模块信息，并加载模块符号（如果可能）。

如果 nFields 为零并在 Options 中设置了DBG_DUMP_CALL_FOR_EACH，则会为符号中的每个字段调用 CallbackRoutine 中指定的回调函数。

如果 nFields 为非零且在 Options 中设置了DBG_DUMP_CALL_FOR_EACH，则仅针对与其中一个 Fields 元素的 fName 成员匹配的字段进行回调。如果字段与 fName 成员匹配，而 fieldCallBack 成员不为 NULL，则调用 fieldCallBack 中的回调函数;如果为 NULL，则改为调用 CallbackRoutine 中的回调函数。

SYM_DUMP_PARAM 结构的 Options 成员使用 DBG_DUMP_XXX 位标志来控制IG_DUMP_SYMBOL_INFOIoctl 操作的行为。

可以存在以下标志。

标志	效果
DBG_DUMP_NO_INDENT	成员不会在输出中缩进。
DBG_DUMP_NO_OFFSET	不打印偏移量。
DBG_DUMP_VERBOSE	详细输出。
DBG_DUMP_CALL_FOR_EACH	为每个成员调用回调函数。
DBG_DUMP_LIST	符号是链接列表中的条目，IG_DUMP_SYMBOL_INFO Ioctl 操作将循环访问此列表。指向列表中下一项的成员的说明由 SYM_DUMP_PARAM 结构的 linkList 成员指定。
DBG_DUMP_NO_PRINT	(只调用回调函数并) 执行数据复制，则不打印任何内容。
DBG_DUMP_GET_SIZE_ONLY	Ioctl 操作仅返回符号的大小;它不会打印成员信息或调用回调函数。
DBG_DUMP_COMPACT_OUT	不在每个成员之后打印换行符。
DBG_DUMP_ARRAY	符号是数组。数组中的元素数由SYM_DUMP_PARAM结构的成员 listLink->大小指定。
DBG_DUMP_ADDRESS_OF_FIELD	addr 的值实际上是SYM_DUMP_PARAM结构的成员 listLink->fName 的地址，而不是符号的开头。
DBG_DUMP_ADDRESS_AT_END	addr 的值实际上是符号末尾的地址，而不是符号的开头。
DBG_DUMP_COPY_TYPE_DATA	符号的值将复制到成员 pBuffer 中。这只能用于基元类型（例如 ULONG 或 PVOID），它不能与结构一起使用。
DBG_DUMP_READ_PHYSICAL	符号的值将直接从目标的物理内存中读取。
DBG_DUMP_FUNCTION_FORMAT	设置具有函数类型的符号的格式时，将使用函数格式，例如， `function(arg1, arg2, ...)`
DBG_DUMP_BLOCK_RECURSE	通过嵌套结构递归;但不遵循指针。

此外，可以将宏DBG_DUMP_RECUR_LEVEL (级别) 的结果添加到位集中，以指定要递归结构的深度。级别可以是介于 0 和 15 之间的数字。

FIELD_INFO 结构的fOptions 成员使用 DBG_DUMP_FIELD_XXX 位标志来控制IG_DUMP_SYMBOL_INFOIoctl 操作的行为。

可以存在以下标志。

标志	效果
DBG_DUMP_FIELD_CALL_BEFORE_PRINT	回调函数在打印成员之前调用。
DBG_DUMP_FIELD_NO_CALLBACK_REQ	不调用回调函数。
DBG_DUMP_FIELD_RECUR_ON_THIS	处理成员的子成员。
DBG_DUMP_FIELD_FULL_NAME	fName 必须完全匹配，而不是仅具有匹配的前缀，才能处理成员。
DBG_DUMP_FIELD_ARRAY	打印数组成员的数组元素。
DBG_DUMP_FIELD_COPY_FIELD_DATA	成员的值将复制到 pBuffer 中。
DBG_DUMP_FIELD_RETURN_ADDRESS	在回调期间或 Ioctl 返回时，FIELD_INFO。address 成员包含符号成员的地址。如果未为类型提供地址，FIELD_INFO。address 包含成员与类型开头的总偏移量。
DBG_DUMP_FIELD_SIZE_IN_BITS	对于位字段，返回偏移量和大小（以位而不是字节为单位）。
DBG_DUMP_FIELD_NO_PRINT	请勿打印此成员 (仅调用回调函数并) 执行数据复制。
DBG_DUMP_FIELD_DEFAULT_STRING DBG_DUMP_FIELD_WCHAR_STRING DBG_DUMP_FIELD_MULTI_STRING DBG_DUMP_FIELD_GUID_STRING	如果成员是指针，则将其打印为字符串、ANSI 字符串、WCHAR 字符串、MULTI 字符串或 GUID。