Freigeben über

GetShortField-Funktion (wdbgexts.h)

  • Artikel

Die GetShortField-Funktion liest den Wert eines Elements in einer Struktur, wenn seine Größe kleiner oder gleich 8 Byte ist, oder initialisiert eine Struktur, damit sie später gelesen werden kann. Diese Funktion ist nicht für die direkte Verwendung vorgesehen. Stattdessen sollten InitTypeRead oder InitTypeReadPhysical und ReadField verwendet werden.

Syntax

ULONG64 GetShortField(
  [in] IN ULONG64 TypeAddress,
  [in] IN LPCSTR  Name,
  [in] IN USHORT  StoreAddress
);

Parameter

[in] TypeAddress

Die Bedeutung dieses Parameters hängt vom Wert von StoreAddress ab.

Wenn StoreAddress ungleich 0 ist:

Gibt die Adresse der Struktur im Speicher des Ziels an. Diese Adresse wird für nachfolgende Aufrufe verwendet, wenn StoreAddress null ist.

Wenn StoreAddress null ist:

TypeAddress wird ignoriert. Der Wert von TypeAddress aus dem letzten Aufruf, als StoreAddress ungleich 0 war, wird verwendet, um die Adresse der Struktur im Speicher des Ziels anzugeben.

[in] Name

Die Bedeutung dieses Parameters hängt vom Wert von StoreAddress ab.

Wenn StoreAddress ungleich 0 ist:

Gibt den Namen des Typs der Struktur unter TypeAddress an.

Wenn StoreAddress null ist:

Gibt den Namen des zu lesenden Elements in der Struktur an. Die Adresse und der Typ der Struktur werden von einem vorherigen Aufruf dieser Funktion mit StoreAddress nicht gleich 0 gespeichert. Untermembers können mithilfe eines periodentrennten Pfads angegeben werden, z. B. "myfield.mysubfield".

[in] StoreAddress

Gibt den Modus dieser Funktion an.

Wenn StoreAddress ungleich 0 ist:

Bewirkt, dass diese Funktion eine Struktur zum Lesen ihrer Member initialisiert. Die Adresse und der Typname für die Struktur werden gespeichert.

Wenn der Bitwert 0x2 in StoreAddress festgelegt ist, wird die Adresse TypeAddress als physische Adresse betrachtet. Andernfalls wird sie als virtuelle Adresse betrachtet.

Wenn StoreAddress null ist:

Bewirkt, dass diese Funktion einen Member aus einer zuvor initialisierten Struktur liest.

Rückgabewert

Rückgabecode Beschreibung
Wenn StoreAddress ungleich 0 ist:
 Wenn die Funktion erfolgreich ist, gibt sie den Wert 0 (null) zurück. Wenn die Funktion fehlschlägt, weil der Aufrufer einen Nullwert als TypeAddress übergeben hat, gibt sie den Wert MEMORY_READ_ERROR zurück (definiert in Wdbgexts.h). Wenn die Funktion aus einem anderen Grund fehlschlägt, wird ein IG_DUMP_SYMBOL_INFO Fehlercode zurückgegeben.
Wenn StoreAddress null ist:
 Wenn die Funktion erfolgreich ist, gibt sie den Wert des angegebenen Felds in der zuvor initialisierten Struktur zurück. Die -Struktur wurde in einem vorherigen Aufruf von GetShortField initialisiert. Das Feld ist das Feld, das durch den Name-Parameter des aktuellen Aufrufs von GetShortField angegeben wird. Der Rückgabewert wird in ULONG64 umgewandelt. Wenn die Funktion fehlschlägt, gibt sie den Wert 0 zurück.

Hinweise

Wenn GetShortField mit einem StoreAddress-Wert ungleich null aufgerufen wird, initialisiert es die Struktur an der durch TypeAddress angegebenen Adresse. Es kann jeweils nur eine Struktur initialisiert werden. Wenn GetShortField mehrmals mit einem StoreAddress-Wert ungleich null aufgerufen wird, wird nur die im letzten Aufruf angegebene Struktur initialisiert. Wenn GetShortField mit StoreAddress gleich 0 aufgerufen wird, greift es auf die zuletzt initialisierte Struktur zu, liest in dieser Struktur das durch Name angegebene Feld und gibt den Wert dieses Felds zurück.

Diese Funktion muss nicht direkt aufgerufen werden. Die Makros InitTypeRead und InitTypeReadPhysical rufen diese Funktion mit StoreAddress ungleich 0 auf, um eine Struktur für das Lesen ihrer Member vorzubereiten. Das Makro ReadField ruft diese Funktion mit StoreAddress (und TypeAddress) gleich 0 auf, um Member aus der Struktur zu lesen.

Beachten Sie, dass diese Funktion typeAddress und Name mithilfe statischer lokaler Variablen speichert. Da diese Funktion in WdbgExts.h definiert ist, erstellt der C-Präprozessor eine neue instance dieser Funktion für jede DLL, und TypeAddress und Name sind nur in einer einzelnen Quelldatei verfügbar. Anders ausgedrückt: Die Struktur muss in derselben Quelldatei initialisiert werden, aus der die Member gelesen werden.
 
