Fungsi panggilan balik PERFLIBREQUEST (perflib.h)

Artikel
03/08/2023

Penyedia dapat menerapkan fungsi ini untuk menerima pemberitahuan ketika konsumen melakukan tindakan tertentu, seperti menambahkan atau menghapus penghitung dari kueri. PERFLIB memanggil panggilan balik sebelum permintaan konsumen selesai.

Jenis PERFLIBREQUEST mendefinisikan pointer ke fungsi panggilan balik ini. Fungsi ControlCallback adalah tempat penampung untuk nama fungsi yang ditentukan aplikasi.

Sintaks

PERFLIBREQUEST Perflibrequest;

ULONG Perflibrequest(
  [in] ULONG RequestCode,
  [in] PVOID Buffer,
  [in] ULONG BufferSize
)
{...}

Parameter

[in] RequestCode

Kode permintaan dapat menjadi salah satu nilai berikut.

Nilai	Makna
PERF_ADD_COUNTER	Konsumen menambahkan penghitung ke kueri. PERFLIB memanggil panggilan balik dengan kode permintaan ini untuk setiap penghitung yang ditambahkan ke kueri. Parameter Buffer berisi struktur PERF_COUNTER_IDENTITY yang mengidentifikasi penghitung yang ditambahkan. Penyedia dapat menggunakan pemberitahuan ini untuk mulai menghitung.
PERF_REMOVE_COUNTER	Konsumen menghapus penghitung dari kueri. PERFLIB memanggil panggilan balik dengan kode permintaan ini untuk setiap penghitung yang dihapus dari kueri. Parameter Buffer berisi struktur PERF_COUNTER_IDENTITY yang mengidentifikasi penghitung yang dihapus. Penyedia dapat menggunakan pemberitahuan ini untuk menghentikan penghitungan.
PERF_ENUM_INSTANCES	Konsumen menghitung instans set penghitung. Parameter Buffer berisi string Unicode yang dihentikan null yang mengidentifikasi nama komputer (atau alamat IP-nya) tempat konsumen menghitung instans.
PERF_COLLECT_START	Konsumen mulai mengumpulkan data penghitung. Parameter Buffer berisi string Unicode yang dihentikan null yang mengidentifikasi nama komputer (atau alamat IP-nya) tempat konsumen mengumpulkan data. Penyedia dapat menggunakan pemberitahuan ini jika status data mentah sangat penting (misalnya, penghitung terkait transaksi di mana pembaruan parsial tidak diizinkan). Pemberitahuan ini memberi penyedia kesempatan untuk menghapus semua pembaruan yang tertunda dan mengunci pembaruan di masa mendatang sebelum pengumpulan dimulai.
PERF_COLLECT_END	Pengumpulan data penghitung selesai. Parameter Buffer berisi string Unicode yang dihentikan null yang mengidentifikasi nama komputer (atau alamat IP-nya) tempat konsumen mengumpulkan data. Penyedia dapat menggunakan pemberitahuan ini untuk merilis kunci pembaruan yang diberlakukan oleh pemberitahuan mulai pengumpulan sehingga pembaruan pada data penghitung dapat dilanjutkan.

[in] Buffer

Konten buffer tergantung pada permintaan. Untuk kemungkinan konten, lihat parameter RequestCode .

[in] BufferSize

Ukuran, dalam byte, dari parameter Buffer .

Mengembalikan nilai

Kembalikan ERROR_SUCCESS jika panggilan balik berhasil.

Jika panggilan balik gagal, PERFLIB akan mengembalikan kode kesalahan kepada konsumen jika permintaan PERF_ADD_COUNTER, PERF_ENUM_INSTANCES, atau PERF_COLLECT_START; jika tidak, kode kesalahan diabaikan.

Keterangan

Jika atribut panggilan balik elemen penyedia adalah "kustom" atau Anda menggunakan argumen -NotificationCallback saat memanggil CTRPP, Anda harus menerapkan fungsi ini. Anda meneruskan nama fungsi panggilan balik Anda ke CounterInitialize.

Windows Vista: Fungsi CounterInitialize diberi nama PerfAutoInitialize. Alat CTRPP juga menghasilkan kerangka panggilan balik ini untuk Anda yang menyertakan semua kode permintaan. Anda kemudian menambahkan kode ke kode permintaan yang ingin Anda dukung dan hapus yang lain.

Panggilan balik harus selesai dalam satu detik. Jika panggilan balik tidak selesai tepat waktu, PERFLIB melanjutkan permintaan konsumen dan mengabaikan nilai pengembalian panggilan balik ketika selesai.

Contoh

Contoh berikut menunjukkan implementasi sederhana dari fungsi ControlCallback .

ULONG MyControlCallback(ULONG RequestCode, PVOID pBuffer, ULONG* pBufferSize)
{
    ULONG Status = ERROR_SUCCESS;
    PWNODE_HEADER Wnode = (PWNODE_HEADER)pBuffer;
    LPWSTR pComputerName = NULL;
    LPWSTR pInstance = NULL;
    PPERF_COUNTER_IDENTITY pCounter;
    UNREFERENCED_PARAMETER(pBufferSize);

    switch (RequestCode) 
    {
        case PERF_ADD_COUNTER:
            pCounter = (PPERF_COUNTER_IDENTITY)(((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            pComputerName = (LPWSTR)(((LPBYTE) pCounter) + pCounter->MachineOffset);
            pInstance = (pCounter->NameOffset > 0) 
                ? (LPWSTR) (((LPBYTE) pCounter) + pCounter->NameOffset) : NULL;
            
            break;

        case PERF_REMOVE_COUNTER: 
            pCounter = (PPERF_COUNTER_IDENTITY)(((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            pComputerName = (LPWSTR)(((LPBYTE) pCounter) + pCounter->MachineOffset);
            pInstance = (pCounter->NameOffset > 0)
                ? (LPWSTR) (((LPBYTE) pCounter) + pCounter->NameOffset) : NULL;
            
            break;

        case PERF_ENUM_INSTANCES:
            pComputerName = (LPWSTR) (((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            
            break;

        case PERF_COLLECT_START: 
            pComputerName = (LPWSTR) (((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            
            break;

        case PERF_COLLECT_END: 
            pComputerName = (LPWSTR) (((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            
            break;

        default:
            wprintf(L"Unknown request code, %lu\n", RequestCode);
    }

    return Status;
}

Persyaratan

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

Bagikan melalui