Fungsi RegGetValueA (winreg.h)

Artikel
03/08/2023

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.

Nilai	Makna
RRF_RT_ANY 0x0000ffff	Tidak ada batasan jenis.
RRF_RT_DWORD 0x00000018	Membatasi jenis ke RRF_RT_REG_BINARY 32-bit \| RRF_RT_REG_DWORD.
RRF_RT_QWORD 0x00000048	Membatasi jenis ke RRF_RT_REG_BINARY 64-bit \| RRF_RT_REG_QWORD.
RRF_RT_REG_BINARY 0x00000008	Batasi jenis untuk REG_BINARY.
RRF_RT_REG_DWORD 0x00000010	Batasi jenis untuk REG_DWORD.
RRF_RT_REG_EXPAND_SZ 0x00000004	Batasi jenis untuk REG_EXPAND_SZ.
RRF_RT_REG_MULTI_SZ 0x00000020	Batasi jenis untuk REG_MULTI_SZ.
RRF_RT_REG_NONE 0x00000001	Batasi jenis untuk REG_NONE.
RRF_RT_REG_QWORD 0x00000040	Batasi jenis untuk REG_QWORD.
RRF_RT_REG_SZ 0x00000002	Batasi jenis untuk REG_SZ.

Parameter ini juga dapat mencakup satu atau beberapa nilai berikut.

Nilai	Makna
RRF_NOEXPAND 0x10000000	Jangan memperluas string lingkungan secara otomatis jika nilainya berjenis REG_EXPAND_SZ.
RRF_ZEROONFAILURE 0x20000000	Jika pvData bukan NULL, atur konten buffer ke nol jika gagal.
RRF_SUBKEY_WOW6464KEY 0x00010000	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.
RRF_SUBKEY_WOW6432KEY 0x00020000	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