Fungsi RegCreateKeyExA (winreg.h)

Artikel
03/08/2023

Membuat kunci registri yang ditentukan. Jika kunci sudah ada, fungsi akan membukanya. Perhatikan bahwa nama kunci tidak peka huruf besar/kecil.

Untuk melakukan operasi registri yang ditransaksikan pada kunci, panggil fungsi RegCreateKeyTransacted .

Aplikasi yang mencadangkan atau memulihkan status sistem termasuk file sistem dan sarang registri harus menggunakan Layanan Menyalin Bayangan Volume alih-alih fungsi registri.

Sintaks

LSTATUS RegCreateKeyExA(
  [in]            HKEY                        hKey,
  [in]            LPCSTR                      lpSubKey,
                  DWORD                       Reserved,
  [in, optional]  LPSTR                       lpClass,
  [in]            DWORD                       dwOptions,
  [in]            REGSAM                      samDesired,
  [in, optional]  const LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [out]           PHKEY                       phkResult,
  [out, optional] LPDWORD                     lpdwDisposition
);

Parameter

[in] hKey

Handel ke kunci registri terbuka. Proses panggilan harus memiliki akses KEY_CREATE_SUB_KEY ke kunci. Untuk informasi selengkapnya, lihat Keamanan Kunci Registri dan Hak Akses.

Akses untuk pembuatan kunci diperiksa terhadap pendeskripsi keamanan kunci registri, bukan masker akses yang ditentukan ketika handel diperoleh. Oleh karena itu, bahkan jika hKey dibuka dengan samDesired KEY_READ, hKey dapat digunakan dalam operasi yang memodifikasi registri jika diizinkan oleh deskriptor keamanannya.

Handel ini dikembalikan oleh fungsi RegCreateKeyEx atau RegOpenKeyEx , atau dapat menjadi salah satu kunci yang telah ditentukan sebelumnya berikut:

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

[in] lpSubKey

Nama subkunci yang dibuka atau dibuat fungsi ini. Subkey yang ditentukan harus berupa subkunji kunci yang diidentifikasi oleh parameter hKey ; bisa sampai 32 tingkat jauh di pohon registri. Untuk informasi selengkapnya tentang nama kunci, lihat Struktur Registri.

Jika lpSubKey adalah penunjuk ke string kosong, phkResult menerima handel baru ke kunci yang ditentukan oleh hKey.

Parameter ini tidak boleh NULL.

Reserved

Parameter ini dicadangkan dan harus nol.

[in, optional] lpClass

Jenis kelas yang ditentukan pengguna dari kunci ini. Parameter ini dapat diabaikan. Parameter ini bisa NULL.

[in] dwOptions

Parameter ini bisa menjadi salah satu nilai berikut.

Nilai	Makna
REG_OPTION_BACKUP_RESTORE 0x00000004L	Jika bendera ini diatur, fungsi mengabaikan parameter samDesired dan mencoba membuka kunci dengan akses yang diperlukan untuk mencadangkan atau memulihkan kunci. Jika utas panggilan mengaktifkan hak istimewa SE_BACKUP_NAME, kunci dibuka dengan hak akses ACCESS_SYSTEM_SECURITY dan KEY_READ. Jika utas panggilan mengaktifkan hak istimewa SE_RESTORE_NAME, dimulai dengan Windows Vista, kunci dibuka dengan hak akses ACCESS_SYSTEM_SECURITY, DELETE, dan KEY_WRITE. Jika kedua hak istimewa diaktifkan, kunci memiliki hak akses gabungan untuk kedua hak istimewa tersebut. Untuk informasi selengkapnya, lihat Menjalankan dengan Hak Istimewa Khusus.
REG_OPTION_CREATE_LINK 0x00000002L	Catatan Tautan simbolis registri hanya boleh digunakan untuk kompatibilitas aplikasi jika benar-benar diperlukan. Kunci ini adalah tautan simbolis. Jalur target ditetapkan ke nilai L"SymbolicLinkValue" dari kunci. Jalur target harus merupakan jalur registri absolut.
REG_OPTION_NON_VOLATILE 0x00000000L	Kunci ini tidak volatil; ini adalah defaultnya. Informasi disimpan dalam file dan dipertahankan ketika sistem dimulai ulang. Fungsi RegSaveKey menyimpan kunci yang tidak volatil.
REG_OPTION_VOLATILE 0x00000001L	Semua kunci yang dibuat oleh fungsi bersifat volatil. Informasi disimpan dalam memori dan tidak dipertahankan ketika sarang registri yang sesuai dibongkar. Untuk HKEY_LOCAL_MACHINE, ini hanya terjadi ketika sistem memulai pematian penuh. Untuk kunci registri yang dimuat oleh fungsi RegLoadKey , ini terjadi ketika RegUnLoadKey yang sesuai dilakukan. Fungsi RegSaveKey tidak menyimpan kunci volatil. Bendera ini diabaikan untuk kunci yang sudah ada. Catatan Pada pematian yang dipilih pengguna, matikan startup cepat adalah perilaku default untuk sistem.

