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 マネージャーが コールバック ルーチンに渡す呼び出し元が指定したコンテキスト構造を指します。 呼び出し元は、非ページ メモリからこの構造体を割り当てる必要があります。
戻り値
| リターン コード | 説明 |
|---|---|
| STATUS_INVALID_DEVICE_REQUEST | 呼び出し元は、GUID_TARGET_DEVICE_QUERY_REMOVEなどのシステム PnP イベントを指定しました。 このルーチンは、カスタム イベント専用です。 |
注釈
IoReportTargetDeviceChangeAsynchronous ルーチンは、デバイスでカスタム イベントが発生したことを PnP マネージャーに通知した後、ルーチンは直ちにを返します。PnP マネージャーがデバイスで通知を登録したドライバーにイベントの通知を送信している間は待機しません。 このルーチンを使用して、GUID_TARGET_DEVICE_REMOVE_COMPLETEなどのシステム PnP イベントを報告しないでください。
カスタム デバイス イベントを定義するドライバーは 、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 を割り当てる必要があります。
要件
| 要件 | 値 |
|---|---|
| 対象プラットフォーム | ユニバーサル |
| Header | wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | <= DISPATCH_LEVEL (「解説」セクションを参照) |
| DDI コンプライアンス規則 | HwStorPortProhibitedDDIs(storport) |