Fungsi IoRegisterPlugPlayNotification (wdm.h)

Artikel
02/27/2024

Rutinitas IoRegisterPlugPlayNotification mendaftarkan rutinitas panggilan balik pemberitahuan Plug and Play (PnP) untuk dipanggil ketika peristiwa PnP dari kategori yang ditentukan terjadi.

Sintaks

NTSTATUS IoRegisterPlugPlayNotification(
  [in]           IO_NOTIFICATION_EVENT_CATEGORY        EventCategory,
  [in]           ULONG                                 EventCategoryFlags,
  [in, optional] PVOID                                 EventCategoryData,
  [in]           PDRIVER_OBJECT                        DriverObject,
  [in]           PDRIVER_NOTIFICATION_CALLBACK_ROUTINE CallbackRoutine,
  [in, optional] __drv_aliasesMem PVOID                Context,
  [out]          PVOID                                 *NotificationEntry
);

Parameter

[in] EventCategory

Menentukan nilai enumerasi dari IO_NOTIFICATION_EVENT_CATEGORY yang menunjukkan kategori peristiwa PnP yang rutinitas panggilan baliknya sedang didaftarkan.

[in] EventCategoryFlags

Benderai bit yang mengubah operasi pendaftaran. Nilai yang mungkin termasuk:

PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_INTERFACES

Hanya valid dengan EventCategory dari EventCategoryDeviceInterfaceChange. Jika diatur, manajer PnP memanggil rutinitas panggilan balik driver untuk setiap instans antarmuka perangkat yang saat ini terdaftar dan aktif dan mendaftarkan rutinitas panggilan balik untuk kedatangan di masa mendatang atau penghapusan instans antarmuka perangkat.

[in, optional] EventCategoryData

Pointer untuk informasi lebih lanjut tentang peristiwa di mana CallbackRoutine sedang didaftarkan. Informasi bervariasi untuk nilai EventCategory yang berbeda:

Ketika EventCategory adalah EventCategoryDeviceInterfaceChange, EventCategoryData harus menunjuk ke GUID yang menentukan kelas antarmuka perangkat. CallbackRoutine akan dipanggil ketika antarmuka kelas tersebut diaktifkan atau dihapus.
Ketika EventCategory adalah EventCategoryHardwareProfileChange, EventCategoryData harus NULL.
Ketika EventCategory adalah EventCategoryTargetDeviceChange, EventCategoryData harus menunjuk ke objek file tempat pemberitahuan PnP diminta.

[in] DriverObject

Penunjuk ke objek driver penelepon.

Untuk memastikan bahwa driver tetap dimuat saat terdaftar untuk pemberitahuan PnP, panggilan ini menaikkan jumlah referensi pada DriverObject. Manajer PnP mengurangi jumlah referensi ketika pendaftaran ini dihapus.

Untuk EventCategoryTargetDeviceChange, DriverObject tidak boleh menjadi objek driver perangkat target; sebaliknya, itu harus menjadi objek driver driver yang mengimplementasikan CallbackRoutine.

[in] CallbackRoutine

Penunjuk ke rutinitas panggilan balik pemberitahuan PnP untuk dipanggil ketika peristiwa PnP yang ditentukan terjadi.

Prototipe fungsi untuk rutinitas panggilan balik ini didefinisikan sebagai berikut:

typedef NTSTATUS
  DRIVER_NOTIFICATION_CALLBACK_ROUTINE(
    _In_ PVOID NotificationStructure,
    _Inout_opt_ PVOID Context
    );

NotificationStructure rutin panggilan balik khusus untuk nilai EventCategory, seperti yang ditunjukkan dalam tabel berikut.

Kategori kejadian	Struktur pemberitahuan
EventCategoryDeviceInterfaceChange	DEVICE_INTERFACE_CHANGE_NOTIFICATION
EventCategoryHardwareProfileChange	HWPROFILE_CHANGE_NOTIFICATION
EventCategoryTargetDeviceChange	TARGET_DEVICE_REMOVAL_NOTIFICATION Untuk informasi selengkapnya, lihat Menggunakan Pemberitahuan PnP dan TARGET_DEVICE_CUSTOM_NOTIFICATION.

Parameter Konteks rutin panggilan balik berisi data konteks yang disediakan driver selama pendaftaran.

Untuk informasi tentang menyertakan deklarasi fungsi untuk rutinitas panggilan balik yang memenuhi persyaratan Pemverifikasi Driver Statis (SDV), lihat Contoh.

Manajer PnP memanggil rutinitas panggilan balik driver di IRQL = PASSIVE_LEVEL.

[in, optional] Context

Penunjuk ke buffer yang dialokasikan penelepon yang berisi konteks yang diteruskan manajer PnP ke rutinitas panggilan balik.

[out] NotificationEntry

Pointer ke nilai buram yang dikembalikan oleh panggilan ini yang mengidentifikasi pendaftaran. Teruskan nilai ini ke rutinitas IoUnregisterPlugPlayNotificationEx untuk menghapus pendaftaran.

