Fungsi IopenDeviceRegistryKey (wdm.h)

Artikel
02/29/2024

Rutinitas IopenDeviceRegistryKey mengembalikan handel ke lokasi status registri untuk instans perangkat tertentu.

Sintaks

NTSTATUS IoOpenDeviceRegistryKey(
  [in]  PDEVICE_OBJECT DeviceObject,
  [in]  ULONG          DevInstKeyType,
  [in]  ACCESS_MASK    DesiredAccess,
  [out] PHANDLE        DeviceRegKey
);

Parameter

[in] DeviceObject

Arahkan ke objek perangkat fisik (PDO) instans perangkat tempat lokasi status registri akan dibuka.

[in] DevInstKeyType

Menentukan bendera yang menunjukkan apakah akan membuka kunci perangkat keras khusus perangkat atau kunci perangkat lunak khusus driver. Bendera juga menunjukkan apakah kunci relatif terhadap profil perangkat keras saat ini. Untuk informasi selengkapnya tentang kunci perangkat keras dan perangkat lunak, lihat Pengantar Kunci Registri untuk Driver.

Bendera didefinisikan sebagai berikut:

PLUGPLAY_REGKEY_DEVICE

Buka kunci perangkat keras perangkat, lokasi status registri khusus perangkat yang berisi informasi tentang perangkat. Bendera ini tidak dapat ditentukan dengan PLUGPLAY_REGKEY_DRIVER.

PLUGPLAY_REGKEY_DRIVER

Buka kunci perangkat lunak perangkat, lokasi status registri khusus perangkat untuk menyimpan informasi khusus driver. Bendera ini tidak dapat ditentukan dengan PLUGPLAY_REGKEY_DEVICE.

PLUGPLAY_REGKEY_CURRENT_HWPROFILE

Profil perangkat keras tidak digunakan lagi dan statusnya tidak boleh disimpan relatif terhadap profil perangkat keras.

Buka kunci yang relatif terhadap profil perangkat keras saat ini untuk informasi perangkat atau driver. Ini memungkinkan driver untuk mengakses informasi konfigurasi yang khusus untuk profil perangkat keras. Pemanggil harus menentukan PLUGPLAY_REGKEY_DEVICE atau PLUGPLAY_REGKEY_DRIVER dengan bendera ini.

[in] DesiredAccess

Menentukan nilai ACCESS_MASK yang mewakili akses yang dibutuhkan pemanggil ke kunci. Lihat rutinitas ZwCreateKey untuk deskripsi setiap akses KEY_XXX dengan benar.

[out] DeviceRegKey

Penunjuk ke buffer yang dialokasikan penelepon yang, saat pengembalian berhasil, berisi handel ke lokasi status registri yang diminta.

Nilai kembali

IoOpenDeviceRegistryKey mengembalikan STATUS_SUCCESS jika panggilan berhasil. Kemungkinan nilai pengembalian kesalahan meliputi yang berikut ini:

Menampilkan kode	Deskripsi
STATUS_INVALID_PARAMETER	Mungkin menunjukkan bahwa pemanggil menentukan sekumpulan bendera DevInstKeyType ilegal atau menyediakan DeviceObject yang bukan PDO yang valid.

Keterangan

Driver harus memanggil ZwClose untuk menutup handel yang dikembalikan dari rutinitas ini ketika akses tidak lagi diperlukan.

Kunci registri yang dibuka oleh rutinitas ini bersifat nonvolatile.

Aplikasi penyiapan mode pengguna dapat mengakses kunci registri ini dengan menggunakan fungsi CM_Open_DevNode_Key atau informasi perangkat seperti SetupDiOpenDevRegKey atau SetupDiCreateDevRegKey.

Untuk mengisi status sebelumnya di lokasi status registri ini pada waktu penginstalan paket driver, gunakan arahan INF AddReg dalam file INF.

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

Persyaratan

Persyaratan	Nilai
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), PowerIrpDDis(wdm)