Fungsi RegSetValueExW (winreg.h)

Artikel
08/27/2023

Mengatur data dan jenis nilai tertentu di bawah kunci registri.

Sintaks

LSTATUS RegSetValueExW(
  [in]           HKEY       hKey,
  [in, optional] LPCWSTR    lpValueName,
                 DWORD      Reserved,
  [in]           DWORD      dwType,
  [in]           const BYTE *lpData,
  [in]           DWORD      cbData
);

Parameter

[in] hKey

Handel ke kunci registri terbuka. Kunci harus telah dibuka dengan hak akses KEY_SET_VALUE. Untuk informasi selengkapnya, lihat Keamanan Kunci Registri dan Hak Akses.

Handel ini dikembalikan oleh fungsi RegCreateKeyEx, RegCreateKeyTransacted, RegOpenKeyEx, atau RegOpenKeyTransacted . Ini juga bisa menjadi salah satu kunci yang telah ditentukan sebelumnya berikut:

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

Versi Unicode dari fungsi ini mendukung kunci tambahan yang telah ditentukan berikut:

HKEY_PERFORMANCE_TEXT
HKEY_PERFORMANCE_NLSTEXT

[in, optional] lpValueName

Nama nilai yang akan ditetapkan. Jika nilai dengan nama ini belum ada di kunci, fungsi akan menambahkannya ke kunci.

Jika lpValueName adalah NULL atau string kosong, "", fungsi mengatur jenis dan data untuk nilai kunci yang tidak bernama atau default.

Untuk informasi selengkapnya, lihat Batas Ukuran Elemen Registri.

Kunci registri tidak memiliki nilai default, tetapi dapat memiliki satu nilai yang tidak disebutkan namanya, yang bisa dari jenis apa pun.

Reserved

Parameter ini dicadangkan dan harus nol.

[in] dwType

Jenis data yang ditujukkan oleh parameter lpData . Untuk daftar jenis yang mungkin, lihat Jenis Nilai Registri.

[in] lpData

Data yang akan disimpan.

Untuk jenis berbasis string, seperti REG_SZ, string harus dihentikan null. Dengan jenis data REG_MULTI_SZ, string harus dihentikan dengan dua karakter null .

Perhatikan lpData yang menunjukkan nilai null valid, namun, jika demikian, cbData harus diatur ke '0'.

[in] cbData

Ukuran informasi yang ditujukkan oleh parameter lpData , dalam byte. Jika data berjenis REG_SZ, REG_EXPAND_SZ, atau REG_MULTI_SZ, cbData harus menyertakan ukuran karakter atau karakter null yang mengakhiri.

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

Ukuran nilai dibatasi oleh memori yang tersedia. Namun, menyimpan nilai besar dalam registri dapat memengaruhi performanya. Nilai panjang (lebih dari 2.048 byte) harus disimpan sebagai file, dengan lokasi file yang disimpan di registri.

Elemen aplikasi seperti ikon, bitmap, dan file yang dapat dieksekusi harus disimpan sebagai file dan tidak ditempatkan di registri.

Jika dwType adalah jenis REG_SZ, REG_MULTI_SZ, atau REG_EXPAND_SZ dan versi ANSI dari fungsi ini digunakan (baik dengan secara eksplisit memanggil RegSetValueExA atau dengan tidak menentukan UNICODE sebelum menyertakan file Windows.h), data yang diarahkan oleh parameter lpData harus berupa string karakter ANSI. String dikonversi ke Unicode sebelum disimpan dalam registri.

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.

Pertimbangkan untuk menggunakan fungsi RegSetKeyValue , yang menyediakan cara yang lebih nyaman untuk mengatur nilai kunci registri.

Catatan

Header winreg.h mendefinisikan RegSetValueEx 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 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