Fungsi TdhFormatProperty (tdh.h)

Artikel
03/08/2023

Memformat nilai properti untuk ditampilkan.

Sintaks

TDHSTATUS TdhFormatProperty(
  [in]            PTRACE_EVENT_INFO EventInfo,
  [in, optional]  PEVENT_MAP_INFO   MapInfo,
  [in]            ULONG             PointerSize,
  [in]            USHORT            PropertyInType,
  [in]            USHORT            PropertyOutType,
  [in]            USHORT            PropertyLength,
  [in]            USHORT            UserDataLength,
  [in]            PBYTE             UserData,
  [in, out]       PULONG            BufferSize,
  [out, optional] PWCHAR            Buffer,
  [out]           PUSHORT           UserDataConsumed
);

Parameter

[in] EventInfo

Struktur TRACE_EVENT_INFO yang berisi informasi peristiwa. Untuk mendapatkan struktur ini, panggil fungsi TdhGetEventInformation.

[in, optional] MapInfo

Struktur EVENT_MAP_INFO yang memetakan nilai bilangan bulat dan bit ke string. Untuk mendapatkan struktur ini, panggil fungsi TdhGetEventMapInformation. Untuk mendapatkan nama peta, gunakan anggota MapNameOffset dari struktur EVENT_PROPERTY_INFO. Jika Anda tidak memberikan informasi peta untuk properti yang dipetakan, fungsi memformat nilai bilangan bulat atau bit.

[in] PointerSize

Ukuran nilai penunjuk dalam data peristiwa. Untuk mendapatkan ukurannya, akses EVENT_RECORD. Anggota EventHeader.Flags . Ukuran pointer adalah 4 byte jika bendera EVENT_HEADER_FLAG_32_BIT_HEADER diatur; jika tidak, itu adalah 8 byte jika bendera EVENT_HEADER_FLAG_64_BIT_HEADER diatur. Struktur EVENT_RECORD (evntcons.h) diteruskan ke [fungsi panggilan balik PEVENT_RECORD_CALLBACK] Anda.

[in] PropertyInType

Jenis input properti . Gunakan anggota InType dari struktur EVENT_PROPERTY_INFO untuk mengatur parameter ini.

[in] PropertyOutType

Jenis output properti . Gunakan anggota OutType dari struktur EVENT_PROPERTY_INFO untuk mengatur parameter ini.

[in] PropertyLength

Panjangnya, dalam byte, dari properti . Gunakan anggota Panjangstruktur EVENT_PROPERTY_INFO untuk mengatur parameter ini.

[in] UserDataLength

Ukuran, dalam byte, dari buffer UserData . Lihat Keterangan.

[in] UserData

Buffer yang berisi data peristiwa. Lihat Keterangan.

[in, out] BufferSize

Ukuran, dalam byte, dari buffer Buffer . Jika fungsi berhasil, parameter ini menerima ukuran buffer yang digunakan. Jika buffer terlalu kecil, fungsi mengembalikan ERROR_INSUFFICIENT_BUFFER dan mengatur parameter ini ke ukuran buffer yang diperlukan. Jika ukuran buffer nol pada input, tidak ada data yang dikembalikan dalam buffer dan parameter ini menerima ukuran buffer yang diperlukan.

[out, optional] Buffer

Buffer yang dialokasikan penelepon yang berisi nilai properti yang diformat. Untuk menentukan ukuran buffer yang diperlukan, atur parameter ini ke NULL dan BufferSize ke nol.

[out] UserDataConsumed

Panjang, dalam byte, dari data peristiwa yang digunakan. Gunakan nilai ini untuk menyesuaikan nilai parameter UserData dan UserDataLength . Lihat Keterangan.

Mengembalikan nilai

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

Menampilkan kode	Deskripsi
ERROR_INSUFFICIENT_BUFFER	Ukuran buffer pBuffer terlalu kecil. Gunakan set ukuran buffer yang diperlukan di pBufferSize untuk mengalokasikan buffer baru.
ERROR_INVALID_PARAMETER	Satu atau beberapa parameter tidak valid.
ERROR_EVT_INVALID_EVENT_DATA	Data peristiwa tidak cocok dengan definisi peristiwa dalam manifes.

Keterangan

Biasanya, Anda memanggil fungsi ini dalam perulangan. Gunakan TRACE_EVENT_INFO. Anggota TopLevelPropertyCount untuk mengontrol perulangan ( fungsi TdhGetEventInformation mengembalikan struktur TRACE_EVENT_INFO). Sebelum memasukkan perulangan, Anda mengatur parameter UserData dan UserDataLength ke nilai anggota UserData dan UserDataLength dari struktur EVENT_RECORD. Struktur EVENT_RECORD diteruskan ke [fungsi panggilan balik PEVENT_RECORD_CALLBACK] Anda.

Tentukan apakah properti adalah array. Properti adalah array jika EVENT_PROPERTY_INFO. Anggota bendera diatur ke PropertyParamCount atau anggota EVENT_PROPERTY_INFO.count lebih besar dari 1. Panggil fungsi TdhFormatProperty dalam perulangan berdasarkan jumlah elemen dalam array.

Setelah memanggil fungsi TdhFormatProperty , gunakan nilai parameter UserDataConsumed untuk mengatur nilai baru parameter UserData dan UserDataLength (Kurangi UserDataConsumed dari UserDataLength dan gunakan UserDataLength untuk meningkatkan penunjuk UserData ).

Jika properti adalah alamat IP V6, Anda harus mengatur parameter PropertyLength ke ukuran struktur IN6_ADDR . Properti dianggap sebagai alamat IP V6 jika kondisi berikut terpenuhi:

Anggota InType dari struktur EVENT_PROPERTY_INFO TDH_INTYPE_BINARY
Anggota OutType dari struktur EVENT_PROPERTY_INFO TDH_OUTTYPE_IPV6
Anggota Panjangstruktur EVENT_PROPERTY_INFO adalah 0

Contoh

Untuk contoh yang memperlihatkan cara memanggil fungsi ini , lihat Menggunakan TdhFormatProperty untuk Mengonsumsi Data Peristiwa.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 7 [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 R2 [hanya aplikasi desktop]
Target Platform	Windows
Header	tdh.h
Pustaka	Tdh.lib
DLL	Tdh.dll

Bagikan melalui