Fungsi TdhCreatePayloadFilter (tdh.h)

Artikel
03/08/2023

Fungsi TdhCreatePayloadFilter membuat satu filter untuk satu payload yang akan digunakan dengan fungsi EnableTraceEx2 .

Sintaks

TDHSTATUS TdhCreatePayloadFilter(
  [in]  LPCGUID                   ProviderGuid,
  [in]  PCEVENT_DESCRIPTOR        EventDescriptor,
  [in]  BOOLEAN                   EventMatchANY,
  [in]  ULONG                     PayloadPredicateCount,
  [in]  PPAYLOAD_FILTER_PREDICATE PayloadPredicates,
  [out] PVOID                     *PayloadFilter
);

Parameter

[in] ProviderGuid

GUID yang mengidentifikasi penyedia manifes parameter EventDescriptor .

[in] EventDescriptor

Penunjuk ke deskriptor peristiwa yang payload-nya akan difilter.

[in] EventMatchANY

Nilai Boolean yang menunjukkan bagaimana peristiwa ditangani ketika beberapa kondisi ditentukan.

Ketika parameter ini TRUE, peristiwa akan ditulis ke sesi jika salah satu kondisi yang ditentukan yang ditentukan dalam filter adalah TRUE.

Ketika parameter ini FALSE, peristiwa akan ditulis ke sesi hanya jika semua kondisi yang ditentukan dalam filter adalah TRUE.

[in] PayloadPredicateCount

Jumlah kondisi yang ditentukan dalam filter. Nilai ini harus kurang dari atau sama dengan konstanta ETW_MAX_PAYLOAD_PREDICATES yang ditentukan dalam file header Tdh.h .

[in] PayloadPredicates

Penunjuk ke array struktur PAYLOAD_FILTER_PREDICATE yang berisi kondisi daftar yang ditentukan filter.

[out] PayloadFilter

Setelah berhasil, parameter ini mengembalikan penunjuk ke satu filter payload yang berukuran tepat dan dibuat untuk kondisi yang ditentukan.

Ketika pemanggil selesai menggunakan filter payload yang dikembalikan dengan fungsi EnableTraceEx2 , fungsi TdhDeletePayloadFilter harus dipanggil untuk membebaskan memori yang dialokasikan.

Nilai kembali

Mengembalikan ERROR_SUCCESS jika berhasil. Jika tidak, fungsi ini mengembalikan salah satu kode pengembalian berikut selain yang lain.

Menampilkan kode	Deskripsi
ERROR_FILE_NOT_FOUND	Metadata untuk penyedia tidak ditemukan.
ERROR_INVALID_PARAMETER	Satu atau beberapa parameter tidak valid.
ERROR_INSUFFICIENT_BUFFER	Filter payload yang dihasilkan tidak akan sesuai dalam batas MAX_EVENT_FILTER_PAYLOAD_SIZE yang diberlakukan oleh fungsi EnableTraceEx2 pada struktur EVENT_FILTER_DESCRIPTOR dalam payload.
ERROR_NOT_ENOUGH_MEMORY	Tidak dapat mengalokasikan memori untuk membuat filter payload.
ERROR_NOT_FOUND	Informasi skema untuk GUID penyedia yang disediakan tidak ditemukan.

Keterangan

Pada Windows 8.1,Windows Server 2012 R2, dan yang lebih baru, filter payload peristiwa dapat digunakan oleh fungsi EnableTraceEx2 untuk memfilter konten peristiwa tertentu dalam sesi pencatat.

Fungsi TdhCreatePayloadFilter digunakan untuk membuat filter payload tunggal untuk satu payload yang akan digunakan dengan fungsi EnableTraceEx2 . TdhCreatePayloadFilter mengalokasikan dan mengisi struktur data buram untuk satu filter payload. Ketika filter payload tidak lagi diperlukan, fungsi TdhDeletePayloadFilter digunakan untuk mengosongkan memori yang dialokasikan untuk filter payload.

Untuk satu penyedia, beberapa peristiwa dapat memiliki filter payload yang berbeda. Mungkin juga ada beberapa filter untuk peristiwa yang sama, dengan payload diteruskan ke sesi jika salah satu atau semua filter peristiwa meneruskannya.

Fungsi EnableTraceEx2 mengambil array struktur EVENT_FILTER_DESCRIPTOR dalam struktur ENABLE_TRACE_PARAMETERS yang diteruskan dalam parameter EnableParameters . Hanya boleh ada satu entri dalam array untuk setiap jenis filter peristiwa. Fungsi TdhAggregatePayloadFilters dapat digunakan untuk menggabungkan daftar filter payload untuk satu penyedia yang dibuat menggunakan TdhCreatePayloadFilter ke dalam struktur data tunggal dan mengembalikan EVENT_FILTER_DESCRIPTOR untuk digunakan dengan fungsi EnableTraceEx2 .

Contoh

Misalnya yang menggunakan fungsi TdhCreatePayloadFilter untuk membuat filter payload yang akan digunakan dalam pemfilteran pada kondisi tertentu dalam sesi pencatat, lihat contoh untuk fungsi EnableTraceEx2 .

Persyaratan


Klien minimum yang didukung	Windows 8.1 [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2012 R2 [hanya aplikasi desktop]
Target Platform	Windows
Header	tdh.h
Pustaka	Tdh.lib
DLL	Tdh.dll