Makro traceLoggingCustom (traceloggingprovider.h)

Makro pembungkus TraceLogging yang menambahkan bidang yang dikemas menggunakan serializer kustom ke peristiwa tersebut.

Sebagian besar peristiwa TraceLogging tidak perlu menggunakan serializer kustom dan tidak boleh menggunakan TraceLoggingCustom.

Sintaks

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

Parameter

[in] pValue

Penunjuk ke payload bidang, diserialisasikan saat runtime oleh serializer dari keluarga protokol yang ditentukan.

[in] cbValue

Ukuran, dalam byte, payload bidang, diserialisasikan pada runtime oleh serializer dari keluarga protokol yang ditentukan.

[in] protocol

Keluarga protokol, yang mungkin merupakan nilai yang ditentukan Microsoft dari 0-4 atau nilai yang ditentukan pengguna dari 5-31. Nilai yang ditentukan Microsoft ditentukan oleh makro yang dimulai dengan TRACELOGGING_PROTOCOL_.

[in] bSchema

Daftar nilai byte yang dipisahkan koma yang berisi informasi yang diperlukan untuk mendekode payload (yaitu skema), dalam format yang ditentukan protokol. Nilai dalam daftar ini harus konstanta waktu kompilasi. Contoh: (0x12, 0x23, 0x34)

[in] cbSchema

Jumlah nilai byte yang disediakan dalam bSchema. Nilai ini harus berupa konstanta waktu kompilasi.

[in, optional] __VA_ARGS__

Parameter nama, deskripsi, dan tag opsional untuk definisi bidang.

TraceLoggingCustom dapat ditentukan dengan 5, 6, 7, atau 8 parameter. Jika parameter tidak ditentukan, default akan digunakan. Misalnya, TraceLoggingCustom(&x.data, sizeof(x.data), p, (schema), cbSchema) sama dengan TraceLoggingCustom(&x.data, sizeof(x.data), p, (schema), cbSchema, "&x.data", "", 0).

• [in, optional] name

  Nama yang digunakan untuk bidang peristiwa. Jika disediakan, parameter nama harus berupa string literal (bukan variabel) dan tidak boleh berisi karakter '\0'. Jika tidak disediakan, nama bidang peristiwa akan didasarkan pada pValue.

• [in, optional] description

  Deskripsi nilai bidang peristiwa. Jika disediakan, parameter deskripsi harus berupa string literal dan akan disertakan dalam PDB.

• [in, optional] tags

  Nilai bilangan bulat konstanta waktu kompilasi. Nilai 28 bit rendah akan disertakan dalam metadata bidang. Semantik nilai ini ditentukan oleh konsumen peristiwa. Selama pemrosesan peristiwa, nilai ini dapat diambil dari bidang Tag EVENT_PROPERTY_INFO .

Menampilkan nilai

Tidak ada

Keterangan

TraceLoggingCustom(pValue, cbValue, protocol, (schema...), cbSchema, ...) dapat digunakan sebagai parameter untuk pemanggilan makro TraceLoggingWrite . Setiap parameter TraceLoggingCustom menambahkan bidang berseri kustom ke peristiwa. Sebagian besar peristiwa TraceLogging tidak menggunakan serializer kustom dan tidak boleh menggunakan TraceLoggingCustom. Dekode ETW tujuan umum tidak mendukung bidang yang menggunakan serialisasi kustom dan biasanya akan memperlakukan bidang sebagai TDH_INTYPE_BINARY.

Dekode harus mengakses bidang berseri TraceLoggingCustom menggunakan API TDH. Struktur TRACE_EVENT_INFO yang dikembalikan oleh TdhGetEventInformation akan berisi dua struktur EVENT_PROPERTY_INFO yang terkait dengan bidang TraceLoggingCustom yang dicatat. Ini berkorelasi dengan cara umum dengan data yang ditemukan di blob UserData EVENT_RECORD untuk bidang biner (TDH_INTYPE_BINARY).

• Yang pertama dari dua struktur EVENT_PROPERTY_INFO adalah properti "Panjang" yang menjelaskan panjang payload berseri (yaitu cbValue).
• Yang kedua adalah properti yang mengacu pada payload pengguna (pbValue). Properti kedua akan memiliki PropertyParamLength (mengacu pada properti "Panjang"), dan propertiHasCustomSchema diatur.

Decoders harus mengenali bahwa PropertyHasCustomSchema telah diatur dan berkonsultasi dengan anggota customSchemaType EVENT_PROPERTY_INFO untuk CustomSchemaOffset, yang merupakan offset dalam TRACE_EVENT_INFORMATION tempat jenis protokol dan metadata protokol berada. Di sana, mereka dapat menemukan metadata yang mereka lewati dengan format (pseudo-struct):

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

Dekode yang ada yang tidak mengambil langkah tambahan ini untuk mengenali bendera PropertyHasCustomSchema dan sebaliknya merujuk ke bagian nonStructType dari serikat EVENT_PROPERTY_INFO untuk mendekode peristiwa akan memperlakukan payload dengan mulus seolah-olah itu TDH_INTYPE_BINARY.

Contoh

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

Persyaratan

Klien minimum yang didukung	Windows Vista [aplikasi desktop | Aplikasi UWP]
Server minimum yang didukung	Windows Server 2008 [aplikasi desktop | Aplikasi UWP]
Target Platform	Windows
Header	traceloggingprovider.h

Lihat juga

TraceLoggingWrite

Makro pembungkus TraceLogging