Fungsi WdfDeviceOpenRegistryKey (wdfdevice.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Metode WdfDeviceOpenRegistryKey membuka kunci perangkat keras perangkat atau kunci perangkat lunak driver di registri dan membuat objek kunci registri kerangka kerja yang mewakili kunci registri.

Sintaks

NTSTATUS WdfDeviceOpenRegistryKey(
  [in]           WDFDEVICE              Device,
  [in]           ULONG                  DeviceInstanceKeyType,
  [in]           ACCESS_MASK            DesiredAccess,
  [in, optional] PWDF_OBJECT_ATTRIBUTES KeyAttributes,
  [out]          WDFKEY                 *Key
);

Parameter

[in] Device

Handel ke objek perangkat kerangka kerja.

[in] DeviceInstanceKeyType

Menentukan kunci atau subkunjuk mana yang akan dibuka.

Catatan

UMDF tidak mendukung pembuatan subkunci.

Ini adalah bitwise ATAU dari bendera berikut (yang didefinisikan dalam Wdm.h).

Bendera DeviceInstanceKeyType	Makna	Kerangka Kerja
PLUGPLAY_REGKEY_DEVICE	Membuka kunci perangkat keras perangkat.	KMDF/UMDF
PLUGPLAY_REGKEY_DRIVER	Membuka kunci perangkat lunak driver. Driver UMDF yang mengatur bendera ini juga harus mengatur DesiredAccess ke KEY_READ. Jika tidak, metode ini mengembalikan STATUS_ACCESS_DENIED.	KMDF/UMDF
PLUGPLAY_REGKEY_CURRENT_HWPROFILE	Driver KMDF menggunakan bendera ini untuk membuka salinan kunci perangkat keras atau perangkat lunak yang ada di profil perangkat keras saat ini.	KMDF
PLUGPLAY_REGKEY_DRIVER \| WDF_REGKEY_DRIVER_SUBKEY	Driver UMDF menggunakan bendera ini bersama-sama untuk membuka subkunji ServiceName dari kunci perangkat lunak driver untuk akses baca/tulis.	UMDF
PLUGPLAY_REGKEY_DEVICE \| WDF_REGKEY_DEVICE_SUBKEY	Demikian pula, driver UMDF menggunakan bendera ini untuk membuka subkunci ServiceName dari kunci perangkat keras perangkat untuk akses baca/tulis.	UMDF

[in] DesiredAccess

Nilai jenis ACCESS_MASK yang menentukan hak akses yang diminta driver untuk kunci registri yang ditentukan.

Driver KMDF biasanya meminta KEY_READ, KEY_WRITE, atau KEY_READ | KEY_WRITE.

Jika Anda menulis driver UMDF, gunakan tabel berikut.

DeviceInstanceKeyType	DesiredAccess
PLUGPLAY_REGKEY_DEVICE	KEY_READ
PLUGPLAY_REGKEY_DEVICE \| WDF_REGKEY_DEVICE_SUBKEY	KEY_READ atau KEY_READ \| KEY_SET_VALUE
PLUGPLAY_REGKEY_DRIVER	KEY_READ
PLUGPLAY_REGKEY_DRIVER \| WDF_REGKEY_DRIVER_SUBKEY	KEY_READ atau KEY_READ \| KEY_SET_VALUE

Sebagai praktik terbaik, mintalah hanya jenis akses yang dibutuhkan driver Anda.

[in, optional] KeyAttributes

Penunjuk ke struktur WDF_OBJECT_ATTRIBUTES yang berisi atribut yang disediakan driver untuk objek kunci registri baru. Parameter ini bersifat opsional dan dapat WDF_NO_OBJECT_ATTRIBUTES.

[out] Key

Penunjuk ke lokasi yang menerima handel ke objek kunci registri baru.

Mengembalikan nilai

WdfDeviceOpenRegistryKey mengembalikan STATUS_SUCCESS jika operasi berhasil. Jika tidak, metode mungkin mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
STATUS_INVALID_DEVICE_REQUEST	WdfDeviceOpenRegistryKey tidak dipanggil di IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	Parameter yang tidak valid ditentukan. Untuk UMDF, nilai pengembalian ini dapat menunjukkan hak akses yang tidak memadai.
STATUS_INSUFFICIENT_RESOURCES	Objek kunci registri tidak dapat dialokasikan.
STATUS_OBJECT_NAME_NOT_FOUND	Kunci registri yang ditentukan tidak ada.

Untuk daftar nilai pengembalian lain yang mungkin dikembalikan oleh metode WdfDeviceOpenRegistryKey , lihat Kesalahan Pembuatan Objek Kerangka Kerja.

Metode ini mungkin mengembalikan nilai NTSTATUS lainnya.

Pemeriksaan bug terjadi jika driver menyediakan handel objek yang tidak valid.

Keterangan

Jika driver Anda harus membuka kunci perangkat keras atau perangkat lunak sebelum disebut WdfDeviceCreate, driver harus memanggil WdfFdoInitOpenRegistryKey alih-alih WdfDeviceOpenRegistryKey.

Ketika driver telah selesai menggunakan kunci registri yang dibuka dengan WdfDeviceOpenRegistryKey, driver harus memanggil WdfRegistryClose.

Untuk informasi selengkapnya tentang registri, kunci perangkat keras dan perangkat lunak, dan objek registri, lihat Menggunakan Registri di driver Framework-Based.

Contoh

Untuk contoh kode yang menggunakan WdfDeviceOpenRegistryKey, lihat WdfRegistryCreateKey, WdfRegistryOpenKey, dan WdfRegistryQueryValue.

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1,0
Versi UMDF minimum	2.0
Header	wdfdevice.h (termasuk Wdf.h)
Pustaka	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Aturan kepatuhan DDI	AccessHardwareKey(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Lihat juga

WdfFdoInitOpenRegistryKey