Función IoReportTargetDeviceChangeAsynchronous (wdm.h)
La rutina IoReportTargetDeviceChangeAsynchronous notifica al administrador de PnP que se ha producido un evento personalizado en un dispositivo.
Sintaxis
NTSTATUS IoReportTargetDeviceChangeAsynchronous(
[in] PDEVICE_OBJECT PhysicalDeviceObject,
[in] PVOID NotificationStructure,
[in, optional] PDEVICE_CHANGE_COMPLETE_CALLBACK Callback,
[in, out] PVOID Context
);
Parámetros
[in] PhysicalDeviceObject
Puntero al PDO del dispositivo que se está notificando.
[in] NotificationStructure
Puntero a una estructura de TARGET_DEVICE_CUSTOM_NOTIFICATION proporcionada por el autor de la llamada que describe el evento personalizado. El administrador de PnP envía esta estructura a los controladores registrados para la notificación del evento.
Esta estructura proporcionada por el autor de la llamada se puede liberar una vez que se devuelve la rutina, ya que el administrador de PnP realiza una copia superficial y usa la copia para notificar a los controladores. El administrador de PnP libera automáticamente la copia una vez que ya no es necesaria. Consulte la sección Comentarios sobre los requisitos del grupo de asignación.
NotificationStructure. FileObject debe ser null. NotificationStructure. de eventos debe contener el GUID personalizado para el evento. Los demás campos del NotificationStructure deben rellenarse según corresponda para el evento personalizado.
El administrador de PnP rellena el NotificationStructure.campo FileObject cuando envía notificaciones a los registradores.
[in, optional] Callback
Opcionalmente, apunta a una rutina proporcionada por el autor de la llamada que el administrador de PnP llama después de que termine de notificar a los controladores registrados para este evento personalizado.
La rutina de devolución de llamada tiene el siguiente tipo:
typedef
VOID
(*PDEVICE_CHANGE_COMPLETE_CALLBACK)(
IN PVOID Context
);
Una rutina de devolución de llamada completa de cambio de dispositivo no debe bloquearse y no debe llamar a rutinas sincrónicas que generen eventos PnP.
El administrador de PnP llama a rutinas de devolución de llamada de device-change-complete en IRQL = PASSIVE_LEVEL.
[in, out] Context
Opcionalmente, apunta a una estructura de contexto proporcionada por el autor de la llamada que el administrador de PnP pasa a la rutina de devolución de llamada de . El autor de la llamada debe asignar esta estructura de la memoria no paginada.
Valor devuelto
| Código devuelto | Descripción |
|---|---|
| STATUS_INVALID_DEVICE_REQUEST | El autor de la llamada especificó un evento PnP del sistema, como GUID_TARGET_DEVICE_QUERY_REMOVE. Esta rutina solo es para eventos personalizados. |
Observaciones
Después de que el ioReportTargetDeviceChangeAsynchronous rutina notifica al administrador de PnP que se ha producido un evento personalizado en un dispositivo, la rutina vuelve inmediatamente; no espera mientras el administrador de PnP envía la notificación del evento a los controladores registrados para la notificación en el dispositivo. No use esta rutina para notificar eventos PnP del sistema, como GUID_TARGET_DEVICE_REMOVE_COMPLETE.
Controlador que define una llamada a eventos de dispositivo personalizado ioReportTargetDeviceChangeAsynchronous para informar al administrador de PnP de que se ha producido el evento personalizado. La notificación personalizada se puede usar para eventos como un cambio de etiqueta de volumen.
La estructura de notificación personalizada contiene un evento definido por el controlador con su propio GUID. Los escritores de controladores pueden generar GUID con Uuidgen.exe o Guidgen.exe (que se incluyen en Microsoft Windows SDK).
Cuando un controlador llama a esta rutina mientras controla un evento, un IRP_MN_REMOVE_DEVICEo un IRP_MN_SURPRISE_REMOVAL, el administrador de PnP llama a la rutina de devolución de llamada del controlador después de que el controlador devuelva y la pila desenrede.
Los autores de llamadas de ioReportTargetDeviceChangeAsynchronous deben ejecutarse en IRQL <= DISPATCH_LEVEL. Si un escritor de controladores llama a esta rutina en IRQL = DISPATCH_LEVEL, el NotificationStructure debe asignarse desde la memoria no paginada.