SYM_DUMP_PARAM結構 (wdbgexts.h)

發行項
03/01/2024

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

接收符號的類型識別碼。

TypeSize

接收目標記憶體中符號的大小，以位元組為單位。

BufferSize

指定 pBuffer 緩衝區的大小，以位元組為單位。

fPointer

接收布爾值，指出符號是否為指標。如果符號不是指標，則 fPointer 為 FALSE。如果符號是 32 位指標，則為 1;如果符號是 64 位指標，則為 3。

fArray

接收布爾值，指出符號是否為陣列。如果符號不是陣列，則 fArray 為 FALSE;如果為，則為 TRUE。

fStruct

接收布爾值，指出符號是否為結構。如果符號不是結構，則 fStruct 為 FALSE，如果為，則為 TRUE。

fConstant

接收布爾值，指出符號是否為常數。如果符號不是常數，則 fConstant 為 FALSE;如果為，則為 TRUE。

Reserved

備註

IG_DUMP_SYMBOL_INFO Ioctl 作業的參數是SYM_DUMP_PARAM結構的成員。

此 Ioctl 作業會查閱符號的模組資訊，並盡可能載入模組符號。

如果 nFields 為零，且DBG_DUMP_CALL_FOR_EACH在 Options 中設定，則會針對符號中的每個字段呼叫 CallbackRoutine 中指定的回 呼函式。

如果 nFields 不是零，而且DBG_DUMP_CALL_FOR_EACH是在 Options 中設定，則只會針對符合其中一個 Fields 元素 fName 成員的欄位進行回呼。如果欄位符合 fName 成員，且 fieldCallBack 成員不是 NULL，則會呼叫 fieldCallBack 中的回呼函式;如果是 NULL，則會改為呼叫 CallbackRoutine 中的回調 函式。

DBG_DUMP_XXX 位旗標是由 SYM_DUMP_PARAM 結構的 Options 成員用來控制 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 (Level) 可以新增至位集，以指定要遞歸結構的程度。層級可以是介於 0 到 15 之間的數位。

DBG_DUMP_FIELD_XXX 位旗標是由 FIELD_INFO 結構的 fOptions 成員用來控制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。