Fungsi IoReportTargetDeviceChangeAsynchronous (wdm.h)

  • Artikel

Rutinitas IoReportTargetDeviceChangeAsynchronous memberi tahu manajer PnP bahwa peristiwa kustom telah terjadi pada perangkat.

Sintaks

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

Parameter

[in] PhysicalDeviceObject

Arahkan ke PDO perangkat yang sedang dilaporkan.

[in] NotificationStructure

Penunjuk ke struktur TARGET_DEVICE_CUSTOM_NOTIFICATION yang disediakan penelepon yang menjelaskan peristiwa kustom. Manajer PnP mengirimkan struktur ini ke driver yang terdaftar untuk pemberitahuan peristiwa.

Struktur yang disediakan penelepon ini dapat dibebaskan setelah rutin kembali, karena manajer PnP membuat salinan dangkal dan menggunakan salinan untuk memberi tahu driver. Salinan secara otomatis dibebaskan oleh manajer PnP setelah tidak lagi diperlukan. Lihat bagian Keterangan tentang persyaratan kumpulan alokasi.

NotificationStructure. FileObject harus NULL. NotificationStructure. Peristiwa harus berisi GUID kustom untuk peristiwa tersebut. Bidang lain dari NotificationStructure harus diisi sebagaimana mestinya untuk peristiwa kustom.

Manajer PnP mengisi NotificationStructure. Bidang FileObject saat mengirim pemberitahuan ke pendaftar.

[in, optional] Callback

Secara opsional menunjuk ke rutinitas yang disediakan penelepon yang dipanggil manajer PnP setelah selesai memberi tahu driver yang terdaftar untuk peristiwa kustom ini.

Rutinitas panggilan balik memiliki jenis berikut:

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

Rutinitas panggilan balik perangkat-ubah-selesai tidak boleh memblokir dan tidak boleh memanggil rutinitas sinkron yang menghasilkan peristiwa PnP.

Manajer PnP memanggil rutinitas panggilan balik device-change-complete di IRQL = PASSIVE_LEVEL.

[in, out] Context

Secara opsional menunjuk ke struktur konteks yang disediakan penelepon yang diteruskan manajer PnP ke rutinitas Callback . Pemanggil harus mengalokasikan struktur ini dari memori yang tidak di-halaman.

Nilai kembali

Menampilkan kode Deskripsi
STATUS_INVALID_DEVICE_REQUEST Pemanggil menentukan peristiwa PnP sistem, seperti GUID_TARGET_DEVICE_QUERY_REMOVE. Rutinitas ini hanya untuk peristiwa kustom.

Keterangan

Setelah rutinitas IoReportTargetDeviceChangeAsynchronous memberi tahu manajer PnP bahwa peristiwa kustom telah terjadi pada perangkat, rutinitas segera kembali; tidak menunggu sementara manajer PnP mengirimkan pemberitahuan peristiwa ke driver yang terdaftar untuk pemberitahuan pada perangkat. Jangan gunakan rutinitas ini untuk melaporkan peristiwa PnP sistem, seperti GUID_TARGET_DEVICE_REMOVE_COMPLETE.

Driver yang mendefinisikan peristiwa perangkat kustom memanggil IoReportTargetDeviceChangeAsynchronous untuk memberi tahu manajer PnP bahwa peristiwa kustom telah terjadi. Pemberitahuan kustom dapat digunakan untuk peristiwa seperti perubahan label volume.

Struktur pemberitahuan kustom berisi peristiwa yang ditentukan driver dengan GUID-nya sendiri. Penulis driver dapat menghasilkan GUID dengan Uuidgen.exe atau Guidgen.exe (yang disertakan dalam Microsoft Windows SDK).

Ketika driver memanggil rutinitas ini saat menangani peristiwa, IRP_MN_REMOVE_DEVICE, atau IRP_MN_SURPRISE_REMOVAL, manajer PnP memanggil rutinitas Callback driver setelah driver kembali dan tumpukan melepas lelah.

Penelepon IoReportTargetDeviceChangeAsynchronous harus berjalan di IRQL <= DISPATCH_LEVEL. Jika penulis driver memanggil rutinitas ini di IRQL = DISPATCH_LEVEL, NotificationStructure harus dialokasikan dari memori yang tidak di-patah.

Persyaratan

Persyaratan Nilai
Target Platform Universal
Header wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
Pustaka NtosKrnl.lib
DLL NtosKrnl.exe
IRQL <= DISPATCH_LEVEL (lihat bagian Keterangan)
Aturan kepatuhan DDI HwStorPortProhibitedDDIs(storport)

Lihat juga

IoReportTargetDeviceChange

TARGET_DEVICE_CUSTOM_NOTIFICATION