Die Makros ReadField und ReadFieldStr lesen ein Feld, dessen Größe kleiner als 8 Bytes ist, aus einer Struktur, die mit InitTypeRead oder InitTypeReadPhysical initialisiert wurde. 
#define ReadField(Field) \
    GetShortField(0, #Field, 0)

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

Parameter

FieldFieldStr

Rückgabewert

Wenn dieses Makro erfolgreich ist, wird der Wert des angegebenen Felds in der zuvor initialisierten Struktur zurückgegeben. Die -Struktur wurde in einem vorherigen Aufruf von InitTypeRead, InitTypeStrRead, InitTypeReadPhysical, InitTypeStrReadPhysical oder GetShortField initialisiert. Das Feld ist das Feld, das durch den Field - oder FieldStr-Parameter von ReadField angegeben wird. Der Rückgabewert wird in ULONG64 umgewandelt. Wenn die Funktion fehlschlägt, gibt sie den Wert 0 zurück.

Der Parameter Field ist der Name des Members. Für ReadField wandelt der C-Präprozessor den Parameter in eine Zeichenfolge um. Für ReadFieldStr wird erwartet, dass Field bereits eine ASCII-Zeichenfolge ist. Beispielsweise sind die folgenden beiden Befehle identisch und lesen denselben Member aus einer zuvor initialisierten Struktur:

  • ReadField( myField );
  • ReadFieldStr( "myField" );

Untermembers können mithilfe eines periodentrennten Pfads gelesen werden, z. B. "myField.mySubfield".

Hinweis Da diese Makros die GetShortField-Funktion verwenden, müssen sie aus derselben Quellcodedatei wie die Makros aufgerufen werden, die die Struktur zum Lesen initialisieren. Weitere Informationen finden Sie unter GetShortField.
 
Wenn Sie eine WdbgExts-Erweiterung schreiben, schließen Sie wdbgexts.h ein. Wenn Sie eine DbgEng-Erweiterung schreiben, die diese Funktion aufruft, schließen Sie wdbgexts.h vor dbgeng.h ein (ausführliche Informationen finden Sie unter Schreiben von DbgEng-Erweiterungscode ).

Das InitTypeRead-Makro initialisiert eine Struktur, sodass ihre Member mithilfe von ReadField gelesen werden können.

#define InitTypeRead(
    Addr,
    Type
);

Parameter

Addr

Gibt die Adresse der Struktur im virtuellen Speicher des Ziels an.

Typ

Gibt den Namen des Typs der -Struktur an. Der C-Präprozessor wandelt Type in eine Zeichenfolge um.

Rückgabewert

Wenn dieses Makro erfolgreich ist, wird der Wert 0 (null) zurückgegeben. Wenn ein Fehler auftritt, weil der Aufrufer einen Nullwert als Addr übergeben hat, gibt er den Wert MEMORY_READ_ERROR zurück (definiert in Wdbgexts.h). Wenn er aus einem anderen Grund fehlschlägt, wird ein IG_DUMP_SYMBOL_INFO Fehlercode zurückgegeben.

Die Makros InitTypeReadPhysical und InitTypeStrReadPhysical initialisieren eine Struktur im physischen Speicher, sodass ihre Member mit ReadField gelesen werden können.

#define InitTypeReadPhysical(
    Addr,
    Type,
    TypeStr
);

Parameter

Addr

Gibt die Adresse der Struktur im physischen Speicher des Ziels an.

Typ

Gibt den Namen des Typs der -Struktur an. Der C-Präprozessor wandelt Type in eine Zeichenfolge um.

TypeStr

Gibt den Namen des Typs der -Struktur an. TypeStr wird erwartet, dass es sich um eine ASCII-Zeichenfolge handelt.

Rückgabewert

Wenn dieses Makro erfolgreich ist, wird der Wert 0 (null) zurückgegeben. Wenn ein Fehler auftritt, weil der Aufrufer einen Nullwert als Addr übergeben hat, gibt er den Wert MEMORY_READ_ERROR zurück (definiert in Wdbgexts.h). Wenn er aus einem anderen Grund fehlschlägt, wird ein IG_DUMP_SYMBOL_INFO Fehlercode zurückgegeben.

Das InitTypeRead-Makro initialisiert eine Struktur, sodass ihre Member mithilfe von ReadField gelesen werden können.

#define InitTypeRead(
    Addr,
    TypeStr
);

Parameter

Addr

Gibt die Adresse der Struktur im virtuellen Arbeitsspeicher des Ziels an.

Typ

Gibt den Namen des Typs der Struktur an. TypeStr wird erwartet, dass es sich um eine ASCII-Zeichenfolge handelt.

Rückgabewert

Wenn dieses Makro erfolgreich ist, gibt es den Wert 0 zurück. Wenn es fehlschlägt, weil der Aufrufer einen Nullwert als Addr übergeben hat, gibt er den Wert MEMORY_READ_ERROR zurück (definiert in Wdbgexts.h). Wenn es aus einem anderen Grund fehlschlägt, wird ein IG_DUMP_SYMBOL_INFO Fehlercode zurückgegeben.

Anforderungen

Anforderung Wert
Zielplattform Desktop
Kopfzeile wdbgexts.h (einschließlich Wdbgexts.h, Dbgeng.h)

Weitere Informationen

InitTypeRead

InitTypeReadPhysical

ReadField