struttura EVENT_DATA_DESCRIPTOR (evntprov.h)

  • Articolo

La struttura EVENT_DATA_DESCRIPTOR definisce un blocco di dati che verrà usato in un evento ETW.

Questa struttura viene in genere inizializzata usando la funzione EventDataDescCreate .

Sintassi

typedef struct _EVENT_DATA_DESCRIPTOR {
  ULONGLONG Ptr;
  ULONG     Size;
  union {
    ULONG Reserved;
    struct {
      UCHAR  Type;
      UCHAR  Reserved1;
      USHORT Reserved2;
    } DUMMYSTRUCTNAME;
  } DUMMYUNIONNAME;
} EVENT_DATA_DESCRIPTOR, *PEVENT_DATA_DESCRIPTOR;

Members

Ptr

Puntatore ai dati.

Importante

Si tratta di un valore intero senza segno a 64 bit nelle architetture a 32 bit e a 64 bit. Per impostare correttamente questo valore, eseguire il cast del puntatore dati a un intero senza segno prima di assegnarlo al Ptr campo, ad esempio EventDataDescriptor.Ptr = (UINT_PTR)dataPointer;o usare la funzione EventDataDescCreate .

Size

Dimensioni dei dati in byte.

DUMMYUNIONNAME

DUMMYUNIONNAME.Reserved

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Type

Specifica l'uso di questi dati nell'evento . I valori possibili sono i seguenti:

  • EVENT_DATA_DESCRIPTOR_TYPE_NONE (0)

    Dati di evento normali.

  • EVENT_DATA_DESCRIPTOR_TYPE_EVENT_METADATA (1)

    Informazioni sulla decodifica degli eventi TraceLogging.

  • EVENT_DATA_DESCRIPTOR_TYPE_PROVIDER_METADATA (2)

    Tratti del provider collegati manualmente. Per l'uso con sistemi operativi che non supportano il collegamento di tratti del provider tramite EventSetInformation. Questi dati verranno ignorati se i tratti del provider sono stati configurati tramite EventSetInformation.

  • EVENT_DATA_DESCRIPTOR_TYPE_TIMESTAMP_OVERRIDE (3)

    Override del timestamp dell'evento a 64 bit. Per usarlo quando si esegue il relogging. Si noti che la registrazione degli eventi fuori dall'ordine di timestamp può causare problemi di ordinamento degli eventi durante l'elaborazione della traccia.

Si noti che questo campo verrà ignorato a meno che il provider di eventi non sia stato configurato per rispettare il Type campo chiamando l'API EventSetInformation con l'operazione EventProviderSetTraits o EventProviderUseDescriptorType .

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Reserved1

Non usato. Impostare su 0.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Reserved2

Non usato. Impostare su 0.

Commenti

La maggior parte dei provider di eventi non chiamerà direttamente EventDataDescCreate . La maggior parte dei provider di eventi viene invece implementata usando un framework ETW che esegue il wrapping delle chiamate a EventRegister, EventWrite e EventUnregister. Ad esempio, è possibile scrivere un manifesto dell'evento e quindi usare il compilatore di messaggi per generare codice C/C++ per gli eventi oppure è possibile usare TraceLogging per evitare la necessità di un manifesto.

Per scrivere un evento contenente i dati dell'evento, è necessario creare una matrice di strutture EVENT_DATA_DESCRIPTOR (un elemento per ogni blocco di dati) e chiamare la funzione EventDataDescCreate per inizializzare ogni elemento con i dati da includere nell'evento. È quindi necessario passare questa matrice a EventWrite per includere i dati nell'evento. Per un esempio, vedere Scrittura di eventi basati su manifesto.

I dati scritti nell'evento saranno la concatenazione dei blocchi di dati a cui fanno riferimento le strutture EVENT_DATA_DESCRIPTOR passate alla EventWrite funzione. Questa concatenazione non contiene spaziatura interna e non mantiene alcun limite o informazioni sulle dimensioni dal set originale di blocchi di dati.

Le dimensioni totali di un evento ETW (la somma dei dati forniti dall'utente, il EVENT_HEADER e qualsiasi EVENT_HEADER_EXTENDED_DATA_ITEM che potrebbe essere necessario per l'evento) non può superare i 64 KB. Gli eventi di dimensioni superiori a 64 KB verranno eliminati dal runtime ETW.

Inoltre, anche gli eventi ETW che non possono rientrare in un buffer di sessione di traccia verranno eliminati. Ogni buffer ha un'intestazione a 72 byte, quindi l'evento più grande che può rientrare in un buffer è leggermente inferiore alle dimensioni del buffer. Ad esempio, una sessione di traccia che usa buffer da 32 KB non sarà in grado di accettare alcun evento maggiore di 32.696 byte (buffer a 32.768 byte meno l'intestazione a 72 byte lascia 32.696 byte per gli eventi).

Requisiti

Requisito Valore
Client minimo supportato Windows Vista [solo app desktop]
Server minimo supportato Windows Server 2008 [solo app desktop]
Intestazione evntprov.h

Vedi anche

EVENT_HEADER

EVENT_HEADER_EXTENDED_DATA_ITEM

EventDataDescCreate

EventWrite

EventWriteTransfer

Scrittura di eventi basati su manifesto