Función IoRegisterPlugPlayNotification (wdm.h)

Artículo
08/08/2023

La rutina IoRegisterPlugPlayNotification registra una rutina de devolución de llamada de notificación de Plug and Play (PnP) que se llamará cuando se produce un evento PnP de la categoría especificada.

Sintaxis

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
);

Parámetros

[in] EventCategory

Especifica un valor de enumeración de IO_NOTIFICATION_EVENT_CATEGORY que indica la categoría del evento PnP para el que se está registrando la rutina de devolución de llamada.

[in] EventCategoryFlags

Marca bits que modifican la operación de registro. Los valores posibles son:

PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_INTERFACES

Solo es válido con eventCategory de EventCategoryDeviceInterfaceChange. Si se establece, el administrador de PnP llama a la rutina de devolución de llamada del controlador para cada instancia de interfaz de dispositivo registrada actualmente y activa y registra la rutina de devolución de llamada para futuras llegadas o eliminaciones de instancias de interfaz de dispositivo.

[in, optional] EventCategoryData

Puntero para obtener más información sobre los eventos para los que se está registrando CallbackRoutine . La información varía según los distintos valores de EventCategory :

Cuando EventCategory es EventCategoryDeviceInterfaceChange, EventCategoryData debe apuntar a un GUID que especifique una clase de interfaz de dispositivo. Se llamará a CallbackRoutine cuando se habilite o quite una interfaz de esa clase.
Cuando EventCategory es EventCategoryHardwareProfileChange, EventCategoryData debe ser NULL.
Cuando EventCategory es EventCategoryTargetDeviceChange, EventCategoryData debe apuntar al objeto de archivo para el que se solicita la notificación PnP.

[in] DriverObject

Puntero al objeto de controlador del autor de la llamada.

Para asegurarse de que el controlador permanece cargado mientras está registrado para la notificación PnP, esta llamada incrementa el recuento de referencias en DriverObject. El administrador de PnP disminuye el recuento de referencias cuando se quita este registro.

Para EventCategoryTargetDeviceChange, DriverObject no debe ser el objeto de controlador del dispositivo de destino; en su lugar, debe ser el objeto de controlador del controlador que implementa CallbackRoutine.

[in] CallbackRoutine

Puntero a la rutina de devolución de llamada de notificación PnP que se va a llamar cuando se produce el evento PnP especificado.

El prototipo de función para esta rutina de devolución de llamada se define de la siguiente manera:

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

La rutina de devolución de llamada NotificationStructure es específica del valor EventCategory , como se muestra en la tabla siguiente.

Categoría de eventos	Estructura de notificaciones
EventCategoryDeviceInterfaceChange	DEVICE_INTERFACE_CHANGE_NOTIFICATION
EventCategoryHardwareProfileChange	HWPROFILE_CHANGE_NOTIFICATION
EventCategoryTargetDeviceChange	TARGET_DEVICE_REMOVAL_NOTIFICATION Para obtener más información, consulte Uso de notificaciones PnP y TARGET_DEVICE_CUSTOM_NOTIFICATION.

El parámetro Context de la rutina de devolución de llamada contiene los datos de contexto proporcionados por el controlador durante el registro.

Para obtener información sobre cómo incluir una declaración de función para la rutina de devolución de llamada que cumple los requisitos del comprobador de controladores estáticos (SDV), vea Ejemplos.

El administrador de PnP llama a las rutinas de devolución de llamada del controlador en IRQL = PASSIVE_LEVEL.

[in, optional] Context

Puntero a un búfer asignado por el autor de la llamada que contiene el contexto que el administrador de PnP pasa a la rutina de devolución de llamada.

[out] NotificationEntry

Puntero a un valor opaco devuelto por esta llamada que identifica el registro. Pase este valor a la rutina IoUnregisterPlugPlayNotificationEx para quitar el registro.

Valor devuelto

IoRegisterPlugPlayNotification devuelve STATUS_SUCCESS o un estado de error adecuado.

