estrutura EVENT_DATA_DESCRIPTOR (evntprov.h)

  • Artigo

A estrutura EVENT_DATA_DESCRIPTOR define um bloco de dados que será usado em um evento ETW.

Normalmente, essa estrutura é inicializada usando a função EventDataDescCreate .

Sintaxe

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;

Membros

Ptr

Um ponteiro para os dados.

Importante

Esse é um valor inteiro sem sinal de 64 bits em arquiteturas de 32 bits e 64 bits. Para definir corretamente esse valor, converta o ponteiro de dados para um inteiro sem sinal antes de atribuí-lo ao Ptr campo, por exemplo EventDataDescriptor.Ptr = (UINT_PTR)dataPointer;, ou use a função EventDataDescCreate .

Size

O tamanho dos dados em bytes.

DUMMYUNIONNAME

DUMMYUNIONNAME.Reserved

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Type

Especifica o uso desses dados no evento. Esse valor pode ser um dos seguintes:

  • EVENT_DATA_DESCRIPTOR_TYPE_NONE (0)

    Dados de evento normais.

  • EVENT_DATA_DESCRIPTOR_TYPE_EVENT_METADATA (1)

    Informações de decodificação de evento traceLogging.

  • EVENT_DATA_DESCRIPTOR_TYPE_PROVIDER_METADATA (2)

    Características de provedor anexadas manualmente. Para uso com sistemas operacionais que não dão suporte à anexação de características do provedor por meio de EventSetInformation. Esses dados serão ignorados se as características do provedor tiverem sido configuradas por meio de EventSetInformation.

  • EVENT_DATA_DESCRIPTOR_TYPE_TIMESTAMP_OVERRIDE (3)

    Substituição de carimbo de data/hora do evento de 64 bits. Para uso ao registrar novamente. Observe que registrar eventos fora da ordem de carimbo de data/hora pode levar a problemas de ordenação de eventos durante o processamento de rastreamento.

Observe que esse campo será ignorado, a menos que o provedor de eventos tenha sido configurado para respeitar o Type campo chamando a API EventSetInformation com a EventProviderSetTraits operação ou EventProviderUseDescriptorType .

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Reserved1

Não usado. Defina como 0.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Reserved2

Não usado. Defina como 0.

Comentários

A maioria dos provedores de eventos não chamará EventDataDescCreate diretamente. Em vez disso, a maioria dos provedores de eventos é implementada usando uma estrutura ETW que encapsula as chamadas para EventRegister, EventWrite e EventUnregister. Por exemplo, você pode escrever um manifesto de evento e usar o Compilador de Mensagens para gerar código C/C++ para os eventos ou pode usar TraceLogging para evitar a necessidade de um manifesto.

Para gravar um evento que contém dados de evento, você criaria uma matriz de estruturas de EVENT_DATA_DESCRIPTOR (um elemento para cada parte de dados) e chamaria a função EventDataDescCreate para inicializar cada elemento com os dados a serem incluídos em seu evento. Em seguida, você passaria essa matriz para EventWrite para incluir os dados no evento. Para obter um exemplo, consulte Escrevendo eventos baseados em manifesto.

Os dados gravados no evento serão a concatenação das partes de dados referenciadas pelas estruturas de EVENT_DATA_DESCRIPTOR passadas para a EventWrite função. Essa concatenação não contém preenchimento e não retém nenhum dos limites ou informações de tamanho do conjunto original de partes de dados.

O tamanho total de um evento ETW (a soma dos dados fornecidos pelo usuário, o EVENT_HEADER e qualquer EVENT_HEADER_EXTENDED_DATA_ITEM que possa ser necessário para o evento) não pode exceder 64 KB. Eventos maiores que 64 KB serão descartados pelo runtime do ETW.

Além disso, eventos ETW que não cabem em um buffer de sessão de rastreamento também serão descartados. Cada buffer tem um cabeçalho de 72 bytes, portanto, o maior evento que pode caber em um buffer é ligeiramente menor que o tamanho do buffer. Por exemplo, uma sessão de rastreamento que usa buffers de 32 KB não poderá aceitar nenhum evento maior que 32.696 bytes (buffer de 32.768 bytes menos o cabeçalho de 72 bytes deixa 32.696 bytes para eventos).

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2008 [somente aplicativos da área de trabalho]
Cabeçalho evntprov.h

Confira também

EVENT_HEADER

EVENT_HEADER_EXTENDED_DATA_ITEM

EventDataDescCreate

EventWrite

EventWriteTransfer

Gravando eventos baseados em manifesto