structure EVENT_DATA_DESCRIPTOR (evntprov.h)

La structure EVENT_DATA_DESCRIPTOR définit un bloc de données qui sera utilisé dans un événement ETW.

Cette structure est généralement initialisée à l’aide de la fonction EventDataDescCreate .

Syntaxe

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;

Membres

Ptr

Pointeur vers les données.

Important

Il s’agit d’une valeur entière non signée 64 bits dans les architectures 32 bits et 64 bits. Pour définir correctement cette valeur, castez votre pointeur de données en entier non signé avant de l’affecter au Ptr champ, par EventDataDescriptor.Ptr = (UINT_PTR)dataPointer;exemple , ou utilisez la fonction EventDataDescCreate .

Size

Taille des données en octets.

DUMMYUNIONNAME

DUMMYUNIONNAME.Reserved

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Type

Spécifie l’utilisation de ces données dans l’événement. Il peut s’agir de l’une des valeurs suivantes :

• EVENT_DATA_DESCRIPTOR_TYPE_NONE (0)

  Données d’événement normales.

• EVENT_DATA_DESCRIPTOR_TYPE_EVENT_METADATA (1)

  Informations de décodage de l’événement TraceLogging.

• EVENT_DATA_DESCRIPTOR_TYPE_PROVIDER_METADATA (2)

  Caractéristiques de fournisseur attachées manuellement. À utiliser avec des systèmes d’exploitation qui ne prennent pas en charge l’attachement de caractéristiques de fournisseur via EventSetInformation. Ces données seront ignorées si les caractéristiques du fournisseur ont été configurées via EventSetInformation.

• EVENT_DATA_DESCRIPTOR_TYPE_TIMESTAMP_OVERRIDE (3)

  Remplacement de l’horodatage d’événement 64 bits. À utiliser lors du relogging. Notez que la journalisation des événements dans l’ordre d’horodatage peut entraîner des problèmes d’ordre des événements pendant le traitement des traces.

Notez que ce champ sera ignoré, sauf si le fournisseur d’événements a été configuré pour respecter le Type champ en appelant l’API EventSetInformation avec l’opération EventProviderSetTraits ou EventProviderUseDescriptorType .

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Reserved1

Non utilisé. Définit la valeur 0.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Reserved2

Non utilisé. Définit la valeur 0.

Remarques

La plupart des fournisseurs d’événements n’appellent pas Directement EventDataDescCreate . Au lieu de cela, la plupart des fournisseurs d’événements sont implémentés à l’aide d’une infrastructure ETW qui encapsule les appels à EventRegister, EventWrite et EventUnregister. Par exemple, vous pouvez écrire un manifeste d’événement , puis utiliser le compilateur de messages pour générer du code C/C++ pour les événements, ou vous pouvez utiliser TraceLogging pour éviter d’avoir besoin d’un manifeste.

Pour écrire un événement qui contient des données d’événement, vous devez créer un tableau de structures EVENT_DATA_DESCRIPTOR (un élément pour chaque segment de données) et appeler la fonction EventDataDescCreate pour initialiser chaque élément avec les données à inclure dans votre événement. Vous passerez ensuite ce tableau à EventWrite pour inclure les données dans l’événement. Pour obtenir un exemple, consultez Écriture d’événements basés sur un manifeste.

Les données écrites dans l’événement seront la concaténation des blocs de données référencés par les structures EVENT_DATA_DESCRIPTOR passées à la EventWrite fonction. Cette concaténation ne contient aucun remplissage et ne conserve aucune des limites ou informations de taille du jeu de blocs de données d’origine.

La taille totale d’un événement ETW (la somme des données fournies par l’utilisateur, des EVENT_HEADER et des EVENT_HEADER_EXTENDED_DATA_ITEM qui peuvent être nécessaires pour l’événement) ne peut pas dépasser 64 Ko. Les événements supérieurs à 64 Ko seront supprimés par le runtime ETW.

En outre, les événements ETW qui ne peuvent pas tenir dans une mémoire tampon de session de trace seront également supprimés. Chaque mémoire tampon a un en-tête de 72 octets, de sorte que le plus grand événement pouvant tenir dans une mémoire tampon est légèrement plus petit que la taille de la mémoire tampon. Par exemple, une session de suivi qui utilise des mémoires tampons de 32 Ko ne peut pas accepter d’événement supérieur à 32 696 octets (32 768 octets de mémoire tampon moins l’en-tête de 72 octets laisse 32 696 octets pour les événements).

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
En-tête	evntprov.h

Voir aussi

EVENT_HEADER

EVENT_HEADER_EXTENDED_DATA_ITEM

EventDataDescCreate

EventWrite

EventWriteTransfer

Écriture d’événements basés sur un manifeste