Fungsi WdfRegistryCreateKey (wdfregistry.h)
[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 |
---|---|
|
WdfRegistryCreateKey tidak dipanggil di IRQL = PASSIVE_LEVEL. |
|
Parameter yang tidak valid ditentukan. |
|
Objek kunci registri tidak dapat dialokasikan. |
|
Sistem menolak hak akses yang ditentukan. |
|
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) |