IoReportTargetDeviceChangeAsynchronous 函数 (wdm.h)

  • 项目

IoReportTargetDeviceChangeAsynchronous 例程通知 PnP 管理器，设备上发生了自定义事件。

语法

NTSTATUS IoReportTargetDeviceChangeAsynchronous(
  [in]           PDEVICE_OBJECT                   PhysicalDeviceObject,
  [in]           PVOID                            NotificationStructure,
  [in, optional] PDEVICE_CHANGE_COMPLETE_CALLBACK Callback,
  [in, out]      PVOID                            Context
);

参数

[in] PhysicalDeviceObject

指向所报告设备的 PDO 的指针。

[in] NotificationStructure

指向调用方提供的描述自定义事件的 TARGET_DEVICE_CUSTOM_NOTIFICATION 结构的指针。 PnP 管理器将此结构发送给注册事件通知的驱动程序。

在例程返回后，可以释放调用方提供的此结构，因为 PnP 管理器会创建浅表复制并使用副本通知驱动程序。 不再需要副本后，PnP 管理器会自动释放该副本。 请参阅有关分配池要求的备注部分。

NotificationStructure。FileObject 必须为 NULL。 NotificationStructure。事件 必须包含事件的自定义 GUID。 必须根据自定义事件填写 NotificationStructure 的其他字段。

PnP 管理器将填充 NotificationStructure。向注册者发送通知时的 FileObject 字段。

[in, optional] Callback

（可选）指向调用方提供的例程，PnP 管理器在完成通知为此自定义事件注册的驱动程序后调用该例程。

回调例程具有以下类型：

typedef
VOID
(*PDEVICE_CHANGE_COMPLETE_CALLBACK)(
    IN PVOID Context
    );

device-change-complete 回调例程不应阻止，也不得调用生成 PnP 事件的同步例程。

PnP 管理器在 IRQL = PASSIVE_LEVEL 调用 device-change-complete 回调例程。

[in, out] Context

（可选）指向调用方提供的上下文结构，PnP 管理器将该结构传递给 回调 例程。 调用方必须从非分页内存中分配此结构。

返回值

返回代码 说明
STATUS_INVALID_DEVICE_REQUEST 调用方指定了系统 PnP 事件，例如GUID_TARGET_DEVICE_QUERY_REMOVE。 此例程仅适用于自定义事件。

注解

IoReportTargetDeviceChangeAsynchronous 例程通知 PnP 管理器设备上发生了自定义事件后，例程将立即返回;当 PnP 管理器将事件的通知发送给在设备上注册通知的驱动程序时，它不会等待。 请勿使用此例程来报告系统 PnP 事件，例如GUID_TARGET_DEVICE_REMOVE_COMPLETE。

定义自定义设备事件的驱动程序调用 IoReportTargetDeviceChangeAsynchronous ，以通知 PnP 管理员自定义事件已发生。 自定义通知可用于卷标签更改等事件。

自定义通知结构包含驱动程序定义的事件及其自己的 GUID。 驱动程序编写器可以使用Microsoft Windows SDK) 中包含的 Uuidgen.exe 或 Guidgen.exe (生成 GUID。

当驱动程序在处理事件、 IRP_MN_REMOVE_DEVICE或 IRP_MN_SURPRISE_REMOVAL时调用此例程时，PnP 管理器会在驱动程序返回且堆栈展开后调用驱动程序的 回调 例程。

IoReportTargetDeviceChangeAsynchronous 的调用方必须在 IRQL <= DISPATCH_LEVEL 运行。 如果驱动程序编写器在 IRQL = DISPATCH_LEVEL 调用此例程，则必须从非分页内存中分配 NotificationStructure 。

要求

要求 值
目标平台 通用
标头 wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL <= DISPATCH_LEVEL (请参阅备注部分)
DDI 符合性规则 HwStorPortProhibitedDDI (storport)

另请参阅

IoReportTargetDeviceChange

TARGET_DEVICE_CUSTOM_NOTIFICATION