GetShortField, fonction (wdbgexts.h)

Article
08/08/2023

La fonction GetShortField lit la valeur d’un membre dans une structure si sa taille est inférieure ou égale à 8 octets, ou initialise une structure afin qu’elle puisse être lue ultérieurement. Cette fonction n’est pas destinée à être utilisée directement ; InitTypeRead ou InitTypeReadPhysical et ReadField doivent être utilisés à la place.

Syntaxe

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

Paramètres

[in] TypeAddress

La signification de ce paramètre dépend de la valeur de StoreAddress.

Si StoreAddress est différent de zéro :

Spécifie l’adresse de la structure dans la mémoire de la cible. Cette adresse est utilisée pour les appels suivants lorsque StoreAddress est égal à zéro.

Si StoreAddress est égal à zéro :

TypeAddress est ignoré. La valeur typeAddress du dernier appel lorsque StoreAddress était différent de zéro est utilisée pour spécifier l’adresse de la structure dans la mémoire de la cible.

[in] Name

La signification de ce paramètre dépend de la valeur de StoreAddress.

Si StoreAddress est différent de zéro :

Spécifie le nom du type de la structure dans TypeAddress.

Si StoreAddress est égal à zéro :

Spécifie le nom du membre dans la structure à lire. L’adresse et le type de la structure sont mémorisés à partir d’un appel précédent à cette fonction avec StoreAddress non égal à zéro. Les sous-membres peuvent être spécifiés à l’aide d’un chemin d’accès séparé par un point, par exemple, « myfield.mysubfield ».

[in] StoreAddress

Spécifie le mode de cette fonction.

Si StoreAddress est différent de zéro :

Cette fonction initialise une structure pour la lecture de ses membres. L’adresse et le nom de type de la structure sont mémorisés.

Si la valeur de bits 0x2 est définie dans StoreAddress, l’adresse TypeAddress est considérée comme une adresse physique ; sinon, il est considéré comme une adresse virtuelle.

Si StoreAddress est égal à zéro :

Cette fonction lit un membre à partir d’une structure initialisée précédemment.

Valeur retournée

Code de retour	Description
*Si StoreAddress* est différent de zéro :**	Si la fonction réussit, elle retourne la valeur zéro. Si la fonction échoue parce que l’appelant a passé une valeur zéro comme TypeAddress, elle retourne la valeur MEMORY_READ_ERROR (définie dans Wdbgexts.h). Si la fonction échoue pour une autre raison, elle retourne un code d’erreur IG_DUMP_SYMBOL_INFO.
*Si StoreAddress* est égal à zéro :**	Si la fonction réussit, elle retourne la valeur du champ spécifié dans la structure initialisée précédemment. La structure est celle initialisée dans un appel précédent à GetShortField. Le champ est celui spécifié par le paramètre Name de l’appel actuel à GetShortField. La valeur de retour est convertie en ULONG64. Si la fonction échoue, elle retourne la valeur zéro.

Remarques

Lorsque GetShortField est appelé avec une valeur StoreAddress différente de zéro, il initialise la structure située à l’adresse spécifiée par TypeAddress. Une seule structure peut être initialisée à la fois. Si GetShortField est appelé plusieurs fois avec une valeur StoreAddress différente de zéro, seule la structure spécifiée dans l’appel le plus récent est initialisée. Lorsque GetShortField est appelé avec StoreAddress égal à zéro, il accède à la structure initialisée la plus récente, lit dans cette structure le champ spécifié par Name et retourne la valeur de ce champ.

Cette fonction n’a pas besoin d’être appelée directement. Les macros InitTypeRead et InitTypeReadPhysical appellent cette fonction avec StoreAddress non zéro pour préparer une structure pour la lecture de ses membres. La macro ReadField appelle cette fonction avec StoreAddress (et TypeAddress) égal à zéro, pour lire les membres de la structure.

Notez que cette fonction stocke TypeAddress et Name à l’aide de variables locales statiques et que cette fonction est définie dans WdbgExts.h, le préprocesseur C crée une nouvelle instance de cette fonction pour chaque DLL, et TypeAddress et Name ne seront disponibles que dans un seul fichier source. En d’autres termes, la structure doit être initialisée dans le même fichier source à partir duquel les membres sont lus.

