Condividi tramite

Funzione GetShortField (wdbgexts.h)

  • Articolo

La funzione GetShortField legge il valore di un membro in una struttura se la dimensione è minore o uguale a 8 byte oppure inizializza una struttura in modo che possa essere letta in un secondo momento. Questa funzione non deve essere usata direttamente; initTypeRead o initTypeReadPhysical e è consigliabile usare ReadField.

Sintassi

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

Parametri

[in] TypeAddress

Il significato di questo parametro dipende dal valore di StoreAddress.

Se StoreAddress è diverso da zero:

Specifica l'indirizzo della struttura nella memoria della destinazione. Questo indirizzo viene usato per le chiamate successive quando StoreAddress è zero.

Se StoreAddress è zero:

TypeAddress viene ignorato. Il valore di TypeAddress dall'ultima chiamata quando StoreAddress era diverso da zero viene usato per specificare l'indirizzo della struttura nella memoria della destinazione.

[in] Name

Il significato di questo parametro dipende dal valore di StoreAddress.

Se StoreAddress è diverso da zero:

Specifica il nome del tipo della struttura in TypeAddress.

Se StoreAddress è zero:

Specifica il nome del membro nella struttura da leggere. L'indirizzo e il tipo della struttura vengono memorizzati da una chiamata precedente a questa funzione con StoreAddress non uguale a zero. I membri secondari possono essere specificati usando un percorso separato da punti, ad esempio "myfield.mysubfield".

[in] StoreAddress

Specifica la modalità di questa funzione.

Se StoreAddress è diverso da zero:

Fa sì che questa funzione inizializzi una struttura per la lettura dei relativi membri. Viene memorizzato l'indirizzo e il nome del tipo per la struttura.

Se il valore di bit 0x2 è impostato in StoreAddress, l'indirizzo TypeAddress viene considerato un indirizzo fisico; in caso contrario, viene considerato un indirizzo virtuale.

Se StoreAddress è zero:

Fa sì che questa funzione legga un membro da una struttura inizializzata in precedenza.

Valore restituito

Codice restituito Descrizione
Se StoreAddress è diverso da zero:
 Se la funzione ha esito positivo, restituisce il valore zero. Se la funzione ha esito negativo perché il chiamante ha passato un valore zero come TypeAddress, restituisce il valore MEMORY_READ_ERROR (definito in Wdbgexts.h). Se la funzione ha esito negativo per qualsiasi altro motivo, restituisce un codice di errore IG_DUMP_SYMBOL_INFO.
Se StoreAddress è zero:
 Se la funzione ha esito positivo, restituisce il valore del campo specificato nella struttura inizializzata in precedenza. La struttura è quella inizializzata in una chiamata precedente a GetShortField. Il campo è quello specificato dal parametro Name della chiamata corrente a GetShortField. Viene eseguito il cast del valore restituito per ULONG64. Se la funzione ha esito negativo, restituisce il valore zero.

Osservazioni

Quando GetShortField viene chiamato con un valore StoreAddress diverso da zero, inizializza la struttura in corrispondenza dell'indirizzo specificato da TypeAddress. È possibile inizializzare una sola struttura alla volta. Se GetShortField viene chiamato più volte con un valore StoreAddress diverso da zero, viene inizializzata solo la struttura specificata nella chiamata più recente. Quando GetShortField viene chiamato con StoreAddress uguale a zero, accede alla struttura inizializzata più di recente, legge in tale struttura il campo specificato da Namee restituisce il valore di tale campo.

Questa funzione non deve essere chiamata direttamente. Le macro InitTypeRead e InitTypeReadPhysical chiamare questa funzione con StoreAddress diverso da zero per preparare una struttura per la lettura dei relativi membri. La macro ReadField chiama questa funzione con StoreAddress (e TypeAddress) uguale a zero per leggere i membri dalla struttura.

Nota perché questa funzione archivia il TypeAddress e Name usando variabili locali statiche e poiché questa funzione è definita in WdbgExts.h, il preprocessore C creerà una nuova istanza di questa funzione per ogni DLL e TypeAddress e Name saranno disponibili solo all'interno di un singolo file di origine. In altre parole, la struttura deve essere inizializzata nello stesso file di origine da cui vengono letti i membri.
 
