Fungsi RegQueryValueExW (winreg.h)

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

Sintaksis

LSTATUS RegQueryValueExW(
  [in]                HKEY    hKey,
  [in, optional]      LPCWSTR 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 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] lpValueName

Nama nilai registri.

Jika lpValueName NULL atau string kosong, "", fungsi mengambil jenis dan data untuk nilai kunci yang tidak disebutkan namanya atau 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 null jika kode jenis tidak diperlukan.

[out, optional] lpData

Penunjuk ke buffer yang menerima data nilai. Parameter ini dapat 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 NULL hanya jika lpData NULL .

Jika data memiliki jenis REG_SZ, REG_MULTI_SZ, atau REG_EXPAND_SZ, ukuran ini mencakup karakter atau karakter null 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 NULL, dan lpcbData non-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 meneruskan 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 ditentukan.

Mengembalikan nilai

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 akan mengembalikan ERROR_MORE_DATA.

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

Komentar

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 penghentian yang tepat karakter null. 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 penghentian.) Salah satu cara aplikasi dapat memastikan bahwa string dihentikan dengan benar adalah dengan menggunakan RegGetValue, yang menambahkan penghentian karakter null jika diperlukan.

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

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);
}

Persyaratan

Lihat juga

ExpandEnvironmentStrings

RegCreateKeyEx

RegEnumKeyEx

RegEnumValue

RegGetValue

RegOpenKeyEx

RegQueryInfoKey

Fungsi Registri

Gambaran Umum Registri