Función IoRegisterPlugPlayNotification (wdm.h)

Artículo
08/08/2023

La rutina IoRegisterPlugPlayNotification registra una rutina de devolución de llamada de notificación 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

Marcar bits que modifican la operación de registro. Entre los valores posibles se incluyen:

PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_INTERFACES

Solo es válido con un 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 a información adicional sobre los eventos para los que se está registrando CallbackRoutine. La información varía para distintos valores de EventCategory:

Cuando EventCategory es EventCategoryDeviceInterfaceChange, EventCategoryData debe apuntar a un GUID que especifique una clase de interfaz de dispositivo. callbackRoutine se llamará cuando se habilite o quite una interfaz de esa clase.
Cuando eventCategory 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 de PnP, esta llamada incrementa el recuento de referencias de 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 a la que se 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 de 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 Using PnP Notification and TARGET_DEVICE_CUSTOM_NOTIFICATION.

El parámetro context de la rutina de devolución de llamada contiene los datos de contexto proporcionados 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 de static Driver Verifier (SDV), consulte 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.

Observaciones

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 única rutina de devolución de llamada puede convertir el NotificationStructure a un PLUGPLAY_NOTIFICATION_HEADER y usar el campo evento de 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 una sola 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 quita 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, los controladores de Kernel-Mode Driver Framework (KMDF) deben llamar a ioRegisterPlugPlayNotification desde su EvtDeviceSelfManagedIoInit función de devolución de llamada y deben llamar a IoUnregisterPlugPlayNotification desde su EvtDeviceSelfManagedIoCleanup función de devolución de llamada. Estos controladores no deben llamar 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, vea Using PnP Notification.

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 va a definir. 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 Análisis de código para controladores, comprobador de controladores estáticos (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 de DRIVER_NOTIFICATION_CALLBACK_ROUTINE tal y 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 rol de función para controladores WDM. Para obtener información sobre _Use_decl_annotations_, vea Anotación del comportamiento de la función.

Requisitos

Requisito	Valor
de la plataforma de destino de	Universal
encabezado de	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
biblioteca de	NtosKrnl.lib
DLL de	NtosKrnl.exe
irQL	PASSIVE_LEVEL
reglas de cumplimiento de DDI	HwStorPortProhibitedDIs(storport), MarkPower(wdm), MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), powerIrpDDis(wdm)