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 o inizializza una struttura in modo che possa essere letto in un secondo momento. Questa funzione non deve essere usata direttamente; InitTypeRead o InitTypeReadPhysical e ReadField devono essere usati invece.

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 non è 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 non è 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 ricordati da una chiamata precedente a questa funzione con StoreAddress non uguale a zero. È possibile specificare sottoscrizioni usando un percorso delimitato da periodi, ad esempio "myfield.mysubfield".

[in] StoreAddress

Specifica la modalità di questa funzione.

Se StoreAddress non è zero:

Causa l'inizializzazione di una struttura per la lettura dei relativi membri. Viene ricordato l'indirizzo e il nome del tipo per la struttura.

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

Se StoreAddress è zero:

Causa la lettura di un membro da una struttura inizializzata in precedenza.

Valore restituito

Codice restituito Descrizione
Se StoreAddress non è 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. Il valore restituito viene eseguito il cast in ULONG64. Se la funzione ha esito negativo, restituisce il valore zero.

Commenti

Quando GetShortField viene chiamato con un valore StoreAddress diverso da zero, inizializza la struttura situata nell'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ù recente, legge in tale struttura il campo specificato da Name e restituisce il valore di tale campo.

Questa funzione non deve essere chiamata direttamente. Le macro InitTypeRead e InitTypeReadPhysical chiamano questa funzione con StoreAddress non 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 TypeAddress e Name usando variabili locali statiche e perché questa funzione è definita in WdbgExts.h, il pre-processore 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 leggeno un campo le cui dimensioni sono inferiori 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

Field FieldStr

Valore restituito

Se questa 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, InitTypeStrReadPhysical o GetShortField. Il campo è quello specificato dal parametro Field o FieldStr di ReadField. Il valore restituito viene eseguito il cast in ULONG64. Se la funzione ha esito negativo, restituisce il valore zero.

Il parametro Field è il nome del membro. Per ReadField, il pre-processore C trasforma il parametro in una stringa. Per ReadFieldStr è previsto che Field sia già una stringa ASCII. Ad esempio, i due comandi seguenti sono identici e leggere lo stesso membro da una struttura inizializzata in precedenza:

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

I sottomember possono essere letti usando un percorso delimitato da periodi, ad esempio "myField.mySubfield".

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

La macro InitTypeRead inizializza una struttura in modo che i membri possano essere letti usando 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 pre-processore C trasforma il tipo in una stringa.

Restituisce il valore

Se questa 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 InitTypeStrReadReadPhysical inizializzano una struttura in memoria fisica in modo che i membri possano essere letti usando 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 pre-processore C trasforma il tipo in una stringa.

TypeStr

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

Restituisce il valore

Se questa 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 membri possano essere letti usando 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 un 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.

Requisiti

Requisito Valore
Piattaforma di destinazione Desktop
Intestazione wdbgexts.h (include Wdbgexts.h, Dbgeng.h)

Vedi anche

InitTypeRead

InitTypeReadPhysical

ReadField