Fungsi ZwCreateKey (wdm.h)

Artikel
03/08/2023

Rutinitas ZwCreateKey membuat kunci registri baru atau membuka yang sudah ada.

Sintaks

NTSYSAPI NTSTATUS ZwCreateKey(
  [out]           PHANDLE            KeyHandle,
  [in]            ACCESS_MASK        DesiredAccess,
  [in]            POBJECT_ATTRIBUTES ObjectAttributes,
                  ULONG              TitleIndex,
  [in, optional]  PUNICODE_STRING    Class,
  [in]            ULONG              CreateOptions,
  [out, optional] PULONG             Disposition
);

Parameter

[out] KeyHandle

Penunjuk ke variabel HANDLE yang menerima handel ke kunci.

[in] DesiredAccess

Menentukan nilai ACCESS_MASK yang menentukan akses yang diminta ke objek. Selain hak akses yang ditentukan untuk semua jenis objek (lihat ACCESS_MASK), pemanggil dapat menentukan satu atau beberapa hak akses berikut, yang khusus untuk direktori objek:

Bendera DesiredAccess	Memungkinkan penelepon untuk melakukan ini
KEY_QUERY_VALUE	Membaca nilai kunci.
KEY_SET_VALUE	Tulis nilai kunci.
KEY_CREATE_SUB_KEY	Buat subkunci untuk kunci.
KEY_ENUMERATE_SUB_KEYS	Baca kunci sekuntum kunci.
KEY_CREATE_LINK	Buat tautan simbolis ke kunci. Bendera ini tidak digunakan oleh perangkat dan driver perantara.
KEY_NOTIFY	Minta untuk menerima pemberitahuan saat nama, nilai, atau atribut kunci berubah. Untuk informasi selengkapnya, lihat ZwNotifyChangeKey.

Pemanggil juga dapat menentukan salah satu konstanta berikut, yang menggabungkan beberapa bendera ACCESS_MASK.

Terus-menerus	Terdiri dari bendera ACCESS_MASK ini
KEY_READ	STANDARD_RIGHTS_READ, KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS dan KEY_NOTIFY
KEY_WRITE	STANDARD_RIGHTS_WRITE, KEY_SET_VALUE, dan KEY_CREATE_SUB_KEY
KEY_EXECUTE	Sama seperti KEY_READ.
KEY_ALL_ACCESS	STANDARD_RIGHTS_ALL, KEY_QUERY_VALUE, KEY_SET_VALUE, KEY_CREATE_SUB_KEY, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY, dan KEY_CREATE_LINK

[in] ObjectAttributes

Penunjuk ke struktur OBJECT_ATTRIBUTES yang menentukan nama objek dan atribut lainnya. Gunakan InitializeObjectAttributes untuk menginisialisasi struktur ini. Jika penelepon tidak berjalan dalam konteks utas sistem, pemanggil harus mengatur atribut OBJ_KERNEL_HANDLE saat memanggil InitializeObjectAttributes.

TitleIndex

Perangkat dan driver perantara mengatur parameter ini ke nol.

[in, optional] Class

Penunjuk ke string Unicode yang berisi kelas objek kunci. Informasi ini digunakan oleh manajer konfigurasi.

[in] CreateOptions

Menentukan opsi yang akan diterapkan saat membuat atau membuka kunci, yang ditentukan sebagai kombinasi bendera berikut yang kompatibel.

Bendera CreateOptions	Deskripsi
REG_OPTION_VOLATILE	Kunci tidak dipertahankan ketika sistem di-boot ulang.
REG_OPTION_NON_VOLATILE	Kunci dipertahankan ketika sistem di-boot ulang.
REG_OPTION_CREATE_LINK	Kunci yang baru dibuat adalah tautan simbolis. Bendera ini tidak digunakan oleh perangkat dan driver perantara.
REG_OPTION_BACKUP_RESTORE	Kunci harus dibuat atau dibuka dengan hak istimewa khusus yang memungkinkan operasi pencadangan dan pemulihan. Bendera ini tidak digunakan oleh perangkat dan driver perantara.

[out, optional] Disposition

Penunjuk ke variabel yang menerima nilai yang menunjukkan apakah kunci baru dibuat atau yang sudah ada dibuka.

Nilai disposisi	Deskripsi
REG_CREATED_NEW_KEY	Kunci baru dibuat.
REG_OPENED_EXISTING_KEY	Kunci yang ada dibuka.

Mengembalikan nilai

ZwCreateKey mengembalikan STATUS_SUCCESS pada keberhasilan, atau kode kesalahan NTSTATUS yang sesuai pada kegagalan.

Keterangan

ZwCreateKey menyediakan handel yang dapat digunakan pemanggil untuk memanipulasi kunci registri. Untuk informasi selengkapnya, lihat Menggunakan Registri di Driver.

Setelah handel yang ditunjukkan oleh KeyHandle tidak lagi digunakan, driver harus memanggil ZwClose untuk menutupnya.

Ada dua cara alternatif untuk menentukan nama file yang akan dibuat atau dibuka dengan ZwCreateKey:

Sebagai nama jalur yang sepenuhnya memenuhi syarat, disediakan di anggota ObjectName dari objectAttributes input. Nama jalur kunci registri dimulai dengan \Registri.
Sebagai nama jalur relatif terhadap kunci registri lain, diwakili oleh handel di anggota RootDirectory dari input ObjectAttributes.

Jika kunci yang ditentukan oleh ObjectAttributes tidak ada, rutinitas mencoba membuat kunci. Agar upaya ini berhasil, kunci baru harus merupakan subkunci langsung dari kunci yang dirujuk oleh RootDirectory, dan kunci yang dirujuk RootDirectory harus telah dibuka untuk akses KEY_CREATE_SUB_KEY.

Jika kunci yang ditentukan sudah ada, kunci dibuka dan nilainya tidak terpengaruh dengan cara apa pun.

Atribut keamanan yang ditentukan oleh ObjectAttributes saat kunci dibuat menentukan apakah DesiredAccess yang ditentukan diberikan pada panggilan berikutnya ke ZwCreateKey dan ZwOpenKey.

Jika penelepon tidak berjalan dalam konteks utas sistem, pemanggil harus memastikan bahwa setiap handel yang dibuatnya adalah handel privat. Jika tidak, handel dapat diakses oleh proses dalam konteks driver yang berjalan. Untuk informasi selengkapnya, lihat Penanganan Objek.

Untuk informasi selengkapnya tentang bekerja dengan kunci registri, lihat Menggunakan Registri di Driver.

Jika panggilan ke fungsi ini terjadi dalam mode pengguna, Anda harus menggunakan nama "NtCreateKey" alih-alih "ZwCreateKey".

Rutinitas NtCreateKey di kernel Windows tidak dapat diakses langsung oleh driver mode kernel.

Untuk panggilan dari driver mode kernel, versi NtXxx dan ZwXxx dari rutinitas Windows Native System Services dapat berperilaku berbeda dalam cara mereka menangani dan menafsirkan parameter input. Untuk informasi selengkapnya tentang hubungan antara versi NtXxx dan ZwXxx dari rutinitas, lihat Menggunakan Versi Nt dan Zw dari Rutinitas Layanan Sistem Asli.

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
Aturan kepatuhan DDI	HwStorPortProhibitedDDIs(storport), IrqlZwPassive(wdm), PowerIrpDDis(wdm), ZwRegistryCreate(storport), ZwRegistryCreate(storport), ZwRegistryCreate(wdm), ZwRegistryOpen(wdm)