Fungsi RegQueryValueA (winreg.h)

Artikel
08/27/2023

Mengambil data yang terkait dengan nilai default atau tidak disebutkan namanya dari kunci registri tertentu. Data harus berupa string yang dihentikan null.

Catatan Fungsi ini disediakan hanya untuk kompatibilitas dengan Windows versi 16-bit. Aplikasi harus menggunakan fungsi RegQueryValueEx .

Sintaks

LSTATUS RegQueryValueA(
  [in]                HKEY   hKey,
  [in, optional]      LPCSTR lpSubKey,
  [out, optional]     LPSTR  lpData,
  [in, out, optional] PLONG  lpcbData
);

Parameter

[in] hKey

Handel ke kunci registri terbuka. Kunci harus telah 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_USERS

[in, optional] lpSubKey

Nama subkey parameter hKey tempat nilai default diambil.

Nama kunci tidak peka huruf besar/kecil.

Jika parameter ini NULL atau menunjuk ke string kosong, fungsi mengambil nilai default untuk kunci yang diidentifikasi oleh hKey.

Untuk informasi selengkapnya, lihat Batas Ukuran Elemen Registri.

[out, optional] lpData

Penunjuk ke buffer yang menerima nilai default kunci yang ditentukan.

Jika lpValueADALAH NULL, dan lpcbValuenon-NULL, fungsi mengembalikan ERROR_SUCCESS, dan menyimpan ukuran data, dalam byte, dalam variabel yang ditunjukkan oleh lpcbValue. Ini memungkinkan aplikasi untuk menentukan cara terbaik untuk mengalokasikan buffer untuk data nilai.

[in, out, optional] lpcbData

Penunjuk ke variabel yang menentukan ukuran buffer yang diacu oleh parameter lpValue , dalam byte. Ketika fungsi kembali, variabel ini berisi ukuran data yang disalin ke lpValue, termasuk karakter null yang mengakhiri.

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 lpValue tidak cukup besar untuk menyimpan data, fungsi mengembalikan ERROR_MORE_DATA dan menyimpan ukuran buffer yang diperlukan dalam variabel yang ditunjukkan oleh lpcbValue. Dalam hal ini, konten buffer lpValue tidak terdefinisi.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan ERROR_SUCCESS.

Jika fungsi gagal, nilai yang dikembalikan adalah kode kesalahan sistem.

Jika buffer lpValue terlalu kecil untuk menerima nilai, fungsi akan mengembalikan ERROR_MORE_DATA.

Keterangan

Jika versi ANSI dari fungsi ini digunakan (baik dengan secara eksplisit memanggil RegQueryValueA atau dengan tidak menentukan UNICODE sebelum menyertakan file Windows.h), fungsi ini mengonversi string Unicode yang disimpan ke string ANSI sebelum menyalinnya ke buffer yang ditentukan oleh parameter lpValue .

Jika data memiliki jenis REG_SZ, REG_MULTI_SZ, atau REG_EXPAND_SZ, string mungkin belum disimpan dengan karakter null-terminating 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 null-terminating.)

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 RegQueryValue sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosedur 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