Fungsi IoSetDeviceInterfaceState (wdm.h)

Artikel
08/08/2023

Rutinitas IoSetDeviceInterfaceState memungkinkan atau menonaktifkan instans kelas antarmuka perangkat yang terdaftar sebelumnya.

Sintaks

NTSTATUS IoSetDeviceInterfaceState(
  [in] PUNICODE_STRING SymbolicLinkName,
  [in] BOOLEAN         Enable
);

Parameter

[in] SymbolicLinkName

Penunjuk ke string yang mengidentifikasi instans antarmuka perangkat yang sedang diaktifkan atau dinonaktifkan. String ini diperoleh dari panggilan sebelumnya ke IoRegisterDeviceInterface atau IoGetDeviceInterfaces.

[in] Enable

TRUE menunjukkan bahwa antarmuka perangkat sedang diaktifkan. FALSE menunjukkan bahwa antarmuka perangkat sedang dinonaktifkan.

Nilai kembali

IoSetDeviceInterfaceState mengembalikan STATUS_SUCCESS jika panggilan berhasil. Rutinitas ini mengembalikan status informasi STATUS_OBJECT_NAME_EXISTS jika pemanggil meminta untuk mengaktifkan antarmuka perangkat yang sudah diaktifkan. Kemungkinan nilai pengembalian kesalahan dijelaskan berikut ini.

Menampilkan kode	Deskripsi
STATUS_OBJECT_NAME_NOT_FOUND	Penelepon mencoba menonaktifkan antarmuka perangkat yang tidak diaktifkan.

Keterangan

IoSetDeviceInterfaceState memungkinkan instans antarmuka perangkat terdaftar untuk digunakan oleh aplikasi dan komponen sistem lainnya. Kelas antarmuka harus telah terdaftar sebelumnya dengan IoRegisterDeviceInterface atau dari mode pengguna.

Aplikasi dan komponen sistem lainnya hanya dapat membuka antarmuka yang diaktifkan.

Fungsi atau driver filter biasanya memanggil rutinitas ini dengan Aktifkan diatur ke TRUE setelah berhasil memulai perangkat sebagai respons terhadap IRP IRP_MN_START_DEVICE . Driver tersebut harus menonaktifkan instans antarmuka perangkat (yaitu, memanggil IoSetDeviceInterfaceState dan mengatur Aktifkan ke FALSE) saat menghapus perangkat sebagai respons terhadap IRP IRP_MN_REMOVE_DEVICE atau IRP IRP_MN_SURPRISE_REMOVAL . Jika driver tidak menonaktifkan antarmuka perangkat ketika memproses IRP penghapusan ini, driver tidak boleh mencoba melakukannya karena manajer PnP akan menonaktifkan antarmuka ketika manajer PnP menghapus perangkat.

Jika perangkat dihapus tiba-tiba (misalnya, dengan penghapusan mendadak) tetapi masih memiliki instans antarmuka perangkat yang valid, masalah akan terjadi jika perangkat dipasang kembali. Masalah ini terjadi ketika manajer PnP menghitung perangkat yang baru terpasang dan mengaktifkan instans antarmuka perangkat, yang akan ada di jalur registri yang sama dengan instans antarmuka perangkat yang ada.

Perhatikan bahwa jika driver memanggil IoSetDeviceInterfaceState untuk menonaktifkan instans antarmuka perangkat sebagai respons terhadap IRP IRP_MN_SURPRISE_REMOVAL , driver tidak boleh mencoba menonaktifkan instans antarmuka perangkat yang sama sebagai respons terhadap IRP IRP_MN_REMOVE_DEVICE .

Jika panggilan ke IoSetDeviceInterfaceState berhasil mengekspos instans antarmuka perangkat, sistem akan memberi tahu komponen apa pun yang terdaftar untuk pemberitahuan PnP tentang perubahan kelas perangkat. Demikian pula, jika panggilan ke rutinitas ini menonaktifkan instans antarmuka perangkat yang ada, sistem mengirimkan pemberitahuan yang sesuai.

Manajer PnP tidak mengirim pemberitahuan kedatangan instans antarmuka sampai IRP_MN_START_DEVICE IRP selesai, menunjukkan bahwa semua driver untuk perangkat telah menyelesaikan operasi mulai mereka. Selain itu, manajer PnP gagal membuat permintaan untuk perangkat hingga IRP IRP_MN_START_DEVICE selesai.

Penelepon IoSetDeviceInterfaceState harus berjalan di IRQL = PASSIVE_LEVEL dalam konteks utas sistem.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia dimulai dengan Windows 2000.
Target Platform	Universal
Header	wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (lihat bagian Keterangan)
Aturan kepatuhan DDI	HwStorPortProhibitedDDIs(storport), IrqlIoPassive1(wdm), LowerDriverReturn(wdm), PowerIrpDDis(wdm)