Fungsi IoRegisterDeviceInterface (wdm.h)

Artikel
07/16/2024

Rutinitas IoRegisterDeviceInterface mendaftarkan kelas antarmuka perangkat , jika belum terdaftar sebelumnya, dan membuat instans baru kelas antarmuka, yang kemudian dapat diaktifkan driver untuk digunakan oleh aplikasi atau komponen sistem lainnya.

Sintaksis

NTSTATUS IoRegisterDeviceInterface(
  [in]           PDEVICE_OBJECT  PhysicalDeviceObject,
  [in]           const GUID      *InterfaceClassGuid,
  [in, optional] PUNICODE_STRING ReferenceString,
  [out]          PUNICODE_STRING SymbolicLinkName
);

Parameter

[in] PhysicalDeviceObject

Penunjuk ke PDO untuk perangkat.

[in] InterfaceClassGuid

Pointer ke GUID kelas yang mengidentifikasi fungsionalitas (kelas antarmuka perangkat) yang didaftarkan.

[in, optional] ReferenceString

Secara opsional menunjuk ke UNICODE_STRING. String tidak boleh berisi karakter pemisah jalur ("/" atau "\"). Driver fungsi biasanya menentukan NULL untuk parameter ini. Driver filter harus menentukan NULL.

String referensi hanya digunakan oleh beberapa driver bus, seperti swenum , yang merupakan driver bus yang menggunakan instans antarmuka perangkat sebagai tempat penampung untuk perangkat lunak yang dibuat sesuai permintaan. Saat instans antarmuka dibuka, manajer I/O meneruskan string referensi instans ke driver. String menjadi bagian dari nama instans antarmuka (sebagai komponen jalur tambahan). Driver kemudian dapat menggunakan string referensi untuk membedakan antara dua instans antarmuka dari kelas yang sama untuk satu perangkat.

Pada sistem Microsoft Windows 98/Me, nilai ReferenceString tidak boleh lebih dari MAX_PATH karakter. Tidak ada batas panjang pada Windows 2000 dan versi Windows yang lebih baru.

[out] SymbolicLinkName

Penunjuk ke struktur string Unicode yang dialokasikan oleh pemanggil. Jika rutinitas ini berhasil, ini menginisialisasi string Unicode dan mengalokasikan buffer string yang berisi jalur mode kernel ke tautan simbolis untuk instans kelas antarmuka perangkat yang ditentukan.

Pemanggil harus memperlakukan SymbolicLinkName sebagai buram dan tidak boleh membongkarnya.

Pemanggil bertanggung jawab untuk membebaskan SymbolicLinkName dengan RtlFreeUnicodeString ketika tidak lagi diperlukan.

Mengembalikan nilai

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

Mengembalikan kode	Deskripsi
STATUS_INVALID_DEVICE_REQUEST	Parameter tidak valid. Kemungkinan termasuk bahwa PhysicalDeviceObject tidak menunjuk ke PDO yang valid, atau bahwa string ReferenceString berisi karakter yang tidak valid.

Komentar

IoRegisterDeviceInterface mendaftarkan kelas antarmuka perangkat, jika belum terdaftar sebelumnya, dan membuat instans baru kelas antarmuka. Driver dapat memanggil rutinitas ini beberapa kali untuk perangkat tertentu untuk mendaftarkan beberapa kelas antarmuka dan membuat instans kelas. Fungsi atau driver filter biasanya mendaftarkan antarmuka perangkat dalam rutinitas AddDevice . Misalnya, driver volume yang toleran terhadap kesalahan dapat mendaftarkan instans antarmuka volume toleran terhadap kesalahan dan instans antarmuka volume untuk volume tertentu.

Jika kelas antarmuka perangkat belum terdaftar sebelumnya, manajer I/O membuat kunci registri untuk itu, bersama dengan penyimpanan persisten khusus instans di bawah kunci. Driver dapat mengakses penyimpanan persisten ini menggunakan IoOpenDeviceInterfaceRegistryKey.

Driver mendaftarkan instans antarmuka sekali dan kemudian memanggil IoSetDeviceInterfaceState untuk mengaktifkan dan menonaktifkan antarmuka.

Antarmuka terdaftar bertahan di seluruh reboot sistem operasi. Jika antarmuka yang ditentukan sudah terdaftar, manajer I/O meneruskan namanya di SymbolicLinkName dan mengembalikan status keberhasilan informasi STATUS_OBJECT_NAME_EXISTS.

Sebagian besar driver menggunakan string referensi NULL untuk instans antarmuka perangkat. Jika driver menggunakan string referensi null non-, driver harus melakukan pekerjaan tambahan, termasuk mungkin mengelola namespace dan keamanannya sendiri. Driver filter yang mengekspos antarmuka perangkat harus menggunakan NULLReferenceString untuk menghindari konflik dengan driver lain di tumpukan perangkat.

Penelepon rutin ini tidak diperlukan untuk menghapus pendaftaran untuk antarmuka perangkat ketika tidak lagi diperlukan. Pendaftaran antarmuka perangkat dapat dihapus dari mode pengguna, jika perlu.

Penelepon IoRegisterDeviceInterface 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), IrqlIoPassive3(wdm), PowerIrpDDis(wdm)

Lihat juga

IoGetDeviceInterfaces

IopenDeviceInterfaceRegistryKey

IoSetDeviceInterfaceState

RtlFreeUnicodeString

Bagikan melalui