fungsi CM_Register_Notification (cfgmgr32.h)

Artikel
03/04/2024

Fungsi CM_Register_Notification mendaftarkan rutinitas panggilan balik aplikasi untuk dipanggil ketika peristiwa PnP dari jenis yang ditentukan terjadi.

Gunakan RegisterDeviceNotification alih-alih CM_Register_Notification jika kode Anda menargetkan Windows 7 atau versi Windows yang lebih lama. Pemanggil mode kernel harus menggunakan IoRegisterPlugPlayNotification sebagai gantinya.

Sintaks

CMAPI CONFIGRET CM_Register_Notification(
  [in]           PCM_NOTIFY_FILTER   pFilter,
  [in, optional] PVOID               pContext,
  [in]           PCM_NOTIFY_CALLBACK pCallback,
  [out]          PHCMNOTIFICATION    pNotifyContext
);

Parameter

[in] pFilter

Penunjuk ke struktur CM_NOTIFY_FILTER .

[in, optional] pContext

Penunjuk ke buffer yang dialokasikan penelepon yang berisi konteks yang akan diteruskan ke rutinitas panggilan balik di pCallback.

[in] pCallback

Penunjuk ke rutinitas yang akan dipanggil ketika peristiwa PnP yang ditentukan terjadi. Lihat bagian Keterangan untuk prototipe fungsi panggilan balik.

Parameter Tindakan rutin panggilan balik akan menjadi nilai dari enumerasi CM_NOTIFY_ACTION .

Setelah menerima pemberitahuan, bagaimana panggilan balik memeriksa pemberitahuan akan bergantung pada anggota FilterType dari parameter EventData rutin panggilan balik:

CM_NOTIFY_FILTER_TYPE_DEVICEINTERFACE

Panggilan balik harus memeriksa EventData-u.DeviceInterface>.

CM_NOTIFY_FILTER_TYPE_DEVICEHANDLE

Panggilan balik harus memeriksa EventData-u.DeviceHandle>.

CM_NOTIFY_FILTER_TYPE_DEVICEINSTANCE

Panggilan balik harus memeriksa EventData-u.DeviceInstance>.

[out] pNotifyContext

Penunjuk untuk menerima handel HCMNOTIFICATION yang sesuai dengan panggilan pendaftaran.

Nilai kembali

Jika operasi berhasil, fungsi akan mengembalikan CR_SUCCESS. Jika tidak, ia mengembalikan salah satu kode kesalahan awalan CR_ yang ditentukan dalam Cfgmgr32.h.

Keterangan

Pastikan untuk menangani peristiwa perangkat Plug and Play secepat mungkin. Jika penanganan aktivitas Anda melakukan operasi apa pun yang dapat memblokir eksekusi (seperti I/O), sebaiknya mulai utas lain untuk melakukan operasi secara asinkron.

Fungsi CM_Register_Notification tidak memberikan pemberitahuan tentang antarmuka perangkat yang ada. Untuk mengambil antarmuka yang ada, pertama-tama panggil CM_Register_Notification, lalu panggil CM_Get_Device_Interface_List. Jika antarmuka diaktifkan setelah driver Anda memanggil CM_Register_Notification, tetapi sebelum driver Anda memanggil CM_Get_Device_Interface_List, driver menerima pemberitahuan untuk kedatangan antarmuka, dan antarmuka juga muncul dalam daftar instans antarmuka perangkat yang dikembalikan oleh CM_Get_Device_Interface_List.

Handel HCMNOTIFICATION yang dikembalikan oleh CM_Register_Notification harus ditutup dengan memanggil fungsi CM_Unregister_Notification ketika tidak lagi diperlukan.

Rutinitas panggilan balik menggunakan prototipe fungsi berikut:

typedef __callback DWORD (CALLBACK *PCM_NOTIFY_CALLBACK)(
    _In_ HCMNOTIFICATION       hNotify,
    _In_opt_ PVOID             Context,
    _In_ CM_NOTIFY_ACTION      Action,
    _In_reads_bytes_(EventDataSize) PCM_NOTIFY_EVENT_DATA EventData,
    _In_ DWORD                 EventDataSize
    );

Jika menanggapi pemberitahuan CM_NOTIFY_ACTION_DEVICEQUERYREMOVE , panggilan balik PCM_NOTIFY_CALLBACK harus mengembalikan ERROR_SUCCESS atau ERROR_CANCELLED, sebagaimana mestinya. Jika tidak, panggilan balik harus mengembalikan ERROR_SUCCESS. Panggilan balik tidak boleh mengembalikan nilai lain. Untuk deskripsi tindakan lain, silakan lihat dokumentasi CM_NOTIFY_ACTION . Lihat juga CM_NOTIFY_EVENT_DATA untuk informasi tentang struktur yang diterima panggilan balik ini dalam parameter EventData .

Contoh

Misalnya, lihat Mendaftar untuk Pemberitahuan Kedatangan Antarmuka Perangkat dan Penghapusan Perangkat.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia di Microsoft Windows 8 dan versi Windows yang lebih baru.
Target Platform	Universal
Header	cfgmgr32.h (termasuk Cfgmgr32.h)
Pustaka	Cfgmgr32.lib; OneCoreUAP.lib di Windows 10
DLL	CfgMgr32.dll