Fungsi RegOpenKeyExA (winreg.h)

Artikel
03/13/2024

Membuka kunci registri yang ditentukan. Perhatikan bahwa nama kunci tidak peka huruf besar/kecil.

Untuk melakukan operasi registri yang ditransaksikan pada kunci, panggil fungsi RegOpenKeyTransacted .

Sintaks

LSTATUS RegOpenKeyExA(
  [in]           HKEY   hKey,
  [in, optional] LPCSTR lpSubKey,
  [in]           DWORD  ulOptions,
  [in]           REGSAM samDesired,
  [out]          PHKEY  phkResult
);

Parameter

[in] hKey

Handel ke kunci registri terbuka. Handel ini dikembalikan oleh fungsi RegCreateKeyEx atau RegOpenKeyEx , atau dapat menjadi salah satu kunci yang telah ditentukan sebelumnya berikut:

HKEY_CLASSES_ROOTHKEY_LOCAL_MACHINE HKEY_CURRENT_CONFIGHKEY_CURRENT_USERHKEY_USERS

[in, optional] lpSubKey

Nama subkunji registri yang akan dibuka.

Nama kunci tidak peka huruf besar/kecil.

Jika parameter lpSubKey adalah NULL atau pointer ke string kosong, dan jika hKey adalah kunci yang telah ditentukan sebelumnya, maka sistem me-refresh kunci yang telah ditentukan sebelumnya, dan phkResult menerima handel hKey yang sama yang diteruskan ke fungsi. Jika tidak, phkResult menerima handel baru ke kunci yang dibuka.

Untuk informasi selengkapnya, lihat Batas Ukuran Elemen Registri.

[in] ulOptions

Menentukan opsi untuk diterapkan saat membuka kunci. Atur parameter ini ke nol atau berikut ini:

Nilai	Makna
REG_OPTION_OPEN_LINK	Kuncinya adalah tautan simbolis. Tautan simbolis registri hanya boleh digunakan jika benar-benar diperlukan.

[in] samDesired

Masker yang menentukan hak akses yang diinginkan ke kunci yang akan dibuka. Fungsi gagal jika pendeskripsi keamanan kunci tidak mengizinkan akses yang diminta untuk proses panggilan. Untuk informasi selengkapnya, lihat Keamanan Kunci Registri dan Hak Akses.

[out] phkResult

Penunjuk ke variabel yang menerima handel ke kunci yang dibuka. Jika kunci bukan salah satu kunci registri yang telah ditentukan sebelumnya, panggil fungsi RegCloseKey setelah Anda selesai menggunakan handel.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan ERROR_SUCCESS.

Jika fungsi gagal, nilai yang dikembalikan adalah kode kesalahan bukan nol yang ditentukan dalam Winerror.h. Anda dapat menggunakan fungsi FormatMessage dengan bendera FORMAT_MESSAGE_FROM_SYSTEM untuk mendapatkan deskripsi umum tentang kesalahan tersebut.

Catatan

Pada versi lama Windows, API ini juga diekspos oleh kernel32.dll.

Keterangan

Tidak seperti fungsi RegCreateKeyEx , fungsi RegOpenKeyEx tidak membuat kunci yang ditentukan jika kunci tidak ada di registri.

Operasi registri tertentu melakukan pemeriksaan akses terhadap pendeskripsi keamanan kunci, bukan masker akses yang ditentukan ketika handel ke kunci diperoleh. Misalnya, bahkan jika kunci dibuka dengan samDesired KEY_READ, kunci tersebut dapat digunakan untuk membuat kunci registri jika deskriptor keamanan kunci mengizinkan. Sebaliknya, fungsi RegSetValueEx secara khusus mengharuskan kunci dibuka dengan hak akses KEY_SET_VALUE.

Jika layanan atau aplikasi Anda meniru pengguna yang berbeda, jangan gunakan fungsi ini dengan HKEY_CURRENT_USER. Sebagai gantinya, panggil fungsi RegOpenCurrentUser .

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

lResult = RegOpenKeyEx (hKeyRoot, lpSubKey, 0, KEY_READ, &hKey);

if (lResult != ERROR_SUCCESS) 
{
    if (lResult == ERROR_FILE_NOT_FOUND) {
        printf("Key not found.\n");
        return TRUE;
    } 
    else {
        printf("Error opening key.\n");
        return FALSE;
    }
}

Untuk melihat contoh ini dalam konteks, lihat Menghapus Kunci dengan Subkey.

Catatan

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