Función IoReportTargetDeviceChangeAsynchronous (wdm.h)

  • Artículo

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 la rutina vuelve, 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. El evento debe contener el GUID personalizado para el evento. Los demás campos de NotificationStructure deben rellenarse según corresponda para el evento personalizado.

El administrador de PnP rellena 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 a la que el administrador de PnP llama después de que termine de notificar a los controladores que se registraron para este evento personalizado.

La rutina de devolución de llamada tiene el tipo siguiente:

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 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 devolución de llamada. 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.

Comentarios

Una vez que la rutina IoReportTargetDeviceChangeAsynchronous 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.

Un controlador que define un evento de dispositivo personalizado llama a 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 el Microsoft Windows SDK).

Cuando un controlador llama a esta rutina mientras se controla un evento, un IRP_MN_REMOVE_DEVICE o 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 vuelva y la pila se 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, notificationStructure debe asignarse desde memoria no paginada.

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 <= DISPATCH_LEVEL (consulte la sección Comentarios)
Reglas de cumplimiento de DDI HwStorPortProhibitedDDIs(storport)

Consulte también

IoReportTargetDeviceChange

TARGET_DEVICE_CUSTOM_NOTIFICATION