Mengembalikan nilai

IoRegisterPlugPlayNotification mengembalikan STATUS_SUCCESS atau status kesalahan yang sesuai.

Keterangan

Driver mendaftar untuk kategori peristiwa. Setiap kategori mencakup satu atau beberapa jenis peristiwa PnP.

Driver dapat mendaftarkan rutinitas panggilan balik yang berbeda untuk kategori peristiwa yang berbeda atau dapat mendaftarkan satu rutinitas panggilan balik. Rutinitas panggilan balik tunggal dapat melemparkan NotificationStructure ke PLUGPLAY_NOTIFICATION_HEADER dan menggunakan bidang Peristiwa untuk menentukan jenis struktur pemberitahuan yang tepat.

Jika penelepon menentukan PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_INTERFACES, sistem operasi mungkin memanggil rutinitas panggilan balik pemberitahuan PnP dua kali untuk satu peristiwa EventCategoryDeviceInterfaceChange untuk antarmuka yang ada. Anda dapat mengabaikan panggilan kedua dengan aman ke panggilan balik. Sistem operasi tidak akan memanggil panggilan balik lebih dari dua kali untuk satu peristiwa.

Rutinitas panggilan balik pemberitahuan PnP harus menyelesaikan tugas mereka secepat mungkin dan mengembalikan kontrol ke manajer PnP, untuk mencegah keterlambatan dalam memberi tahu driver dan aplikasi lain yang telah mendaftar untuk acara tersebut.

Manajer PnP tidak mengambil referensi pada objek file ketika driver mendaftar untuk pemberitahuan peristiwa EventCategoryTargetDeviceChange . Jika rutinitas panggilan balik pemberitahuan PnP driver memerlukan akses ke objek file, driver harus mengambil referensi tambahan pada objek file sebelum memanggil IoRegisterPlugPlayNotification.

Biasanya, driver Kernel-Mode Driver Framework (KMDF) harus memanggil IoRegisterPlugPlayNotification dari fungsi panggilan balik EvtDeviceSelfManagedIoInit mereka, dan harus memanggil IoUnregisterPlugPlayNotification dari fungsi panggilan balik EvtDeviceSelfManagedIoCleanup mereka. Driver ini tidak boleh memanggil IoRegisterPlugPlayNotification dari fungsi panggilan balik EvtDriverDeviceAdd mereka; jika tidak, rutinitas panggilan balik pemberitahuan PnP mungkin dipanggil sebelum tumpukan driver dimulai oleh PnP, dalam hal ini driver tidak akan siap untuk menangani pemberitahuan.

Untuk informasi selengkapnya, lihat Menggunakan Pemberitahuan PnP.

Contoh

Untuk menentukan rutinitas panggilan balik pemberitahuan PnP, Anda harus terlebih dahulu memberikan deklarasi fungsi yang mengidentifikasi jenis rutinitas panggilan balik yang Anda tentukan. Windows menyediakan sekumpulan tipe fungsi panggilan balik untuk driver. Mendeklarasikan fungsi menggunakan jenis fungsi panggilan balik membantu Analisis Kode untuk Driver, Pemverifikasi Driver Statis (SDV), dan alat verifikasi lainnya menemukan kesalahan, dan itu adalah persyaratan untuk menulis driver untuk sistem operasi Windows.

Misalnya, untuk menentukan rutinitas panggilan balik pemberitahuan PnP yang diberi nama MyCallbackRoutine, gunakan jenis DRIVER_NOTIFICATION_CALLBACK_ROUTINE seperti yang ditunjukkan dalam contoh kode ini:

DRIVER_NOTIFICATION_CALLBACK_ROUTINE MyCallbackRoutine;

Kemudian, terapkan rutinitas panggilan balik Anda sebagai berikut:

_Use_decl_annotations_
NTSTATUS
  MyCallbackRoutine(
    PVOID NotificationStructure,
    PVOID Context
    )
  {
      // Function body
  }

Jenis fungsi DRIVER_NOTIFICATION_CALLBACK_ROUTINE didefinisikan dalam file header Wdm.h. Untuk mengidentifikasi kesalahan secara lebih akurat saat Anda menjalankan alat analisis kode, pastikan untuk menambahkan anotasi Use_decl_annotations ke definisi fungsi Anda. Anotasi Use_decl_annotations memastikan bahwa anotasi yang diterapkan ke jenis fungsi DRIVER_NOTIFICATION_CALLBACK_ROUTINE dalam file header digunakan. Untuk informasi selengkapnya tentang persyaratan untuk deklarasi fungsi, lihat Mendeklarasikan Fungsi dengan Menggunakan Jenis Peran Fungsi untuk Driver WDM. Untuk informasi tentang _Use_decl_annotations_, lihat Menganotasi Perilaku Fungsi.

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Header	wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Aturan kepatuhan DDI	HwStorPortProhibitedDDIs(storport), MarkPower(wdm), MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), PowerIrpDDis(wdm)