Fungsi IoGetDeviceInterfaces (wdm.h)

Artikel
07/02/2025

Rutinitas IoGetDeviceInterfaces mengembalikan daftar instans antarmuka perangkat dari kelas antarmuka perangkat tertentu (seperti semua perangkat pada sistem yang mendukung antarmuka HID).

Sintaksis

C++

NTSTATUS IoGetDeviceInterfaces(
  [in]           const GUID     *InterfaceClassGuid,
  [in, optional] PDEVICE_OBJECT PhysicalDeviceObject,
  [in]           ULONG          Flags,
  [out]          PZZWSTR        *SymbolicLinkList
);

Parameter

[in] InterfaceClassGuid

Penunjuk ke GUID kelas yang menentukan kelas antarmuka perangkat. GUID untuk kelas harus berada dalam file header khusus perangkat.

[in, optional] PhysicalDeviceObject

Penunjuk ke PDO opsional yang mempersempit pencarian hanya ke instans antarmuka perangkat perangkat yang diwakili oleh PDO.

[in] Flags

Menentukan bendera yang mengubah pencarian antarmuka perangkat. Hanya satu bendera yang saat ini ditentukan, dan dijelaskan dalam tabel berikut.

Bendera	Arti
DEVICE_INTERFACE_INCLUDE_NONACTIVE	Mengembalikan instans antarmuka perangkat yang dinonaktifkan selain instans antarmuka yang diaktifkan.

Saat mencari perangkat yang mendukung kelas antarmuka tertentu, pemanggil memerlukan instans antarmuka yang diaktifkan dan dengan demikian tidak mengatur bendera DEVICE_INTERFACE_INCLUDE_NONACTIVE.

Driver biasanya mengatur bendera DEVICE_INTERFACE_INCLUDE_NONACTIVE untuk menemukan instans antarmuka yang dinonaktifkan yang harus diaktifkan driver. Misalnya, penginstal kelas untuk perangkat mungkin telah diarahkan oleh file INF untuk mendaftarkan satu atau beberapa instans antarmuka untuk perangkat. Instans antarmuka akan didaftarkan tetapi tidak dapat digunakan sampai diaktifkan oleh driver (menggunakan IoSetDeviceInterfaceState). Untuk mempersempit daftar instans antarmuka yang dikembalikan hanya ke yang diekspos oleh perangkat tertentu, driver dapat menentukan PhysicalDeviceObject .

[out] SymbolicLinkList

Penunjuk ke penunjuk karakter lebar tempat rutinitas, jika berhasil, menulis alamat dasar buffer yang berisi daftar string Unicode. String ini adalah nama tautan simbolis yang mengidentifikasi instans antarmuka perangkat yang cocok dengan kriteria pencarian. Setiap string Unicode dalam daftar dihentikan null; akhir seluruh daftar ditandai oleh karakter null tambahan. Rutinitas mengalokasikan buffer untuk string ini dari memori sistem halaman. Pemanggil bertanggung jawab untuk membebaskan buffer (dengan memanggil ExFreePool rutin) ketika tidak lagi diperlukan.

Jika tidak ada instans antarmuka perangkat yang cocok dengan kriteria pencarian, rutinitas ini mengembalikan STATUS_SUCCESS dan string berisi satu karakter NULL.

Mengembalikan nilai

IoGetDeviceInterfaces mengembalikan STATUS_SUCCESS jika panggilan berhasil. Kemungkinan nilai pengembalian kesalahan mencakup yang berikut ini.

Mengembalikan kode	Deskripsi
STATUS_INVALID_DEVICE_REQUEST	Mungkin menunjukkan bahwa PhysicalDeviceObject bukan penunjuk PDO yang valid.

Komentar

IoGetDeviceInterfaces mengembalikan daftar instans antarmuka perangkat yang cocok dengan kriteria pencarian. Komponen mode kernel biasanya memanggil rutinitas ini untuk mendapatkan daftar semua instans antarmuka perangkat yang diaktifkan dari kelas antarmuka perangkat tertentu. Komponen tersebut bisa mendapatkan penunjuk ke objek file dan/atau objek perangkat untuk antarmuka dengan memanggil IoGetDeviceObjectPointer atau ZwCreateFile rutinitas. Penunjuk objek perangkat yang dikembalikan oleh IoGetDeviceObjectPointer menunjuk ke bagian atas tumpukan perangkat untuk perangkat dan dapat digunakan dalam panggilan ke rutinitas IoCallDriver.

Jika ada antarmuka default untuk kelas antarmuka perangkat yang diminta, antarmuka tersebut tercantum terlebih dahulu di SymbolicLinkList. Antarmuka default dapat diatur oleh mode pengguna, tetapi tidak dengan mode kernel.

Format nama tautan simbolis buram; pemanggil tidak boleh mencoba mengurai nama tautan simbolis.

Tautan simbolis untuk instans antarmuka perangkat dapat digunakan di seluruh boot sistem.

Untuk diberi tahu ketika instans antarmuka perangkat tambahan dari kelas tertentu diaktifkan pada sistem, daftar untuk pemberitahuan perubahan kelas perangkat dengan memanggil IoRegisterPlugPlayNotification rutin.

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

Persyaratan

Syarat	Nilai
klien minimum yang didukung	Tersedia dimulai dengan Windows 2000.
Platform Target	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	HwStorPortProhibitedDIs (storport), MarkPower(wdm), MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), PowerIrpDDis(wdm)