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

裝置變更完整回呼例程不應封鎖，且不得呼叫產生 PnP 事件的同步例程。

PnP 管理員會在 IRQL = PASSIVE_LEVEL 呼叫裝置變更完成回呼例程。

[in, out] Context

選擇性地指向 PnP 管理員傳遞給 Callback 例程的呼叫端提供的內容結構。 呼叫端必須從非分頁記憶體配置這個結構。

傳回值

傳回碼 Description
STATUS_INVALID_DEVICE_REQUEST 呼叫端指定了系統 PnP 事件，例如GUID_TARGET_DEVICE_QUERY_REMOVE。 此例程僅適用於自定義事件。

備註

在 IoReportTargetDeviceChangeAsynchronous 例程通知 PnP 管理員在裝置上發生自定義事件之後，例程會立即傳回;當 PnP 管理員將事件的通知傳送給在裝置上註冊通知的驅動程式時，它不會等候。 請勿使用此例程來報告系統 PnP 事件，例如 GUID_TARGET_DEVICE_REMOVE_COMPLETE。

定義自定義裝置事件的驅動程式會呼叫 IoReportTargetDeviceChangeAsynchous ，以通知 PnP 管理員已發生自定義事件。 自定義通知可用於磁碟區標籤變更之類的事件。

自定義通知結構包含驅動程式定義的事件及其本身的 GUID。 驅動程式寫入器可以使用包含在 Microsoft Windows SDK) 中的 Uuidgen.exe 或 Guidgen.exe (來產生 GUID。

當驅動程式在處理事件、 IRP_MN_REMOVE_DEVICE或 IRP_MN_SURPRISE_REMOVAL時呼叫此例程時，PnP 管理員會在驅動程式傳回且堆疊回溯之後呼叫驅動程式的 Callback 例程。

IoReportTargetDeviceChangeAsynchronous 的呼叫端必須在 IRQL <= DISPATCH_LEVEL執行。 如果驅動程式寫入器在 IRQL = DISPATCH_LEVEL呼叫此例程，則必須從非分頁記憶體配置 NotificationStructure 。

規格需求

需求 值
目標平台 Universal
標頭 wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫 NtosKrnl.lib
Dll NtosKrnl.exe
IRQL <= DISPATCH_LEVEL (请参阅一节)
DDI 合規性規則 HwStorPortProhibitedDIS (storport)

另請參閱

IoReportTargetDeviceChange

TARGET_DEVICE_CUSTOM_NOTIFICATION