Partager via

GetShortField, fonction (wdbgexts.h)

  • Article

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 n’est pas égal à 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 de TypeAddress à partir du dernier appel lorsque StoreAddress n’était pas 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 n’est pas égal à zéro :

Spécifie le nom du type de la structure à 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 pas égal à zéro. Les sous-membres peuvent être spécifiés à l’aide d’un chemin séparé par un point, par exemple « myfield.mysubfield ».

[in] StoreAddress

Spécifie le mode de cette fonction.

Si StoreAddress n’est pas égal à zéro :

Provoque l’initialisation d’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 :

Provoque la lecture d’un membre à partir d’une structure précédemment initialisée.

Valeur de retour

Retourner le code Description
Si StoreAddress n’est pas égal à zéro :
 Si la fonction réussit, elle retourne la valeur zéro. Si la fonction échoue, car 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 précédemment initialisée. 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 pour 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, elle 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 Nameet 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.

Remarque, car cette fonction stocke les TypeAddress et Name à l’aide de variables locales statiques et, étant donné 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 sera disponible 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 de

FieldFieldStr

valeur de retour

Si cette macro réussit, elle retourne la valeur du champ spécifié dans la structure précédemment initialisée. La structure est celle initialisée dans un appel précédent à InitTypeRead, InitTypeStrRead, InitTypeReadPhysical, InitTypeStrReadPhysicalou 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, champ devrait déjà être une chaîne ASCII. Par exemple, les deux commandes suivantes sont identiques et lisent le même membre à partir d’une structure précédemment initialisée :

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

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

Remarque É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 (voir Écriture du code d’extension DbgEng pour plus d’informations).

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 la valeur

Si cette macro réussit, elle retourne la valeur zéro. En cas d’échec, car l’appelant a passé une valeur zéro comme addr, il retourne la valeur MEMORY_READ_ERROR (définie dans Wdbgexts.h). Si elle échoue pour une autre raison, elle 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 la valeur

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

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 la valeur

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

Exigences

Exigence Valeur
plateforme cible Bureau
d’en-tête wdbgexts.h (include Wdbgexts.h, Dbgeng.h)

Voir aussi

InitTypeRead

InitTypeReadPhysical

ReadField