PM_COLLECT_PROC fungsi panggilan balik (winperf.h)

Artikel
08/27/2023

Mengumpulkan data performa dan mengembalikannya ke konsumen. Terapkan dan ekspor fungsi ini jika Anda menulis DLL performa untuk menyediakan data performa. Sistem memanggil fungsi ini setiap kali konsumen meminta registri untuk data performa.

Fungsi CollectPerformanceData adalah tempat penampung untuk nama fungsi yang ditentukan aplikasi.

Sintaks

PM_COLLECT_PROC PmCollectProc;

DWORD PmCollectProc(
                 LPWSTR pValueName,
                 void **ppData,
                 DWORD *pcbTotalBytes,
                 DWORD *pNumObjectTypes
)
{...}

Parameter

pValueName

ppData

pcbTotalBytes

pNumObjectTypes

Mengembalikan nilai

Salah satu dari nilai berikut:

Menampilkan kode	Deskripsi
ERROR_MORE_DATA	Ukuran buffer pData (di mana pData mengacu pada pointer yang diacu oleh lppData) seperti yang ditentukan oleh lpcbTotalBytes tidak cukup besar untuk menyimpan data. Biarkan pData tidak berubah, dan atur lpcbTotalBytes dan lpNumObjectTypes ke nol. Tidak ada upaya yang dilakukan untuk menunjukkan ukuran buffer yang diperlukan, karena ini dapat berubah sebelum panggilan berikutnya.
ERROR_SUCCESS	Mengembalikan nilai ini dalam semua kasus selain kasus ERROR_MORE_DATA , meskipun tidak ada data yang dikembalikan atau terjadi kesalahan. Untuk melaporkan kesalahan selain ukuran buffer yang tidak cukup, gunakan Log Peristiwa Aplikasi.

Keterangan

Jika objek yang diminta yang ditentukan dalam parameter lpValueName tidak sesuai dengan indeks objek apa pun yang didukung DLL performa Anda, biarkan parameter pData tidak berubah (di mana pData mengacu pada pointer yang ditunjukkan oleh lppData), dan atur parameter lpcbTotalBytes dan lpNumObjectTypes ke nol. Ini menunjukkan bahwa tidak ada data yang dikembalikan.

Jika Anda mendukung satu atau beberapa objek yang dikueri, tentukan apakah ukuran buffer pData seperti yang ditentukan oleh lpcbTotalBytes cukup besar untuk menyimpan data. Jika tidak, biarkan pData tidak berubah, dan atur lpcbTotalBytes dan lpNumObjectTypes ke nol. Tidak ada upaya yang dilakukan untuk menunjukkan ukuran buffer yang diperlukan, karena ini dapat berubah sebelum panggilan berikutnya. Mengembalikan ERROR_MORE_DATA.

Jika pengumpulan data Anda memakan waktu, Anda hanya harus merespons kueri untuk objek tertentu, atau kueri yang mahal. Anda juga harus menurunkan prioritas utas yang mengumpulkan data, sehingga tidak berdampak buruk pada performa sistem. Untuk format string kueri, lihat Menggunakan Fungsi Registri untuk Mengonsumsi Data Penghitung.

Jika konsumen berjalan di komputer lain (dari jarak jauh), maka fungsi OpenPerformanceData, ClosePerformanceData, dan CollectPerformanceData dipanggil dalam konteks proses Winlogon, yang menangani sisi server koneksi jarak jauh. Perbedaan ini penting ketika memecahkan masalah yang hanya terjadi dari jarak jauh.

Setelah fungsi Anda berhasil dikembalikan, sistem dapat melakukan beberapa pengujian dasar untuk memastikan integritas data. Secara default, tidak ada pengujian yang dilakukan. Jika pengujian gagal, sistem menghasilkan pesan log peristiwa dan data dibuang untuk mencegah masalah lebih lanjut karena pointer yang tidak valid. Nilai registri berikut mengontrol tingkat pengujian: HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Perflib\ExtCounterTestLevel.

Berikut ini adalah kemungkinan tingkat pengujian untuk ExtCounterTestLevel.

Tingkat	Makna
1	Uji pointer dan buffer DLL penghitung tepercaya. Mengirim salinan buffer pengguna.
2	Penunjuk pengujian dan panjang buffer tetapi tidak menguji referensi pointer atau konten buffer. Mengirim salinan buffer pengguna.
3	Jangan menguji pointer atau buffer. Mengirim salinan buffer pengguna.
4	Jangan menguji pointer atau buffer. Mengirim buffer pengguna, bukan salinan. Ini adalah nilai default.

Pengujian berikut dilakukan pada tingkat 1 dan 2:

Memverifikasi bahwa nilai lpcbTotalBytes konsisten dengan penunjuk buffer yang dikembalikan, pData. Jika Anda menambahkan nilai lpcbTotalBytes ke penunjuk buffer asli yang diteruskan ke fungsi ini, Anda harus berakhir dengan penunjuk buffer yang sama yang dikembalikan oleh fungsi ini. Jika tidak sama, pesan kesalahan dicatat dan data diabaikan.
Verifikasi bahwa overrun buffer tidak terjadi. Sistem menambahkan halaman penjaga 1-KB sebelum dan sesudah buffer yang dialokasikan konsumen. Jika penunjuk buffer yang dikembalikan, pData, menunjuk melewati byte pertama dari halaman penjaga yang ditambahkan, maka diasumsikan bahwa buffer tidak valid dan data diabaikan. Jika penunjuk buffer melebihi akhir buffer, tetapi bukan akhir halaman penjaga, maka kesalahan overrun buffer dicatat. Jika penunjuk buffer melewati akhir halaman penjaga, maka kesalahan tumpukan dicatat karena tumpukan tempat buffer dialokasikan dapat rusak, menyebabkan kesalahan memori lainnya.
Verifikasi bahwa halaman penjaga belum rusak. Halaman penjaga 1-KB yang ditambahkan sebelum dan sesudah buffer diinisialisasi dengan pola data sebelum fungsi ini dipanggil. Pola data ini diperiksa setelah prosedur pengumpulan kembali. Jika ada perbedaan yang terdeteksi, buffer overrun atau kesalahan memori lainnya diasumsikan dan data diabaikan.

Pengujian berikut dilakukan hanya jika pengujian tingkat 1 digunakan:

Verifikasi bahwa jumlah setiap anggota TotalByteLength objek sama dengan nilai lpcbTotalBytes. Jika tidak, data diabaikan.
Verifikasi bahwa anggota ByteLength dari setiap instans konsisten. Panjangnya konsisten jika objek atau akhir buffer berikutnya mengikuti instans terakhir. Jika tidak, data diabaikan.

Contoh

Lihat Menerapkan CollectPerformanceData.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	winperf.h

Bagikan melalui