TraceLoggingCustom 宏 (traceloggingprovider.h)

TraceLogging 包裝函式宏 ，會將使用自訂序列化程式封裝的欄位新增至 事件。

大部分 TraceLogging 事件不需要使用自訂序列化程式，而且不應該使用 TraceLoggingCustom。

語法

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

參數

[in] pValue

欄位承載的指標，由指定通訊協定系列中的序列化程式在執行時間序列化。

[in] cbValue

欄位承載的大小，以位元組為單位，由指定通訊協定系列中的序列化程式在執行時間序列化。

[in] protocol

通訊協定系列，可能是來自 0-4 的 Microsoft 定義值，或 5-31 的使用者定義值。 Microsoft 定義的值是由從 開始的 TRACELOGGING_PROTOCOL_ 宏所定義。

[in] bSchema

以逗號分隔的位元組值清單，其中包含解碼承載所需的資訊 (，也就是架構) ，以通訊協定定義的格式。 此清單中的值必須是編譯時間常數。 範例： (0x12、0x23、0x34)

[in] cbSchema

bSchema中提供的位元組值數目。 此值必須是編譯時間常數。

[in, optional] __VA_ARGS__

欄位定義的選擇性 名稱、 描述和 標記 參數。

TraceLoggingCustom 可以使用 5、6、7 或 8 參數來指定。 如果未指定參數，則會使用預設值。 例如，TraceLoggingCustom(&x.data, sizeof(x.data), p, (schema), cbSchema) 相當於 TraceLoggingCustom(&x.data, sizeof(x.data), p, (schema), cbSchema, "&x.data", "", 0)。

• [in, optional] name

  要用於事件欄位的名稱。 如果提供，name 參數必須是字串常值， (不是變數) ，且不得包含任何 '\0' 字元。 如果未提供，事件功能變數名稱將會以 pValue為基礎。

• [in, optional] description

  事件欄位值的描述。 如果提供，description 參數必須是字串常值，且將會包含在 PDB中。

• [in, optional] tags

  編譯時間常數整數值。 值的低 28 位將會包含在欄位的中繼資料中。 此值的語意是由事件取用者所定義。 在事件處理期間，可以從 [EVENT_PROPERTY_INFO 標記 ] 欄位擷取此值。

傳回值

無

備註

TraceLoggingCustom(pValue, cbValue, protocol, (schema...), cbSchema, ...) 可作為 TraceLoggingWrite 宏調用的參數。 每個 TraceLoggingCustom 參數都會將自訂序列化欄位新增至事件。 大部分 TraceLogging 事件不會使用自訂序列化程式，而且不應該使用 TraceLoggingCustom。 一般用途 ETW 解碼器不支援使用自訂序列化的欄位，而且通常會將欄位視為TDH_INTYPE_BINARY。

解碼器應該使用 TDH API 存取 TraceLoggingCustom 序列化欄位。 TdhGetEventInformation 傳回的TRACE_EVENT_INFO結構將包含兩個與記錄的 TraceLoggingCustom 欄位相關的EVENT_PROPERTY_INFO結構。 這些會以一般方式與在二進位欄位EVENT_RECORD UserData Blob 中找到的資料相互關聯 (TDH_INTYPE_BINARY) 。

• 兩個EVENT_PROPERTY_INFO結構的第一個是 「Length」 屬性，描述序列化承載的長度 (，也就是 cbValue) 。
• 第二個是參考使用者承載的屬性， (pbValue) 。 第二個屬性會有 PropertyParamLength (參考 「Length」 屬性) 和 PropertyHasCustomSchema 集合。

解碼器應該會辨識已設定 PropertyHasCustomSchema，並查閱 customSchemaOffset 的 EVENT_PROPERTY_INFO customSchemaType 成員，這是通訊協定類型和通訊協定中繼資料所在TRACE_EVENT_INFORMATION中的位移。 您可以在該處找到以虛擬結構 (格式傳遞的中繼資料) ：

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

未採取這些額外步驟來辨識 PropertyHasCustomSchema 旗標的現有解碼器，而是參考EVENT_PROPERTY_INFO等位的非結構類型部分來解碼事件，會將承載順暢地視為TDH_INTYPE_BINARY。

範例

// 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

規格需求

另請參閱

TraceLoggingWrite

TraceLogging 包裝函式宏