共用方式為

GetShortField 函式 (wdbgexts.h)

  • 發行項

如果結構中的成員大小小於或等於8個字節，則 GetShortField 函式會讀取結構中的成員值，或初始化結構，以便稍後進行讀取。 此函式不適合直接使用;應該改用 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 為零：

讓此函式從先前初始化的結構讀取成員。

傳回值

傳回碼 Description
如果 StoreAddress 不是零：
 如果函式成功，它會傳回零值。 如果函式因為呼叫端傳遞零值做為 TypeAddress 而失敗，它會傳回在 Wdbgexts.h 中定義的 MEMORY_READ_ERROR (值) 。 如果函式因任何其他原因而失敗，它會傳回 IG_DUMP_SYMBOL_INFO錯誤碼。
如果 StoreAddress 為零：
 如果函式成功，它會傳回先前初始化結構中指定欄位的值。 結構是在先前對 GetShortField 的呼叫中初始化的結構。 欄位是由目前對 GetShortField 呼叫的 Name 參數所指定的欄位。 傳回值會轉換成 ULONG64。 如果函式失敗，它會傳回零值。

備註

使用非零的 StoreAddress 值呼叫 GetShortField 時，它會初始化位於 TypeAddress 所指定地址的結構。 一次只能初始化一個結構。 如果使用非零 StoreAddress 值多次呼叫 GetShortField，則只會初始化最近呼叫中指定的結構。 當使用 StoreAddress 等於零呼叫 GetShortField 時，它會存取最近初始化的結構、在該結構中讀取 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)

參數

FieldFieldStr

傳回值

如果此宏成功，它會傳回先前初始化結構中指定欄位的值。 結構是在先前呼叫 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