Macro TraceLoggingCustom (traceloggingprovider.h)

Macro wrapper traceLogging que adiciona um campo que foi empacotado usando um serializador personalizado ao evento.

A maioria dos eventos traceLogging não precisa usar um serializador personalizado e não deve usar TraceLoggingCustom.

Sintaxe

void TraceLoggingCustom(
  [in]            pValue,
  [in]            cbValue,
  [in]            protocol,
  [in]            bSchema,
  [in]            cbSchema,
  [in, optional]  __VA_ARGS__
);

Parâmetros

[in] pValue

Um ponteiro para o conteúdo do campo, serializado em runtime por um serializador da família de protocolos especificada.

[in] cbValue

O tamanho, em bytes, da carga do campo, serializado em runtime por um serializador da família de protocolos especificada.

[in] protocol

Uma família de protocolos, que pode ser um valor definido pela Microsoft de 0 a 4 ou um valor definido pelo usuário de 5 a 31. Os valores definidos pela Microsoft são definidos por macros que começam com TRACELOGGING_PROTOCOL_.

[in] bSchema

Uma lista separada por vírgulas de valores de bytes que contêm as informações necessárias para decodificar a carga (ou seja, o esquema), em um formato definido pelo protocolo. Os valores nesta lista devem ser constantes em tempo de compilação. Exemplo: (0x12, 0x23, 0x34)

[in] cbSchema

O número de valores de bytes fornecidos em bSchema. Esse valor deve ser uma constante de tempo de compilação.

[in, optional] __VA_ARGS__

Parâmetros opcionais de nome, descrição e marcas para a definição de campo.

TraceLoggingCustom pode ser especificado com 5, 6, 7 ou 8 parâmetros. Se um parâmetro não for especificado, um padrão será usado. Por exemplo, TraceLoggingCustom(&x.data, sizeof(x.data), p, (schema), cbSchema) é equivalente a TraceLoggingCustom(&x.data, sizeof(x.data), p, (schema), cbSchema, "&x.data", "", 0).

• [in, optional] name

  O nome a ser usado para o campo de evento. Se fornecido, o parâmetro name deve ser um literal de cadeia de caracteres (não uma variável) e não deve conter nenhum caractere '\0'. Se não for fornecido, o nome do campo de evento será baseado em pValue.

• [in, optional] description

  A descrição do valor do campo de evento. Se fornecido, o parâmetro de descrição deve ser um literal de cadeia de caracteres e será incluído no PDB.

• [in, optional] tags

  Um valor inteiro constante de tempo de compilação. Os 28 bits baixos do valor serão incluídos nos metadados do campo. A semântica desse valor é definida pelo consumidor do evento. Durante o processamento de eventos, esse valor pode ser recuperado do campo Marcas de EVENT_PROPERTY_INFO .

Valor retornado

Nenhum

Comentários

TraceLoggingCustom(pValue, cbValue, protocol, (schema...), cbSchema, ...) pode ser usado como um parâmetro para uma invocação de uma macro TraceLoggingWrite . Cada parâmetro TraceLoggingCustom adiciona um campo serializado personalizado ao evento. A maioria dos eventos traceLogging não usa serializadores personalizados e não deve usar TraceLoggingCustom. Os decodificadores ETW de uso geral não dão suporte a campos que usam serialização personalizada e normalmente tratarão os campos como TDH_INTYPE_BINARY.

Os decodificadores devem acessar campos serializados TraceLoggingCustom usando as APIs TDH. A estrutura TRACE_EVENT_INFO retornada por TdhGetEventInformation conterá duas estruturas EVENT_PROPERTY_INFO relacionadas a um campo TraceLoggingCustom registrado. Eles se correlacionam da forma típica com os dados encontrados no blob UserData do EVENT_RECORD para um campo binário (TDH_INTYPE_BINARY).

• A primeira das duas estruturas EVENT_PROPERTY_INFO é a propriedade "Length", que descreve o comprimento da carga serializada (ou seja, cbValue).
• A segunda é a propriedade que se refere ao conteúdo do usuário (pbValue). A segunda propriedade terá PropertyParamLength (em referência à propriedade "Length") e PropertyHasCustomSchema definidas.

Os decodificadores devem reconhecer que PropertyHasCustomSchema foi definido e consultar o membro customSchemaType do EVENT_PROPERTY_INFO para o CustomSchemaOffset, que é o deslocamento no TRACE_EVENT_INFORMATION em que o tipo de protocolo e os metadados de protocolo estão localizados. Lá, eles podem encontrar os metadados passados com um formato de (pseudo-struct):

struct _CUSTOM_SCHEMA {
    UINT16 protocolType;
    UINT16 cbSchema;
    BYTE bSchema[cbSchema];
};

Os decodificadores existentes que não tomam essas etapas extras para reconhecer o sinalizador PropertyHasCustomSchema e, em vez disso, referem-se à parte nonStructType da união EVENT_PROPERTY_INFO para decodificar o evento tratará perfeitamente a carga como se fosse TDH_INTYPE_BINARY.

Exemplos

// Value generated at runtime by serializer:
BYTE rgValue[] = {...};

TraceLoggingWrite(
   g_hProvider,
   "MyEventName",
   TraceLoggingCustom(
      rgValue,
      sizeof(rgValue),
      TRACELOGGING_PROTOCOL_MYPROTOCOL,
      ( 0x0, 0x1, 0x2 ), // Generated at compile-time
      3,
      "MyCustomField"),
   TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
   TraceLoggingKeyword(MyEventCategories)); // Provider-defined categories

Requisitos

Confira também

TraceLoggingWrite

Macros de wrapper traceLogging