Comentarios

Un controlador se registra para una categoría de eventos. Cada categoría incluye uno o varios tipos de eventos PnP.

Un controlador puede registrar diferentes rutinas de devolución de llamada para diferentes categorías de eventos o puede registrar una sola rutina de devolución de llamada. Una sola rutina de devolución de llamada puede convertir NotificationStructure en un PLUGPLAY_NOTIFICATION_HEADER y usar el campo Evento para determinar el tipo exacto de la estructura de notificación.

Si el autor de la llamada especifica PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_INTERFACES, el sistema operativo podría llamar a la rutina de devolución de llamada de notificación PnP dos veces para un único evento EventCategoryDeviceInterfaceChange para una interfaz existente. Puede omitir de forma segura la segunda llamada a la devolución de llamada. El sistema operativo no llamará a la devolución de llamada más de dos veces para un único evento.

Las rutinas de devolución de llamada de notificación PnP deben completar sus tareas lo antes posible y devolver el control al administrador de PnP, para evitar retrasos en notificar a otros controladores y aplicaciones que se han registrado para el evento.

El administrador de PnP no saca una referencia en el objeto de archivo cuando un controlador se registra para recibir una notificación de un evento EventCategoryTargetDeviceChange . Si la rutina de devolución de llamada de notificación PnP del controlador requiere acceso al objeto de archivo, el controlador debe sacar una referencia adicional en el objeto de archivo antes de llamar a IoRegisterPlugPlayNotification.

Normalmente, Kernel-Mode controladores de Driver Framework (KMDF) deben llamar a IoRegisterPlugPlayNotification desde su función de devolución de llamada EvtDeviceSelfManagedIoInit y deben llamar a IoUnregisterPlugPlayNotification desde su función de devolución de llamada EvtDeviceSelfManagedIoCleanup . Estos controladores no deben llamar a IoRegisterPlugPlayNotification desde su función de devolución de llamada EvtDriverDeviceAdd ; De lo contrario, PnP podría llamar a la rutina de devolución de llamada de notificación PnP antes de que PnP inicie la pila de controladores, en cuyo caso el controlador no estará preparado para controlar la notificación.

Para obtener más información, consulte Uso de la notificación PnP.

Ejemplos

Para definir una rutina de devolución de llamada de notificación PnP, primero debe proporcionar una declaración de función que identifique el tipo de rutina de devolución de llamada que está definiendo. Windows proporciona un conjunto de tipos de función de devolución de llamada para controladores. Declarar una función mediante los tipos de función de devolución de llamada ayuda a Code Analysis for Drivers, Static Driver Verifier (SDV) y otras herramientas de comprobación encuentran errores y es un requisito para escribir controladores para el sistema operativo Windows.

Por ejemplo, para definir una rutina de devolución de llamada de notificación PnP denominada MyCallbackRoutine, use el tipo DRIVER_NOTIFICATION_CALLBACK_ROUTINE como se muestra en este ejemplo de código:

DRIVER_NOTIFICATION_CALLBACK_ROUTINE MyCallbackRoutine;

A continuación, implemente la rutina de devolución de llamada de la siguiente manera:

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

El tipo de función DRIVER_NOTIFICATION_CALLBACK_ROUTINE se define en el archivo de encabezado Wdm.h. Para identificar con más precisión los errores al ejecutar las herramientas de análisis de código, asegúrese de agregar la anotación Use_decl_annotations a la definición de función. La anotación Use_decl_annotations garantiza que se usen las anotaciones que se aplican al tipo de función DRIVER_NOTIFICATION_CALLBACK_ROUTINE en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, vea Declarar funciones mediante tipos de roles de función para controladores WDM. Para obtener información sobre _Use_decl_annotations_, consulte Anotación del comportamiento de la función.

Requisitos

Requisito	Value
Plataforma de destino	Universal
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de DDI	HwStorPortProhibitedDIs(storport), MarkPower(wdm), MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), PowerIrpDDis(wdm)