struktur EVENT_DATA_DESCRIPTOR (evntprov.h)

Artikel
08/23/2023

Struktur EVENT_DATA_DESCRIPTOR mendefinisikan blok data yang akan digunakan dalam peristiwa ETW.

Struktur ini biasanya diinisialisasi menggunakan fungsi EventDataDescCreate .

Sintaks

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;

Anggota

Ptr

Penunjuk pada data.

Penting

Ini adalah nilai bilangan bulat 64-bit yang tidak ditandatangani dalam arsitektur 32-bit dan 64-bit. Untuk mengatur nilai ini dengan benar, transmisikan penunjuk data Anda ke bilangan bulat yang tidak ditandatangani sebelum menetapkannya ke Ptr bidang, misalnya EventDataDescriptor.Ptr = (UINT_PTR)dataPointer;, atau gunakan fungsi EventDataDescCreate .

Size

Ukuran data dalam byte.

DUMMYUNIONNAME

DUMMYUNIONNAME.Reserved

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Type

Menentukan penggunaan data ini dalam peristiwa tersebut. Ini bisa menjadi salah satu nilai berikut:

EVENT_DATA_DESCRIPTOR_TYPE_NONE (0)

Data peristiwa normal.
EVENT_DATA_DESCRIPTOR_TYPE_EVENT_METADATA (1)

Informasi pendekodean peristiwa TraceLogging.
EVENT_DATA_DESCRIPTOR_TYPE_PROVIDER_METADATA (2)

Sifat penyedia yang terpasang secara manual. Untuk digunakan dengan sistem operasi yang tidak mendukung melampirkan sifat penyedia melalui EventSetInformation. Data ini akan diabaikan jika sifat penyedia telah dikonfigurasi melalui EventSetInformation.
EVENT_DATA_DESCRIPTOR_TYPE_TIMESTAMP_OVERRIDE (3)

Penimpaan tanda waktu peristiwa 64-bit. Untuk digunakan saat relogging. Perhatikan bahwa peristiwa pengelogan dari urutan tanda waktu dapat menyebabkan masalah pemesanan peristiwa selama pemrosesan jejak.

Perhatikan bahwa bidang ini akan diabaikan kecuali penyedia peristiwa telah dikonfigurasi untuk menghormati Type bidang dengan memanggil EVENTSetInformation API dengan EventProviderSetTraits operasi atau EventProviderUseDescriptorType .

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Reserved1

Tidak digunakan. Atur ke 0.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Reserved2

Tidak digunakan. Atur ke 0.

Keterangan

Sebagian besar penyedia peristiwa tidak akan memanggil EventDataDescCreate secara langsung. Sebagai gantinya, sebagian besar penyedia peristiwa diimplementasikan menggunakan kerangka kerja ETW yang membungkus panggilan ke EventRegister, EventWrite, dan EventUnregister. Misalnya, Anda dapat menulis manifes peristiwa lalu menggunakan Pengkompilasi Pesan untuk menghasilkan kode C/C++ untuk peristiwa tersebut, atau Anda dapat menggunakan TraceLogging untuk menghindari kebutuhan akan manifes.

Untuk menulis peristiwa yang berisi data peristiwa, Anda akan membuat array struktur EVENT_DATA_DESCRIPTOR (satu elemen untuk setiap gugus data) dan memanggil fungsi EventDataDescCreate untuk menginisialisasi setiap elemen dengan data yang akan disertakan dalam peristiwa Anda. Anda kemudian akan meneruskan array ini ke EventWrite untuk menyertakan data ke dalam peristiwa. Misalnya, lihat Menulis Peristiwa Berbasis Manifes.

Data yang ditulis ke peristiwa akan menjadi perangkaian potongan data yang direferensikan oleh struktur EVENT_DATA_DESCRIPTOR yang diteruskan ke EventWrite fungsi. Perangkaian ini tidak berisi padding dan tidak mempertahankan batas atau informasi ukuran apa pun dari kumpulan potongan data asli.

Ukuran total peristiwa ETW (jumlah data yang disediakan pengguna, EVENT_HEADER, dan EVENT_HEADER_EXTENDED_DATA_ITEM apa pun yang mungkin diperlukan untuk peristiwa tersebut) tidak boleh melebihi 64KB. Peristiwa yang lebih besar dari 64KB akan dihilangkan oleh runtime ETW.

Selain itu, peristiwa ETW yang tidak dapat masuk ke dalam buffer sesi pelacakan juga akan dihilangkan. Setiap buffer memiliki header 72-byte, sehingga peristiwa terbesar yang dapat masuk ke dalam buffer sedikit lebih kecil dari ukuran buffer. Misalnya, sesi pelacakan yang menggunakan buffer 32KB tidak akan dapat menerima peristiwa apa pun yang lebih besar dari 32.696 byte (buffer 32.768 byte dikurangi header 72-byte meninggalkan 32.696 byte untuk peristiwa).

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Header	evntprov.h