[in] samDesired

Masker yang menentukan hak akses untuk kunci yang akan dibuat. Untuk informasi selengkapnya, lihat Keamanan Kunci Registri dan Hak Akses.

[in, optional] lpSecurityAttributes

Penunjuk ke struktur SECURITY_ATTRIBUTES yang menentukan apakah handel yang dikembalikan dapat diwariskan oleh proses anak. Jika lpSecurityAttributesADALAH NULL, handel tidak dapat diwariskan.

Anggota lpSecurityDescriptor dari struktur menentukan deskriptor keamanan untuk kunci baru. Jika lpSecurityAttributes adalah NULL, kuncinya akan mendapatkan deskriptor keamanan default. ACL dalam deskriptor keamanan default untuk kunci diwarisi dari kunci induk langsungnya.

[out] phkResult

Penunjuk ke variabel yang menerima handel ke kunci yang dibuka atau dibuat. Jika kunci bukan salah satu kunci registri yang telah ditentukan sebelumnya, panggil fungsi RegCloseKey setelah Anda selesai menggunakan handel.

[out, optional] lpdwDisposition

Penunjuk ke variabel yang menerima salah satu nilai disposisi berikut.

Nilai	Makna
REG_CREATED_NEW_KEY 0x00000001L	Kunci tidak ada dan dibuat.
REG_OPENED_EXISTING_KEY 0x00000002L	Kunci ada dan hanya dibuka tanpa diubah.

Jika lpdwDispositionADALAH NULL, tidak ada informasi disposisi yang dikembalikan.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan ERROR_SUCCESS.

Jika fungsi gagal, nilai yang dikembalikan adalah kode kesalahan bukan nol yang ditentukan dalam Winerror.h. Anda dapat menggunakan fungsi FormatMessage dengan bendera FORMAT_MESSAGE_FROM_SYSTEM untuk mendapatkan deskripsi umum tentang kesalahan tersebut.

Keterangan

Kunci yang dibuat fungsi RegCreateKeyEx tidak memiliki nilai. Aplikasi dapat menggunakan fungsi RegSetValueEx untuk mengatur nilai kunci.

Fungsi RegCreateKeyEx membuat semua kunci yang hilang di jalur yang ditentukan. Aplikasi dapat memanfaatkan perilaku ini untuk membuat beberapa kunci sekaligus. Misalnya, aplikasi dapat membuat subkunci empat tingkat dalam secara bersamaan dengan tiga subkunci sebelumnya dengan menentukan string formulir berikut untuk parameter lpSubKey :

subkey1\subkey2\subkey3\subkey4

Perhatikan bahwa perilaku ini akan mengakibatkan pembuatan kunci yang tidak diinginkan jika kunci yang ada di jalur dieja dengan tidak benar.

Aplikasi tidak dapat membuat kunci yang merupakan anak langsung dari HKEY_USERS atau HKEY_LOCAL_MACHINE. Aplikasi dapat membuat subkunci di tingkat pohon HKEY_USERS atau HKEY_LOCAL_MACHINE yang lebih rendah.

Jika layanan atau aplikasi Anda meniru pengguna yang berbeda, jangan gunakan fungsi ini dengan HKEY_CURRENT_USER. Sebagai gantinya, panggil fungsi RegOpenCurrentUser .

Perhatikan bahwa operasi yang mengakses kunci registri tertentu dialihkan. Untuk informasi selengkapnya, lihat Virtualisasi Registri dan Data Aplikasi 32-bit dan 64-bit di Registri.

Catatan

Header winreg.h mendefinisikan RegCreateKeyEx sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	winreg.h (termasuk Windows.h)
Pustaka	Advapi32.lib
DLL	Advapi32.dll