Fungsi RegQueryValueExA (winreg.h)

Artikel
03/11/2023

Mengambil jenis dan data untuk nama nilai yang ditentukan yang terkait dengan kunci registri terbuka.

Peringatan

Jika nilai yang dikueri adalah string (REG_SZ, REG_MULTI_SZ, dan REG_EXPAND_SZ) nilai yang dikembalikan TIDAK dijamin akan dihentikan null. Gunakan fungsi RegGetValue jika Anda ingin memastikan nilai string yang dikembalikan dihentikan null. Informasi lebih lanjut ada dalam keterangan di bawah ini.

Sintaks

LSTATUS RegQueryValueExA(
  [in]                HKEY    hKey,
  [in, optional]      LPCSTR  lpValueName,
                      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_PERFORMANCE_NLSTEXT

HKEY_PERFORMANCE_TEXT

HKEY_USERS

[in, optional] lpValueName

Nama nilai registri.

Jika lpValueName adalah NULL atau string kosong, "", fungsi mengambil jenis dan data untuk kunci yang tidak bernama atau nilai default, jika ada.

Jika lpValueName menentukan nilai yang tidak ada dalam registri, fungsi mengembalikan ERROR_FILE_NOT_FOUND.

Kunci tidak secara otomatis memiliki nilai yang tidak disebutkan namanya atau default. Nilai yang tidak disebutkan namanya bisa dari jenis apa pun. Untuk informasi selengkapnya, lihat Batas Ukuran Elemen Registri.

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 nilai. Parameter ini bisa NULL jika data tidak diperlukan.

[in, out, optional] lpcbData

Penunjuk ke variabel yang menentukan ukuran buffer yang diacu oleh parameter lpData , dalam byte. Ketika fungsi kembali, variabel ini berisi ukuran data yang disalin ke lpData.

Parameter lpcbData dapat berupa 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 penghentian kecuali data disimpan tanpanya. Untuk informasi selengkapnya, lihat Keterangan.

Jika buffer yang ditentukan oleh parameter 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, konten buffer lpData tidak terdefinisi.

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

Jika hKey menentukan HKEY_PERFORMANCE_DATA dan buffer lpData tidak cukup besar untuk berisi semua data yang dikembalikan, RegQueryValueEx mengembalikan ERROR_MORE_DATA dan nilai yang dikembalikan melalui parameter lpcbData 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 RegQueryValueEx lagi melewati ukuran buffer yang diperbarui dalam parameter lpcbData . Ulangi ini hingga fungsi berhasil. Anda perlu mempertahankan variabel terpisah untuk melacak ukuran buffer, karena nilai yang dikembalikan oleh lpcbData tidak dapat diprediksi.

Jika nilai registri lpValueName tidak ada, RegQueryValueEx mengembalikan ERROR_FILE_NOT_FOUND dan nilai yang dikembalikan melalui parameter lpcbData tidak terdefinisi.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah ERROR_SUCCESS.

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

Jika buffer lpData terlalu kecil untuk menerima data, fungsi mengembalikan ERROR_MORE_DATA.

Jika nilai registri lpValueName tidak ada, fungsi mengembalikan ERROR_FILE_NOT_FOUND.

Keterangan

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

Jika data memiliki jenis REG_SZ, REG_MULTI_SZ, atau REG_EXPAND_SZ, string mungkin belum disimpan dengan karakter null penghentian 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 yang dihentikan.) Salah satu cara aplikasi dapat memastikan bahwa string dihentikan dengan benar adalah dengan menggunakan RegGetValue, yang menambahkan karakter null yang mengakhiri jika diperlukan.

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 RegQueryValueExA 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 lpData.

Saat memanggil fungsi RegQueryValueEx 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. Saat memanggil fungsi RegQueryValueEx , 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.

Contoh

Pastikan Anda menginisialisasi ulang nilai yang ditunjukkan oleh parameter lpcbData setiap kali Anda memanggil fungsi ini. Ini sangat penting ketika Anda memanggil fungsi ini dalam perulangan, seperti dalam contoh kode berikut.

#include <windows.h>
#include <malloc.h>
#include <stdio.h>

#define TOTALBYTES    8192
#define BYTEINCREMENT 4096

void main()
{
    DWORD BufferSize = TOTALBYTES;
    DWORD cbData;
    DWORD dwRet;

    PPERF_DATA_BLOCK PerfData = (PPERF_DATA_BLOCK) malloc( BufferSize );
    cbData = BufferSize;

    printf("\nRetrieving the data...");

    dwRet = RegQueryValueEx( HKEY_PERFORMANCE_DATA,
                             TEXT("Global"),
                             NULL,
                             NULL,
                             (LPBYTE) PerfData,
                             &cbData );
    while( dwRet == ERROR_MORE_DATA )
    {
        // Get a buffer that is big enough.

        BufferSize += BYTEINCREMENT;
        PerfData = (PPERF_DATA_BLOCK) realloc( PerfData, BufferSize );
        cbData = BufferSize;

        printf(".");
        dwRet = RegQueryValueEx( HKEY_PERFORMANCE_DATA,
                         TEXT("Global"),
                         NULL,
                         NULL,
                         (LPBYTE) PerfData,
                         &cbData );
    }
    if( dwRet == ERROR_SUCCESS )
        printf("\n\nFinal buffer size is %d\n", BufferSize);
    else printf("\nRegQueryValueEx failed (%d)\n", dwRet);
}

Catatan

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