Fungsi SHRegGetValueA (shlwapi.h)

[SHRegGetValue dapat diubah atau tidak tersedia dalam versi sistem operasi atau produk berikutnya. Gunakan RegGetValue sebagai gantinya.]

Mengambil nilai registri.

Sintaks

LSTATUS SHRegGetValueA(
  [in]      HKEY   hkey,
  [in]      LPCSTR pszSubKey,
  [in]      LPCSTR pszValue,
  [in]      SRRF   srrfFlags,
  [in, out] DWORD  *pdwType,
  [out]     void   *pvData,
  [in, out] DWORD  *pcbData
);

Parameter

[in] hkey

Jenis: HKEY

Handel ke kunci yang saat ini terbuka, atau salah satu nilai yang telah ditentukan sebelumnya berikut ini.

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

[in] pszSubKey

Jenis: LPCTSTR

Penunjuk ke string yang dihentikan null yang menentukan jalur relatif dari hkey ke subkunci untuk mengambil nilai. Parameter ini dapat berupa NULL atau string kosong, dalam hal ini data diambil dari lokasi hkey .

[in] pszValue

Jenis: LPCTSTR

Penunjuk ke string yang dihentikan null yang berisi nama nilai. Parameter ini dapat berupa NULL atau string kosong, dalam hal ini data diambil dari nilai Default.

[in] srrfFlags

Jenis: SRRF

Satu atau beberapa bendera SRRF yang membatasi data untuk diambil. Setidaknya satu nilai pembatasan jenis (SRRF_RT) harus ditentukan.

[in, out] pdwType

Jenis: LPDWORD

Penunjuk ke DWORD yang menerima jenis data yang disimpan dalam nilai yang diambil. Saat menggunakan nilai default, pdwType input adalah jenis nilai default. Untuk nilai yang mungkin, lihat Jenis Data Registri. Jika bendera SRRF_NOEXPAND tidak diatur, jenis REG_EXPAND_SZ secara otomatis diperluas dan dikembalikan sebagai REG_SZ. Jika informasi jenis tidak diperlukan, parameter ini bisa NULL.

[out] pvData

Jenis: LPVOID

Penunjuk ke buffer yang menerima data nilai. Parameter ini bisa NULL jika data tidak diperlukan. Misalnya, jika Anda hanya menguji keberadaan nilai, data nilai tertentu akan berlebihan.

[in, out] pcbData

Jenis: LPDWORD

Penunjuk ke DWORD yang, pada entri, berisi ukuran pvData buffer data tujuan, dalam byte. Nilai ini bisa NULL hanya jika pvDataNULL. Saat keluar, pcbData menunjuk ke salah satu nilai ini.

pvData	Tampilkan Nilai	pcbData
NULL	ERROR_SUCCESS	Ukuran dalam byte cukup untuk menyimpan data registri. Perhatikan bahwa ini tidak dijamin ukuran yang tepat, tetapi hanya ukuran yang cukup.
Non-NULL	ERROR_SUCCESS	Jumlah byte yang tepat yang ditulis ke pvData.
Non-NULL	ERROR_MORE_DATA	Ukuran dalam byte diperlukan untuk menyimpan seluruh data. Perhatikan bahwa ini tidak dijamin ukuran yang tepat, tetapi hanya ukuran yang cukup.

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 kesalahan.

Keterangan

SHRegGetValue menyediakan pemeriksaan jenis data, pemeriksaan mode boot, perluasan otomatis data REG_EXPAND_SZ, dan jaminan penghentian null data REG_SZ, REG_EXPAND_SZ, dan REG_MULTI_SZ.

Kunci yang diidentifikasi oleh hkey harus telah dibuka dengan akses keamanan KEY_QUERY_VALUE . Jika pszSubKey bukan NULL atau string kosong, kunci tersebut juga harus dapat dibuka dengan akses keamanan KEY_QUERY_VALUE dalam konteks panggilan saat ini.

Jika jenis data REG_SZ, REG_EXPAND_SZ, atau REG_MULTI_SZ, maka data yang dikembalikan menyertakan atau memperhitungkan penghentian null string. Misalnya, jika pvData bukan NULL, data yang dikembalikan dalam buffer tersebut dihentikan null. Jika pcbData bukan NULL, ukuran buffer yang ditunjukkannya untuk menyertakan byte yang diperlukan untuk menahan karakter null yang mengakhiri.

Kecuali bendera SRRF_NOEXPAND diatur, data string jenis REG_EXPAND_SZ secara otomatis diperluas sebelum dikembalikan. Jenis string yang diperluas dilaporkan dalam pdwType sebagai REG_SZ, parameter pcbData menunjuk ke jumlah byte yang ditulis untuk string yang diperluas, dan buffer yang diarahkan oleh pvData menyimpan versi string yang diperluas.

Catatan Performa

Jika pszSubKey bukan NULL atau string kosong, kunci tersebut dibuka dan ditutup oleh fungsi ini setiap kali diakses. Jika aplikasi Anda harus mengambil serangkaian nilai dari subkunci yang sama, Anda akan melihat performa yang lebih baik dengan membuka kunci menggunakan RegOpenKeyEx sebelum memanggil SHRegGetValue. Gunakan kunci yang dikembalikan dalam parameter phkResultRegOpenKeyEx sebagai parameter hkey dalam fungsi ini, dengan pszSubKey diatur ke NULL.

Potensi panggilan tambahan ke registri untuk membaca atau membaca ulang data ada ketika jenis data REG_EXPAND_SZ dan bendera SRRF_NOEXPAND belum diatur. Kondisi berikut menghasilkan panggilan tambahan tersebut.

• pvData adalah NULL, pcbData bukan NULL. Meskipun data tidak diambil, registri harus dibaca untuk mendapatkan string dan string tersebut diperluas untuk menentukan ukuran buffer data yang diperlukan.
• pvData bukan NULL, tetapi terlalu kecil untuk menyimpan data. Data dibaca ulang untuk mendapatkan string lengkap, string diperluas, dan ukuran total yang diperlukan ditentukan.

Catatan

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

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP dengan SP2 [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	shlwapi.h
Pustaka	Shlwapi.lib
DLL	Shlwapi.dll (versi 6.0 atau yang lebih baru)

Lihat juga

RegQueryValueEx