Fungsi WdfRegistryCreateKey (wdfregistry.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Metode WdfRegistryCreateKey membuat dan membuka kunci registri tertentu, atau hanya membuka kunci jika sudah ada, dan membuat objek kunci registri kerangka kerja yang mewakili kunci registri.

Sintaks

NTSTATUS WdfRegistryCreateKey(
  [in, optional]  WDFKEY                 ParentKey,
  [in]            PCUNICODE_STRING       KeyName,
  [in]            ACCESS_MASK            DesiredAccess,
  [in]            ULONG                  CreateOptions,
  [out, optional] PULONG                 CreateDisposition,
  [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 ParentKey adalah NULL, KeyName harus menentukan jalur lengkap ke kunci registri.

[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] CreateOptions

Satu atau beberapa bendera. Untuk informasi tentang bendera ini, lihat parameter CreateOptions atau ZwCreateKey.

[out, optional] CreateDisposition

Penunjuk ke lokasi yang menerima REG_CREATED_NEW_KEY jika kunci baru dibuat atau REG_OPENED_EXISTING_KEY jika kunci yang ada dibuka. Nilai-nilai ini didefinisikan dalam Wdm.h. Penunjuk ini bersifat opsional dan dapat berupa NULL.

[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

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

Menampilkan kode	Deskripsi
STATUS_INVALID_DEVICE_REQUEST	WdfRegistryCreateKey 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 WdfRegistryCreateKey , lihat Kesalahan Pembuatan Objek Kerangka Kerja.

Metode ini juga dapat mengembalikan nilai NTSTATUS lainnya.

Keterangan

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

Secara default, induk objek kunci registri baru adalah objek driver kerangka kerja yang dibuat metode WdfDriverCreate . Anda dapat menggunakan anggota ParentObject dari struktur WDF_OBJECT_ATTRIBUTES untuk menentukan induk yang berbeda. Kerangka kerja menghapus objek kunci registri saat menghapus objek induk. Jika driver Anda tidak mengubah induk default, driver harus menghapus objek kunci registri ketika telah selesai menggunakan objek ; jika tidak, objek kunci registri akan tetap ada sampai manajer I/O membongkar driver Anda.

Jika driver Anda tidak mengubah induk default, driver harus memanggil WdfRegistryClose ketika telah selesai menggunakan objek ; jika tidak, objek kunci registri akan tetap ada sampai manajer I/O membongkar driver Anda. Atau, driver dapat memanggil WdfObjectDelete untuk menghapus objek kunci registri.

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

Contoh

Contoh kode berikut membuka kunci perangkat lunak driver, lalu membuat dan membuka kunci registri myKeyStr , 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"myKeyStr"
                         );
    status = WdfRegistryCreateKey(
                                  hKey,
                                  &myKeyStr,
                                  KEY_READ,
                                  REG_OPTION_NON_VOLATILE,
                                  NULL,
                                  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)