Les macros ReadField et ReadFieldStr lisent un champ dont la taille est inférieure à 8 octets d’une structure initialisée avec InitTypeRead ou InitTypeReadPhysical.

#define ReadField(Field) \
    GetShortField(0, #Field, 0)

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

Paramètres

FieldStr

Valeur de retour

Si cette macro réussit, elle retourne la valeur du champ spécifié dans la structure initialisée précédemment. La structure est celle initialisée dans un appel précédent à InitTypeRead, InitTypeStrRead, InitTypeReadPhysical, InitTypeStrReadPhysical ou GetShortField. Le champ est celui spécifié par le paramètre Field ou FieldStr de ReadField. La valeur de retour est convertie en ULONG64. Si la fonction échoue, elle retourne la valeur zéro.

Le paramètre Field est le nom du membre. Pour ReadField, le préprocesseur C transforme le paramètre en chaîne. Pour ReadFieldStr, Field est censé être une chaîne ASCII. Par exemple, les deux commandes suivantes sont identiques et lisent le même membre à partir d’une structure initialisée précédemment :

ReadField( myField) ;
ReadFieldStr( « myField » ) ;

Les sous-membres peuvent être lus à l’aide d’un chemin d’accès séparé par un point, par exemple, « myField.mySubfield ».

Note Étant donné que ces macros utilisent la fonction GetShortField , elles doivent être appelées à partir du même fichier de code source que les macros qui initialisent la structure pour la lecture. Pour plus d’informations, consultez GetShortField.

Si vous écrivez une extension WdbgExts, incluez wdbgexts.h. Si vous écrivez une extension DbgEng qui appelle cette fonction, incluez wdbgexts.h avant dbgeng.h (pour plus d’informations, consultez Écriture du code d’extension DbgEng ).

La macro InitTypeRead initialise une structure afin que ses membres puissent être lus à l’aide de ReadField.

#define InitTypeRead(
    Addr,
    Type
);

Paramètres

Addr

Spécifie l’adresse de la structure dans la mémoire virtuelle de la cible.

Type

Spécifie le nom du type de la structure. Le préprocesseur C transforme type en chaîne.

Renvoie une valeur

Si cette macro réussit, elle retourne la valeur zéro. En cas d’échec parce que l’appelant a passé une valeur zéro en tant que addr, il retourne la valeur MEMORY_READ_ERROR (définie dans Wdbgexts.h). S’il échoue pour une autre raison, il retourne un code d’erreur IG_DUMP_SYMBOL_INFO.

Les macros InitTypeReadPhysical et InitTypeStrReadPhysical initialisent une structure en mémoire physique afin que ses membres puissent être lus à l’aide de ReadField.

#define InitTypeReadPhysical(
    Addr,
    Type,
    TypeStr
);

Paramètres

Addr

Spécifie l’adresse de la structure dans la mémoire physique de la cible.

Type

Spécifie le nom du type de la structure. Le préprocesseur C transforme type en chaîne.

TypeStr

Spécifie le nom du type de la structure. TypeStr est censé être une chaîne ASCII.

Renvoie une valeur

La macro InitTypeRead initialise une structure afin que ses membres puissent être lus à l’aide de ReadField.

#define InitTypeRead(
    Addr,
    TypeStr
);

Paramètres

Addr

Spécifie l’adresse de la structure dans la mémoire virtuelle de la cible.

Type

Spécifie le nom du type de la structure. TypeStr est censé être une chaîne ASCII.

Renvoie une valeur

Configuration requise

Condition requise	Valeur
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	wdbgexts.h (inclure Wdbgexts.h, Dbgeng.h)

Voir aussi

InitTypeRead

InitTypeReadPhysical

ReadField

Partager via

GetShortField, fonction (wdbgexts.h)

Syntaxe

Paramètres

Si StoreAddress est différent de zéro :

Si StoreAddress est égal à zéro :

Si StoreAddress est différent de zéro :

Si StoreAddress est égal à zéro :

Si StoreAddress est différent de zéro :

Si StoreAddress est égal à zéro :

Valeur retournée

Remarques

Paramètres

Valeur de retour

Configuration requise

Voir aussi

Commentaires

Ressources supplémentaires