Le macro ReadField e ReadFieldStr leggono un campo la cui dimensione è inferiore a 8 byte da una struttura inizializzata con InitTypeRead o InitTypeReadPhysical. 
#define ReadField(Field) \
    GetShortField(0, #Field, 0)

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

parametri

campoFieldStr

valore restituito

Se la macro ha esito positivo, restituisce il valore del campo specificato nella struttura inizializzata in precedenza. La struttura è quella inizializzata in una chiamata precedente a InitTypeRead, InitTypeStrRead, InitTypeReadPhysical, InitTypeStrReadPhysicalo GetShortField. Il campo è quello specificato dal parametro Field o FieldStr di ReadField. Viene eseguito il cast del valore restituito per ULONG64. Se la funzione ha esito negativo, restituisce il valore zero.

Il parametro Field è il nome del membro. Per ReadField, il preprocessore C trasformerà il parametro in una stringa. Per ReadFieldStr, Field deve essere già una stringa ASCII. Ad esempio, i due comandi seguenti sono identici e leggono lo stesso membro da una struttura inizializzata in precedenza:

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

I membri secondari possono essere letti usando un percorso separato da punti, ad esempio "myField.mySubfield".

Nota Poiché queste macro utilizzano la funzione GetShortField, devono essere chiamate dallo stesso file di codice sorgente delle macro che inizializzano la struttura per la lettura. Per altri dettagli, vedere GetShortField.
 
Se si scrive un'estensione WdbgExts, includere wdbgexts.h. Se si sta scrivendo un'estensione DbgEng che chiama questa funzione, includere wdbgexts.h prima di dbgeng.h (vedere Scrittura del codice dell'estensione DbgEng per informazioni dettagliate).

La macro InitTypeRead inizializza una struttura in modo che i relativi membri possano essere letti utilizzando ReadField.

#define InitTypeRead(
    Addr,
    Type
);

Parametri

addr

Specifica l'indirizzo della struttura nella memoria virtuale della destinazione.

tipo

Specifica il nome del tipo della struttura. Il preprocessore C trasformerà Tipo in una stringa.

Restituisce il valore

Se la macro ha esito positivo, restituisce il valore zero. Se ha esito negativo perché il chiamante ha passato un valore zero come Addr, restituisce il valore MEMORY_READ_ERROR (definito in Wdbgexts.h). Se ha esito negativo per qualsiasi altro motivo, restituisce un codice di errore IG_DUMP_SYMBOL_INFO.

Le macro InitTypeReadPhysical e InitTypeStrReadPhysical inizializzano una struttura in memoria fisica in modo che i relativi membri possano essere letti utilizzando ReadField.

#define InitTypeReadPhysical(
    Addr,
    Type,
    TypeStr
);

Parametri

addr

Specifica l'indirizzo della struttura nella memoria fisica della destinazione.

tipo

Specifica il nome del tipo della struttura. Il preprocessore C trasformerà Tipo in una stringa.

TypeStr

Specifica il nome del tipo della struttura. TypeStr deve essere una stringa ASCII.

Restituisce il valore

Se la macro ha esito positivo, restituisce il valore zero. Se ha esito negativo perché il chiamante ha passato un valore zero come Addr, restituisce il valore MEMORY_READ_ERROR (definito in Wdbgexts.h). Se ha esito negativo per qualsiasi altro motivo, restituisce un codice di errore IG_DUMP_SYMBOL_INFO.

La macro InitTypeRead inizializza una struttura in modo che i relativi membri possano essere letti utilizzando ReadField.

#define InitTypeRead(
    Addr,
    TypeStr
);

Parametri

addr

Specifica l'indirizzo della struttura nella memoria virtuale della destinazione.

tipo

Specifica il nome del tipo della struttura. TypeStr deve essere una stringa ASCII.

Restituisce il valore

Se la macro ha esito positivo, restituisce il valore zero. Se ha esito negativo perché il chiamante ha passato un valore zero come Addr, restituisce il valore MEMORY_READ_ERROR (definito in Wdbgexts.h). Se ha esito negativo per qualsiasi altro motivo, restituisce un codice di errore IG_DUMP_SYMBOL_INFO.

Fabbisogno

Requisito Valore
piattaforma di destinazione Desktop
intestazione wdbgexts.h (include Wdbgexts.h, Dbgeng.h)

Vedere anche

InitTypeRead

initTypeReadPhysical

ReadField