Fungsi WdfRegistryOpenKey (wdfregistry.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Metode WdfRegistryOpenKey membuka kunci registri tertentu dan membuat objek kunci registri kerangka kerja yang mewakili kunci registri.

Sintaks

NTSTATUS WdfRegistryOpenKey(
  [in, optional] WDFKEY                 ParentKey,
  [in]           PCUNICODE_STRING       KeyName,
  [in]           ACCESS_MASK            DesiredAccess,
  [in, optional] PWDF_OBJECT_ATTRIBUTES KeyAttributes,
  [out]          WDFKEY                 *Key
);

Parameter

[in, optional] ParentKey

Handel ke objek kunci registri kerangka kerja. Objek ini mewakili kunci registri induk yang telah dibuka driver. Parameter ini bersifat opsional dan dapat berupa NULL. Jika parameter bukan NULL, kunci yang ditentukan KeyName harus berada di bawah kunci induk ini di registri. Untuk informasi selengkapnya tentang kunci induk ini, lihat bagian Keterangan.

[in] KeyName

Penunjuk ke struktur UNICODE_STRING yang berisi nama kunci yang akan dibuka. Nama kunci dapat menyertakan informasi jalur. Jika ParentKeyNULL, KeyName harus menentukan jalur lengkap ke kunci registri. Misalnya, lihat bagian Keterangan.

[in] DesiredAccess

Nilai jenis ACCESS_MASK yang menentukan hak akses yang diminta driver untuk kunci registri yang ditentukan. Untuk daftar hak akses yang biasanya digunakan driver untuk kunci registri, lihat Membuka Handel ke Objek Registry-Key. Driver Anda hanya harus meminta jenis akses yang dibutuhkannya. Misalnya, driver tidak boleh meminta KEY_ALL_ACCESS jika hanya akan membaca kunci registri.

[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.

Nilai kembali

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

Menampilkan kode	Deskripsi
STATUS_INVALID_DEVICE_REQUEST	WdfRegistryOpenKey tidak dipanggil di IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	Parameter yang tidak valid ditentukan.
STATUS_INSUFFICIENT_RESOURCES	Objek kunci registri tidak dapat dialokasikan.
STATUS_ACCESS_DENIED	Sistem menolak hak akses yang ditentukan.
STATUS_OBJECT_NAME_NOT_FOUND	Kunci registri yang ditentukan tidak ada.

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

Metode ini juga mungkin mengembalikan nilai NTSTATUS lainnya.

Keterangan

Untuk mendapatkan handel ke objek kunci registri yang mewakili kunci induk, driver Anda dapat memanggil WdfDriverOpenParametersRegistryKey, WdfDeviceOpenRegistryKey, atau WdfFdoInitOpenRegistryKey.

Format string yang ditentukan dalam parameter KeyName tergantung pada apakah pemanggil adalah driver KMDF atau driver UMDF. Misalnya, untuk membuka jalur berikut:

HKLM\System\CurrentControlSet\Control

Driver Anda mungkin menggunakan logika kondisi ini:

#ifdef _KERNEL_MODE
#define CONTROL_KEY_FULL_PATH L"\\Registry\\Machine\\System\\CurrentControlSet\\Control "
#else
#define CONTROL_KEY_FULL_PATH L"System\\CurrentControlSet\\Control\\" 
#endif

Ketika driver telah selesai menggunakan kunci registri yang dibukanya dengan WdfRegistryOpenKey, driver harus memanggil WdfRegistryClose.

Untuk informasi selengkapnya tentang objek kunci registri, lihat Menggunakan Registri di Driver Framework-Based.

Contoh

Contoh kode berikut membuka kunci perangkat lunak driver, lalu membuka kunci registri MySubKey , yang terletak di bawah kunci perangkat lunak driver.

WDFKEY  hKey, subkey;
NTSTATUS  status;
UNICODE_STRING myKeyStr;

status = WdfDeviceOpenRegistryKey(
                                  device,
                                  PLUGPLAY_REGKEY_DRIVER,
                                  KEY_READ,
                                  WDF_NO_OBJECT_ATTRIBUTES,
                                  &hKey
                                  );
if (NT_SUCCESS(status)){
    RtlInitUnicodeString(
                         &myKeyStr,
                         L"MySubKey"
                         );
    status = WdfRegistryOpenKey(
                                hKey,
                                &myKeyStr,
                                KEY_READ,
                                WDF_NO_OBJECT_ATTRIBUTES,
                                &subkey
                                );
}

Persyaratan

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