Fungsi RegCreateKeyTransactedA (winreg.h)
Membuat kunci registri yang ditentukan dan mengaitkannya dengan transaksi. Jika kunci sudah ada, fungsi akan membukanya. Perhatikan bahwa nama kunci tidak peka huruf besar/kecil.
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 RegCreateKeyTransactedA(
[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,
[in] HANDLE hTransaction,
PVOID pExtendedParemeter
);
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, itu dapat digunakan dalam operasi yang membuat kunci jika diizinkan oleh pendeskripsi keamanannya.
Handel ini dikembalikan oleh fungsi RegCreateKeyTransacted atau RegOpenKeyTransacted , atau dapat menjadi salah satu kunci yang telah ditentukan 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. Subkunjud yang ditentukan harus merupakan subkuntangan 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
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 |
|---|---|
|
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, kunci dibuka dengan hak akses ACCESS_SYSTEM_SECURITY 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. |
|
Kunci ini tidak volatil; ini adalah default. Informasi disimpan dalam file dan dipertahankan ketika sistem dimulai ulang. Fungsi RegSaveKey menyimpan kunci yang tidak volatil. |
|
Semua kunci yang dibuat oleh fungsi mudah menguap. Informasi disimpan dalam memori dan tidak dipertahankan ketika sarang registri yang sesuai dibongkar. Untuk HKEY_LOCAL_MACHINE, ini terjadi ketika sistem dimatikan. 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. |
[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 pendeskripsi 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 kuncinya 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 |
|---|---|
|
Kunci tidak ada dan dibuat. |
|
Kunci ada dan hanya dibuka tanpa diubah. |
Jika lpdwDispositionadalah NULL, tidak ada informasi disposisi yang dikembalikan.
[in] hTransaction
Handel ke transaksi aktif. Handel ini dikembalikan oleh fungsi CreateTransaction .
pExtendedParemeter
Parameter ini dicadangkan dan harus NULL.
Nilai kembali
Jika fungsi berhasil, nilai yang dikembalikan adalah 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
Ketika kunci dibuat menggunakan fungsi ini, operasi berikutnya pada kunci ditransaksikan. Jika operasi yang tidak ditransaksikan dilakukan pada kunci sebelum transaksi dilakukan, transaksi digulung balik. Setelah transaksi diterapkan atau digulung balik, Anda harus membuka kembali kunci menggunakan RegCreateKeyTransacted atau RegOpenKeyTransacted dengan handel transaksi aktif untuk membuat operasi tambahan ditransaksikan. Untuk informasi selengkapnya tentang transaksi, lihat Manajer Transaksi Kernel.
Perhatikan bahwa operasi berikutnya pada sub-kunci kunci ini tidak secara otomatis ditransaksikan. Oleh karena itu, RegDeleteKeyEx tidak melakukan operasi penghapusan yang ditransaksikan. Sebagai gantinya, gunakan fungsi RegDeleteKeyTransacted untuk melakukan operasi penghapusan yang ditransaksikan.
Kunci yang dibuat fungsi RegCreateKeyTransacted tidak memiliki nilai. Aplikasi dapat menggunakan fungsi RegSetValueEx untuk mengatur nilai kunci.
Fungsi RegCreateKeyTransacted 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 secara mendalam pada saat yang sama dengan tiga subkunci sebelumnya dengan menentukan string formulir berikut untuk parameter lpSubKey :
subkey1\subkey2\subkey3\subkey4
Perhatikan bahwa perilaku ini akan menghasilkan 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 yang lebih rendah dari pohon HKEY_USERS atau HKEY_LOCAL_MACHINE .
Catatan
Header winreg.h mendefinisikan RegCreateKeyTransacted 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
| Klien minimum yang didukung | Windows Vista [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows Server 2008 [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | winreg.h (termasuk Windows.h) |
| Pustaka | Advapi32.lib |
| DLL | Advapi32.dll |