Fungsi RegGetValueA (winreg.h)

Mengambil jenis dan data untuk nilai registri yang ditentukan.

Sintaksis

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 RegCreateKeyEx, RegCreateKeyTransacted, RegOpenKeyEx, atau fungsi RegOpenKeyTransacted. Ini juga bisa menjadi salah satu kunci berikut yang telah ditentukan sebelumnya:

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 NULL atau string kosong, "", fungsi mengambil jenis dan data untuk nilai kunci yang tidak disebutkan namanya atau default, jika ada. Kunci tidak secara otomatis memiliki nilai yang tidak disebutkan namanya 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 berupa satu atau beberapa nilai berikut.

Parameter ini juga dapat menyertakan satu atau beberapa nilai berikut.

[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 null jika jenis tidak diperlukan.

[out, optional] pvData

Penunjuk ke buffer yang menerima data nilai. Parameter ini dapat NULL jika data tidak diperlukan.

Jika data adalah string, fungsi memeriksa karakter null dihentikan. Jika tidak ditemukan, string disimpan dengan null terminator 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 ditujukkan oleh parameter pvData , dalam byte. Ketika fungsi kembali, variabel ini berisi ukuran data yang disalin ke pvData.

Parameter pcbData dapat NULL hanya jika pvData null.

Jika data memiliki jenis REG_SZ, REG_MULTI_SZ, atau REG_EXPAND_SZ, ukuran ini mencakup karakter atau karakter null yang dihentikan. 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 ditentukan sebaliknya.

Jika pvData null, dan pcbData non-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 ditentukan. 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 pvData buffer terlalu kecil untuk menerima nilai, fungsi akan mengembalikan ERROR_MORE_DATA.

Jika nilai registri lpValue tidak ada, fungsi akan mengembalikan ERROR_FILE_NOT_FOUND.

Jika dwFlags menentukan kombinasi RRF_SUBKEY_WOW6464KEY dan RRF_SUBKEY_WOW6432KEY, fungsi akan mengembalikan ERROR_INVALID_PARAMETER.

Komentar

Aplikasi biasanya memanggil RegEnumValue untuk menentukan nama nilai lalu RegGetValue untuk mengambil data untuk nama tersebut.

Jika data memiliki REG_SZ, REG_MULTI_SZ atau jenis 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 ke 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 diRegistri .

Untuk mengkompilasi aplikasi yang menggunakan fungsi ini, tentukan _WIN32_WINNT sebagai 0x0600 atau yang lebih baru. Untuk informasi selengkapnya, lihat Menggunakan Header Windows.

Persyaratan

Lihat juga

RegCreateKeyEx

RegEnumKeyEx

RegEnumValue

RegOpenKeyEx

RegQueryInfoKey

Fungsi Registri

Gambaran Umum Registri