Fungsi RegEnumValueA (winreg.h)

Artikel
08/27/2023

Menghitung nilai untuk kunci registri terbuka yang ditentukan. Fungsi menyalin satu nama nilai terindeks dan blok data untuk kunci setiap kali dipanggil.

Sintaks

LSTATUS RegEnumValueA(
  [in]                HKEY    hKey,
  [in]                DWORD   dwIndex,
  [out]               LPSTR   lpValueName,
  [in, out]           LPDWORD lpcchValueName,
                      LPDWORD lpReserved,
  [out, optional]     LPDWORD lpType,
  [out, optional]     LPBYTE  lpData,
  [in, out, optional] LPDWORD lpcbData
);

Parameter

[in] hKey

Handel ke kunci registri terbuka. Kunci harus dibuka dengan hak akses KEY_QUERY_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_PERFORMANCE_DATA

HKEY_USERS

[in] dwIndex

Indeks nilai yang akan diambil. Parameter ini harus nol untuk panggilan pertama ke fungsi RegEnumValue dan kemudian dinaikkan untuk panggilan berikutnya.

Karena nilai tidak diurutkan, nilai baru apa pun akan memiliki indeks arbitrer. Ini berarti bahwa fungsi dapat mengembalikan nilai dalam urutan apa pun.

[out] lpValueName

Penunjuk ke buffer yang menerima nama nilai sebagai string yang dihentikan null.

Buffer ini harus cukup besar untuk menyertakan karakter null yang mengakhiri.

Untuk informasi selengkapnya, lihat Batas Ukuran Elemen Registri.

[in, out] lpcchValueName

Penunjuk ke variabel yang menentukan ukuran buffer yang diacu oleh parameter lpValueName , dalam karakter. Ketika fungsi kembali, variabel menerima jumlah karakter yang disimpan dalam buffer, tidak termasuk karakter null yang mengakhiri.

Jika buffer yang ditentukan oleh lpValueName tidak cukup besar untuk menyimpan data, fungsi mengembalikan ERROR_MORE_DATA dan ukuran buffer dalam variabel yang ditunjukkan oleh lpValueName tidak diubah. Dalam hal ini, konten lpcchValueName tidak terdefinisi.

Nama nilai registri dibatasi hingga 32.767 byte. Versi ANSI dari fungsi ini memperlakukan parameter ini sebagai nilai SHORT . Oleh karena itu, jika Anda menentukan nilai yang lebih besar dari 32.767 byte, ada luapan dan fungsi dapat mengembalikan ERROR_MORE_DATA.

lpReserved

Parameter ini dicadangkan dan harus NULL.

[out, optional] lpType

Penunjuk ke variabel yang menerima kode yang menunjukkan jenis data yang disimpan dalam nilai yang ditentukan. Untuk daftar kode jenis yang mungkin, lihat Jenis Nilai Registri. Parameter lpType dapat berupa NULL jika kode jenis tidak diperlukan.

[out, optional] lpData

Penunjuk ke buffer yang menerima data untuk entri nilai. Parameter ini bisa NULL jika data tidak diperlukan.

Jika lpData adalah NULL dan lpcbData bukan NULL, fungsi menyimpan ukuran data, dalam byte, dalam variabel yang ditunjukkan oleh lpcbData. Ini memungkinkan aplikasi untuk menentukan cara terbaik untuk mengalokasikan buffer untuk data.

[in, out, optional] lpcbData

Penunjuk ke variabel yang menentukan ukuran buffer yang diacu oleh parameter lpData , dalam byte. Saat fungsi kembali, variabel menerima jumlah byte yang disimpan dalam buffer.

Parameter ini bisa null hanya jika lpData adalah NULL.

Jika data memiliki jenis REG_SZ, REG_MULTI_SZ, atau REG_EXPAND_SZ, ukuran ini menyertakan karakter atau karakter null yang mengakhiri. Untuk informasi selengkapnya, lihat Keterangan.

Jika buffer yang ditentukan oleh lpData tidak cukup besar untuk menyimpan data, fungsi mengembalikan ERROR_MORE_DATA dan menyimpan ukuran buffer yang diperlukan dalam variabel yang ditunjukkan oleh lpcbData. Dalam hal ini, isi lpData tidak terdefinisi.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah ERROR_SUCCESS.

Jika fungsi gagal, nilai yang dikembalikan adalah kode kesalahan sistem. Jika tidak ada lagi nilai yang tersedia, fungsi akan mengembalikan ERROR_NO_MORE_ITEMS.

Jika buffer yang ditentukan oleh lpValueName atau lpData terlalu kecil untuk menerima nilai, fungsi akan mengembalikan ERROR_MORE_DATA.

Keterangan

Untuk menghitung nilai, aplikasi awalnya harus memanggil fungsi RegEnumValue dengan parameter dwIndex diatur ke nol. Aplikasi kemudian harus menambahkan dwIndex dan memanggil fungsi RegEnumValue sampai tidak ada nilai lagi (sampai fungsi mengembalikan ERROR_NO_MORE_ITEMS).

Aplikasi juga dapat mengatur dwIndex ke indeks nilai terakhir pada panggilan pertama ke fungsi dan mengurangi indeks hingga nilai dengan indeks 0 dijumlahkan. Untuk mengambil indeks nilai terakhir, gunakan fungsi RegQueryInfoKey .

Saat menggunakan RegEnumValue, aplikasi tidak boleh memanggil fungsi registri apa pun yang mungkin mengubah kunci yang sedang dikueri.

Jika data memiliki jenis REG_SZ, REG_MULTI_SZ, atau REG_EXPAND_SZ, string mungkin belum disimpan dengan karakter penghentian null yang tepat. Oleh karena itu, bahkan jika fungsi mengembalikan ERROR_SUCCESS, aplikasi harus memastikan bahwa string dihentikan dengan benar sebelum menggunakannya; jika tidak, itu dapat menimpa buffer. (Perhatikan bahwa string REG_MULTI_SZ harus memiliki dua karakter yang mengakhiri null.)

Untuk menentukan ukuran maksimum nama dan buffer data, gunakan fungsi RegQueryInfoKey .

Catatan

Pada versi lama Windows, API ini juga diekspos oleh kernel32.dll.

Contoh

Misalnya, lihat Menghitung Subkunci Registri.

Catatan

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