EVENT_DATA_DESCRIPTOR-Struktur (evntprov.h)

  • Artikel

Die EVENT_DATA_DESCRIPTOR-Struktur definiert einen Datenblock, der in einem ETW-Ereignis verwendet wird.

Diese Struktur wird in der Regel mit der EventDataDescCreate-Funktion initialisiert.

Syntax

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;

Member

Ptr

Ein Zeiger auf die Daten.

Wichtig

Dies ist ein ganzzahliger 64-Bit-Wert ohne Vorzeichen in 32-Bit- und 64-Bit-Architekturen. Um diesen Wert ordnungsgemäß festzulegen, wandeln Sie den Datenzeiger auf eine ganze Zahl ohne Vorzeichen um, bevor Sie ihn dem Ptr Feld zuweisen, z. B. EventDataDescriptor.Ptr = (UINT_PTR)dataPointer;, oder verwenden Sie die EventDataDescCreate-Funktion .

Size

Die Größe der Daten in Bytes.

DUMMYUNIONNAME

DUMMYUNIONNAME.Reserved

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Type

Gibt die Verwendung dieser Daten im Ereignis an. Mögliche Werte:

  • EVENT_DATA_DESCRIPTOR_TYPE_NONE (0)

    Normale Ereignisdaten.

  • EVENT_DATA_DESCRIPTOR_TYPE_EVENT_METADATA (1)

    TraceLogging-Ereignisdecodierungsinformationen.

  • EVENT_DATA_DESCRIPTOR_TYPE_PROVIDER_METADATA (2)

    Manuell angefügte Anbietereigenschaften. Zur Verwendung mit Betriebssystemen, die das Anfügen von Anbietermerkmalen über EventSetInformation nicht unterstützen. Diese Daten werden ignoriert, wenn Anbietereigenschaften über EventSetInformationkonfiguriert wurden.

  • EVENT_DATA_DESCRIPTOR_TYPE_TIMESTAMP_OVERRIDE (3)

    64-Bit-Ereigniszeitstempel überschreiben. Zur Verwendung beim erneuten Protokollieren. Beachten Sie, dass das Protokollieren von Ereignissen aus der Zeitstempelreihenfolge während der Ablaufverfolgungsverarbeitung zu Problemen bei der Ereignisreihenfolge führen kann.

Beachten Sie, dass dieses Feld ignoriert wird, es sei denn, der Ereignisanbieter wurde so konfiguriert, dass er das Type Feld respektiert, indem die EventSetInformation-API mit dem EventProviderSetTraits - oder EventProviderUseDescriptorType -Vorgang aufgerufen wird.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Reserved1

Nicht verwendet. Auf 0 festlegen.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Reserved2

Nicht verwendet. Auf 0 festlegen.

Hinweise

Die meisten Ereignisanbieter rufen EventDataDescCreate nicht direkt auf. Stattdessen werden die meisten Ereignisanbieter mithilfe eines ETW-Frameworks implementiert, das die Aufrufe von EventRegister, EventWrite und EventUnregister umschließt. Sie können beispielsweise ein Ereignismanifest schreiben und dann den Nachrichtencompiler verwenden, um C/C++-Code für die Ereignisse zu generieren, oder Sie können TraceLogging verwenden, um die Notwendigkeit eines Manifests zu vermeiden.

Um ein Ereignis zu schreiben, das Ereignisdaten enthält, erstellen Sie ein Array von EVENT_DATA_DESCRIPTOR Strukturen (ein Element für jeden Datenblock) und rufen die EventDataDescCreate-Funktion auf, um jedes Element mit den Daten zu initialisieren, die in Ihr Ereignis eingeschlossen werden sollen. Anschließend übergeben Sie dieses Array an EventWrite , um die Daten in das Ereignis einzuschließen. Ein Beispiel finden Sie unter Schreiben manifestbasierter Ereignisse.

Die in das Ereignis geschriebenen Daten sind die Verkettung der Datenblöcke, auf die vom EVENT_DATA_DESCRIPTOR Strukturen verwiesen wird, die an die EventWrite Funktion übergeben werden. Diese Verkettung enthält keine Auffüllung und behält keine Der Grenzen oder Größeninformationen aus dem ursprünglichen Satz von Datenblöcken bei.

Die Gesamtgröße eines ETW-Ereignisses (die Summe der vom Benutzer bereitgestellten Daten, der EVENT_HEADER und aller EVENT_HEADER_EXTENDED_DATA_ITEM , die für das Ereignis möglicherweise erforderlich sind) darf 64 KB nicht überschreiten. Ereignisse, die größer als 64 KB sind, werden von der ETW-Runtime gelöscht.

Darüber hinaus werden AUCH ETW-Ereignisse gelöscht, die nicht in einen Ablaufverfolgungssitzungspuffer passen können. Jeder Puffer verfügt über einen 72-Byte-Header, sodass das größte Ereignis, das in einen Puffer passen kann, etwas kleiner als die Größe des Puffers ist. Beispielsweise kann eine Ablaufverfolgungssitzung, die 32 KB-Puffer verwendet, kein Ereignis akzeptieren, das größer als 32.696 Bytes ist (32.768 Byte-Puffer abzüglich des 72-Byte-Headers lässt 32.696 Bytes für Ereignisse übrig).

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 [nur Desktop-Apps]
Kopfzeile evntprov.h

Weitere Informationen

EVENT_HEADER

EVENT_HEADER_EXTENDED_DATA_ITEM

EventDataDescCreate

EventWrite

EventWriteTransfer

Schreiben manifestbasierter Ereignisse