共用方式為

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 ，它會傳回值MEMORY_READ_ERROR （定義於 Wdbgexts.h 中）。 如果函式因任何其他原因而失敗，它會傳回 IG_DUMP_SYMBOL_INFO 錯誤碼。
如果 storeAddress 為零：
 如果函式成功，它會傳回先前初始化結構中指定欄位的值。 結構是在先前呼叫 GetShortField中初始化的 。 欄位是由目前呼叫 GetShortField的 Name 參數所指定。 傳回值會轉換成ULONG64。 如果函式失敗，它會傳回零值。

言論

使用非零 StoreAddress 值呼叫 getShortField 時，它會初始化位於 TypeAddress 所指定地址的結構。 一次只能初始化一個結構。 如果 GetShortField 多次使用非零 StoreAddress 值呼叫，則只會初始化最近呼叫中指定的結構。 當 呼叫 getShortField 時，StoreAddress 等於零，它會存取最近初始化的結構、讀取 Name所指定的欄位，並傳回該字段的值。

不需要直接呼叫此函式。 巨集 InitTypeRead 和 InitTypeReadPhysical 使用 StoreAddress 非零來準備讀取其成員的結構。 巨集 ReadField 會呼叫這個函式，StoreAddress （和 TypeAddress）等於零，以從 結構讀取成員。

Note，因為此函式會使用靜態局部變數來儲存 TypeAddress 和 Name， 而且由於此函式是在 WdbgExts.h 中定義，因此 C 前置處理器會為每個 DLL 建立此函式的新實例，而且 TypeAddress 和 Name 只能在單一來源檔案中使用。 換句話說，結構必須在讀取成員的來源相同原始程序檔中初始化。
 
ReadField 和 ReadFieldStr 巨集會讀取一個字段，其大小小於 8 個字節，而從 以 initTypeRead 或 InitTypeReadPhysical初始化的 結構。 
#define ReadField(Field) \
    GetShortField(0, #Field, 0)

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

參數

fieldFieldStr

傳回值

如果這個巨集成功，它會傳回先前初始化結構中指定欄位的值。 結構是在先前呼叫 InitTypeRead、InitTypeStrRead、InitTypeReadPhysical、InitTypeStrReadPhysical或 GetShortField中初始化的結構。 欄位是由 readField 的 Field 或 FieldStr 參數所指定的欄位。 傳回值會轉換成ULONG64。 如果函式失敗，它會傳回零值。

field 參數 為成員的名稱。 針對 ReadField，C 前置處理器會將 參數轉換成字串。 針對 ReadFieldStr，Field 必須是 ASCII 字串。 例如，下列兩個命令相同，並從先前初始化的結構讀取相同的成員：

  • ReadField（myField ）：
  • ReadFieldStr（ “myField” ] ;

您可以使用句點分隔路徑來讀取子成員，例如 「myField.mySubfield」。。

Note 因為這些巨集會使用 getShortField 函式，所以必須從與初始化結構以供讀取的巨集相同的原始程式碼檔呼叫它們。 如需詳細資訊，請參閱 GetShortField。
 
如果您要撰寫 WdbgExts 延伸模組，請 wdbgexts.h。 如果您要撰寫呼叫此函式的 DbgEng 延伸模組，請在 dbgeng.h 之前包含 wdbgexts.h （如需詳細資訊，請參閱 撰寫 DbgEng 延伸模組程式代碼）。

InitTypeRead 巨集會初始化 結構，以便使用 readField 讀取其成員。

#define InitTypeRead(
    Addr,
    Type
);

參數

Addr

指定目標虛擬記憶體中 結構的位址。

類型

指定結構類型的名稱。 C 前置處理器會將 Type 轉換成字串。

傳回值

如果這個巨集成功，則會傳回值零。 如果失敗，因為呼叫端以 Addr傳遞零值，則會傳回值MEMORY_READ_ERROR （定義於 Wdbgexts.h 中）。 如果因為任何其他原因而失敗，它會傳回 IG_DUMP_SYMBOL_INFO 錯誤碼。

InitTypeReadPhysical 和 InitTypeStrReadPhysical 巨集會初始化物理記憶體中的結構，讓其成員可以使用 readField 讀取。

#define InitTypeReadPhysical(
    Addr,
    Type,
    TypeStr
);

參數

Addr

指定目標物理記憶體中結構的位址。

類型

指定結構類型的名稱。 C 前置處理器會將 Type 轉換成字串。

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 （include Wdbgexts.h， Dbgeng.h）

另請參閱

InitTypeRead

InitTypeReadPhysical

ReadField