IoRegisterPlugPlayNotification
The IoRegisterPlugPlayNotification routine registers a driver callback routine to be called when a PnP event of the specified category occurs.
NTSTATUS
IoRegisterPlugPlayNotification(
IN IO_NOTIFICATION_EVENT_CATEGORY EventCategory,
IN ULONG EventCategoryFlags,
IN PVOID EventCategoryData OPTIONAL,
IN PDRIVER_OBJECT DriverObject,
IN PDRIVER_NOTIFICATION_CALLBACK_ROUTINE CallbackRoutine,
IN PVOID Context,
OUT PVOID *NotificationEntry
);
Parameters
EventCategory
Specifies the category of PnP event for which the callback routine is being registered. EventCategory must be one of the following:
EventCategoryDeviceInterfaceChange
PnP events in this category include the arrival (enabling) of a new instance of a device interface class (GUID_DEVICE_INTERFACE_ARRIVAL), or the removal (disabling) of an existing device interface instance (GUID_DEVICE_INTERFACE_REMOVAL).
EventCategoryHardwareProfileChange
PnP events in this category include query-change (GUID_HWPROFILE_QUERY_CHANGE), change-complete (GUID_HWPROFILE_CHANGE_COMPLETE), and change-cancel (GUID_HWPROFILE_CHANGE_CANCELLED) of a hardware profile.
EventCategoryTargetDeviceChange
PnP events in this category include events related to removing a device: the device's drivers received a query-remove IRP (GUID_TARGET_DEVICE_QUERY_REMOVE), the drivers completed a remove IRP (GUID_TARGET_DEVICE_REMOVE_COMPLETE), or the drivers received a cancel-remove IRP (GUID_TARGET_DEVICE_REMOVE_CANCELLED). This category is also used for custom notification events.
EventCategoryFlags
Specifies flags that modify the registration operation. Possible values include:
PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_INTERFACES
Only valid with an EventCategory of EventCategoryDeviceInterfaceChange. If set, the PnP Manager calls the driver callback routine for each device interface instance that is currently registered and active and registers the callback routine for future arrivals or removals of device interface instances.
EventCategoryData
Pointer to further information about the events for which CallbackRoutine is being registered. The information varies for different EventCategory values:
When EventCategory is EventCategoryDeviceInterfaceChange, EventCategoryData must point to a GUID specifying a device interface class. CallbackRoutine will be called when an interface of that class is enabled or removed.
When EventCategory is EventCategoryHardwareProfileChange, EventCategoryData must be NULL.
When EventCategory is EventCategoryTargetDeviceChange, EventCategoryData must point to the file object for which PnP notification is requested.
DriverObject
Pointer to the caller's driver object.
To ensure that the driver remains loaded while it is registered for PnP notification, this call increments the reference count on DriverObject. The PnP Manager decrements the reference count when this registration is removed.
CallbackRoutine
Pointer to the routine to be called when the specified PnP event occurs.
A callback routine has the following type:
typedef NTSTATUS (*PDRIVER_NOTIFICATION_CALLBACK_ROUTINE) (
IN PVOID NotificationStructure,
IN PVOID Context
);
The NotificationStructure is specific to the EventCategory. For example, a callback routine for an EventCategoryDeviceInterfaceChange receives a DEVICE_INTERFACE_CHANGE_NOTIFICATION structure.
The Context parameter contains the context data the driver supplied during registration.
The PnP Manager calls driver callback routines at IRQL = PASSIVE_LEVEL.
Context
Pointer to a caller-allocated buffer containing context that the PnP Manager passes to the callback routine.
NotificationEntry
Pointer to an opaque value returned by this call that identifies the registration. Pass this value to IoUnregisterPlugPlayNotification to remove the registration.
Return Value
IoRegisterPlugPlayNotification returns STATUS_SUCCESS or an appropriate error status.