Fungsi RegGetValueA (winreg.h)
Mengambil jenis dan data untuk nilai registri yang ditentukan.
Sintaks
LSTATUS RegGetValueA(
[in] HKEY hkey,
[in, optional] LPCSTR lpSubKey,
[in, optional] LPCSTR lpValue,
[in, optional] DWORD dwFlags,
[out, optional] LPDWORD pdwType,
[out, optional] PVOID pvData,
[in, out, optional] LPDWORD pcbData
);
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_PERFORMANCE_NLSTEXT
- HKEY_PERFORMANCE_TEXT
- HKEY_USERS
[in, optional] lpSubKey
Jalur kunci registri relatif terhadap kunci yang ditentukan oleh parameter hkey . Nilai registri akan diambil dari subkuntang ini.
Jalur tidak peka huruf besar/kecil.
Jika parameter ini null atau string kosong, "", nilai akan dibaca dari kunci yang ditentukan oleh hkey itu sendiri.
[in, optional] lpValue
Nama nilai registri.
Jika parameter ini adalah NULL atau string kosong, "", fungsi mengambil jenis dan data untuk kunci yang tidak bernama atau nilai default, jika ada. Kunci tidak secara otomatis memiliki nilai yang tidak bernama atau default, dan nilai yang tidak disebutkan namanya bisa dari jenis apa pun.
Untuk informasi selengkapnya, lihat Batas Ukuran Elemen Registri.
[in, optional] dwFlags
Bendera yang membatasi jenis data nilai yang akan dikueri. Jika jenis data nilai tidak memenuhi kriteria ini, fungsi gagal. Parameter ini bisa menjadi satu atau beberapa nilai berikut.
Parameter ini juga dapat mencakup satu atau beberapa nilai berikut.
| Nilai | Makna |
|---|---|
|
Jangan memperluas string lingkungan secara otomatis jika nilainya berjenis REG_EXPAND_SZ. |
|
Jika pvData bukan NULL, atur konten buffer ke nol jika gagal. |
|
Jika lpSubKey bukan NULL, buka subkunci yang ditentukan lpSubKey dengan hak akses KEY_WOW64_64KEY.
Untuk informasi tentang hak akses ini, lihat Keamanan Kunci Registri dan Hak Akses.
Anda tidak dapat menentukan RRF_SUBKEY_WOW6464KEY dalam kombinasi dengan RRF_SUBKEY_WOW6432KEY. |
|
Jika lpSubKey bukan NULL, buka subkunci yang ditentukan lpSubKey dengan hak akses KEY_WOW64_32KEY.
Untuk informasi tentang hak akses ini, lihat Keamanan Kunci Registri dan Hak Akses.
Anda tidak dapat menentukan RRF_SUBKEY_WOW6432KEY dalam kombinasi dengan RRF_SUBKEY_WOW6464KEY. |
[out, optional] pdwType
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 ini dapat berupa NULL jika jenisnya tidak diperlukan.
[out, optional] pvData
Penunjuk ke buffer yang menerima data nilai. Parameter ini bisa NULL jika data tidak diperlukan.
Jika data adalah string, fungsi akan memeriksa karakter null yang mengakhiri. Jika tidak ditemukan, string disimpan dengan terminator null jika buffer cukup besar untuk mengakomodasi karakter tambahan. Jika tidak, fungsi gagal dan mengembalikan ERROR_MORE_DATA.
[in, out, optional] pcbData
Penunjuk ke variabel yang menentukan ukuran buffer yang diacu oleh parameter pvData , dalam byte. Ketika fungsi kembali, variabel ini berisi ukuran data yang disalin ke pvData.
Parameter pcbData dapat berupa NULL hanya jika pvData 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 parameter pvData tidak cukup besar untuk menyimpan data, fungsi mengembalikan ERROR_MORE_DATA dan menyimpan ukuran buffer yang diperlukan dalam variabel yang ditunjukkan oleh pcbData. Dalam hal ini, konten buffer pvData adalah nol jika dwFlags menentukan RRF_ZEROONFAILURE dan tidak terdefinisi sebaliknya.
Jika pvData adalah NULL, dan pcbData bukan NULL, fungsi mengembalikan ERROR_SUCCESS dan menyimpan ukuran data, dalam byte, dalam variabel yang diacu oleh pcbData. Ini memungkinkan aplikasi untuk menentukan cara terbaik untuk mengalokasikan buffer untuk data nilai.
Jika hKey menentukan HKEY_PERFORMANCE_DATA dan buffer pvData tidak cukup besar untuk berisi semua data yang dikembalikan, fungsi mengembalikan ERROR_MORE_DATA dan nilai yang dikembalikan melalui parameter pcbData tidak terdefinisi. Ini karena ukuran data performa dapat berubah dari satu panggilan ke panggilan berikutnya. Dalam hal ini, Anda harus meningkatkan ukuran buffer dan memanggil RegGetValue lagi melewati ukuran buffer yang diperbarui dalam parameter pcbData . Ulangi ini hingga fungsi berhasil. Anda perlu mempertahankan variabel terpisah untuk melacak ukuran buffer, karena nilai yang dikembalikan oleh pcbData tidak dapat diprediksi.
Mengembalikan nilai
Jika fungsi berhasil, nilai yang dikembalikan adalah ERROR_SUCCESS.
Jika fungsi gagal, nilai yang dikembalikan adalah kode kesalahan sistem.
Jika buffer pvData terlalu kecil untuk menerima nilai, fungsi mengembalikan ERROR_MORE_DATA.
Jika nilai registri lpValue tidak ada, fungsi mengembalikan ERROR_FILE_NOT_FOUND.
Jika dwFlags menentukan kombinasi RRF_SUBKEY_WOW6464KEY dan RRF_SUBKEY_WOW6432KEY, fungsi mengembalikan ERROR_INVALID_PARAMETER.
Keterangan
Aplikasi biasanya memanggil RegEnumValue untuk menentukan nama nilai lalu RegGetValue untuk mengambil data untuk nama tersebut.
Jika data memiliki jenis REG_SZ, REG_MULTI_SZ, atau REG_EXPAND_SZ, dan versi ANSI dari fungsi ini digunakan (baik dengan secara eksplisit memanggil RegGetValueA atau dengan tidak menentukan UNICODE sebelum menyertakan file Windows.h), fungsi ini mengonversi string Unicode yang disimpan menjadi string ANSI sebelum menyalinnya ke buffer yang ditunjukkan oleh pvData.
Saat memanggil fungsi ini dengan hkey diatur ke handel HKEY_PERFORMANCE_DATA dan string nilai objek tertentu, struktur data yang dikembalikan terkadang memiliki objek yang tidak diminta. Jangan terkejut; ini adalah perilaku normal. Anda harus selalu berharap untuk memandu struktur data yang dikembalikan untuk mencari objek yang diminta.
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.
Untuk mengkompilasi aplikasi yang menggunakan fungsi ini, tentukan _WIN32_WINNT sebagai 0x0600 atau yang lebih baru. Untuk informasi selengkapnya, lihat Menggunakan Header Windows.
Catatan
Header winreg.h mendefinisikan RegGetValue 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, Windows XP Professional x64 Edition |
| Server minimum yang didukung | Windows Server 2008, Windows Server 2003 dengan SP1 |
| Target Platform | Windows |
| Header | winreg.h (termasuk Windows.h) |
| Pustaka | Advapi32.lib |
| DLL | Advapi32.dll |