Fungsi SHRegQueryUSValueA (shlwapi.h)

Mengambil jenis dan data untuk nama tertentu yang terkait dengan subkuntang registri terbuka dalam subtree khusus pengguna (HKEY_CURRENT_USER atau HKEY_LOCAL_MACHINE).

Sintaksis

LSTATUS SHRegQueryUSValueA(
  [in]                HUSKEY hUSKey,
  [in, optional]      LPCSTR pszValue,
  [in, out, optional] DWORD  *pdwType,
  [out, optional]     void   *pvData,
  [in, out]           DWORD  *pcbData,
  [in]                BOOL   fIgnoreHKCU,
  [in, optional]      void   *pvDefaultData,
  [in, optional]      DWORD  dwDefaultDataSize
);

Parameter

[in] hUSKey

Jenis: HUSKEY

Handel ke subkuntang registri yang saat ini terbuka, atau salah satu nilai yang telah ditentukan sebelumnya berikut ini. Subkunjuk harus telah dibuka dengan hak akses KEY_SET_VALUE. Untuk informasi selengkapnya, lihat Keamanan Kunci Registri dan Hak Akses.

Handel ini dapat diperoleh melalui fungsi SHRegOpenUSKey.

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

[in, optional] pszValue

Jenis: LPCTSTR

Penunjuk ke string nulldihentikan yang berisi nama nilai yang akan dikueri.

[in, out, optional] pdwType

Jenis: LPDWORD*

Penunjuk ke variabel yang mengatur atau menerima jenis nilai kunci. Untuk informasi selengkapnya, lihat Jenis Data Registri. Parameter ini dapat null.

[out, optional] pvData

Jenis: LPVOID*

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

[in, out] pcbData

Jenis: LPDWORD*

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

[in] fIgnoreHKCU

Jenis: BOOL

Variabel yang menentukan kunci mana yang akan dilihat. Saat diatur ke TRUE, SHRegQueryUSValue mengabaikan HKEY_CURRENT_USER dan mengembalikan nilai dari kunci di bawah HKEY_LOCAL_MACHINE.

[in, optional] pvDefaultData

Jenis: LPVOID*

Penunjuk ke data default.

[in, optional] dwDefaultDataSize

Jenis: DWORD

Panjangnya, dalam byte, dari data default.

Mengembalikan nilai

Jenis: LSTATUS

Mengembalikan ERROR_SUCCESS jika berhasil, atau kode kesalahan bukan nol yang ditentukan dalam Winerror.h jika tidak. Anda dapat menggunakan fungsi FormatMessage dengan bendera FORMAT_MESSAGE_FROM_SYSTEM untuk mengambil deskripsi umum tentang kesalahan tersebut.

Komentar

Ketika fIgnoreHKCU diatur ke TRUE, SHRegQueryUSValue mengembalikan nilai dari kunci di bawah HKEY_LOCAL_MACHINE. Saat diatur ke FALSE, SHRegQueryUSValue pertama-tama mencoba mengembalikan nilai dari kunci di bawah HKEY_CURRENT_USER. Namun, jika kunci tidak ditemukan di bawah HKEY_CURRENT_USER, nilai dikembalikan dari kunci di bawah HKEY_LOCAL_MACHINE. Jika tidak ada kunci, atau jika terjadi kesalahan dan dwDefaultDataSize bukan nol, maka data default disalin ke pvData dan pengembalian ERROR_SUCCESS. ERROR_SUCCESS mengembalikan untuk data default dan non-default, dan tidak ada cara untuk membedakan salinan nilai mana yang akan pvData. Untuk mencegah penggunaan data default, atur pvDefaultData ke NULL dan dwDefaultDataSize ke nol.

Jika Anda hanya perlu membaca satu nilai, SHRegGetUSValue akan membuka kunci dan mengembalikan nilai. Untuk menggunakanSHRegQueryUSValue , Anda harus terlebih dahulu membuka kunci dengan SHRegOpenUSKey. Namun, setelah kunci dibuka, Anda dapat menggunakan SHRegQueryUSValue sebanyak yang diperlukan. Jika Anda perlu mengambil lebih dari satu nilai dari kunci yang sama, menggunakan beberapa panggilan ke SHRegQueryUSValue biasanya lebih efisien daripada SHRegGetUSValue, karena kunci hanya dibuka sekali.

Nota

Header shlwapi.h mendefinisikan SHRegQueryUSValue sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praproscesor 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

Syarat	Nilai
klien minimum yang didukung	Windows 2000 Professional, Windows XP [hanya aplikasi desktop]
server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Platform Target	Windows
Header	shlwapi.h
Pustaka	Shlwapi.lib
DLL	Shlwapi.dll (versi 4.71 atau yang lebih baru)