Fungsi RegNotifyChangeKeyValue (winreg.h)
Memberi tahu pemanggil tentang perubahan pada atribut atau konten kunci registri tertentu.
Sintaks
LSTATUS RegNotifyChangeKeyValue(
[in] HKEY hKey,
[in] BOOL bWatchSubtree,
[in] DWORD dwNotifyFilter,
[in, optional] HANDLE hEvent,
[in] BOOL fAsynchronous
);
Parameter
[in] hKey
Handel ke kunci registri terbuka. Handel ini dikembalikan oleh fungsi RegCreateKeyEx atau RegOpenKeyEx . Ini juga bisa menjadi salah satu kunci yang telah ditentukan sebelumnya berikut:
HKEY_CLASSES_ROOTHKEY_CURRENT_CONFIGHKEY_CURRENT_USERHKEY_LOCAL_MACHINEHKEY_USERS Parameter ini harus merupakan handel lokal. Jika RegNotifyChangeKeyValue dipanggil dengan handel jarak jauh, regNotifyChangeKeyValue akan mengembalikan ERROR_INVALID_HANDLE.
Kunci harus telah dibuka dengan hak akses KEY_NOTIFY. Untuk informasi selengkapnya, lihat Keamanan Kunci Registri dan Hak Akses.
[in] bWatchSubtree
Jika parameter ini TRUE, fungsi melaporkan perubahan dalam kunci yang ditentukan dan subkuntangannya. Jika parameter false, fungsi melaporkan perubahan hanya dalam kunci yang ditentukan.
[in] dwNotifyFilter
Nilai yang menunjukkan perubahan yang harus dilaporkan. Parameter ini bisa menjadi satu atau beberapa nilai berikut.
[in, optional] hEvent
Handel ke peristiwa. Jika parameter fAsynchronousTRUE, fungsi segera kembali dan perubahan dilaporkan dengan memberi sinyal peristiwa ini. Jika fAsynchronousFALSE, hEvent diabaikan.
[in] fAsynchronous
Jika parameter ini TRUE, fungsi segera mengembalikan dan melaporkan perubahan dengan memberi sinyal peristiwa yang ditentukan. Jika parameter ini FALSE, fungsi tidak kembali sampai perubahan terjadi.
Jika hEvent tidak menentukan peristiwa yang valid, parameter fAsynchronous tidak boleh TRUE.
Mengembalikan nilai
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.
Keterangan
Fungsi ini mendeteksi satu perubahan. Setelah penelepon menerima peristiwa pemberitahuan, pemanggil akan memanggil fungsi lagi untuk menerima pemberitahuan berikutnya.
Jika kunci yang ditentukan ditutup, peristiwa akan disinyalir. Ini berarti bahwa aplikasi tidak boleh bergantung pada kunci yang terbuka setelah kembali dari operasi tunggu pada peristiwa.
Bendera REG_NOTIFY_THREAD_AGNOSTIC yang diperkenalkan di Windows 8 memungkinkan penggunaan utas RegNotifyChangeKeyValue for ThreadPool.
Jika utas yang disebut RegNotifyChangeKeyValue keluar, peristiwa akan disinyalir. Untuk terus memantau perubahan tambahan dalam nilai kunci, panggil RegNotifyChangeKeyValue lagi dari utas lain.
Dengan pengecualian panggilan RegNotifyChangeKeyValue dengan set REG_NOTIFY_THREAD_AGNOSTIC , fungsi ini harus dipanggil pada utas persisten. Jika utas panggilan berasal dari kumpulan utas dan tidak persisten, peristiwa disinyalir setiap kali utas dihentikan, bukan hanya ketika ada perubahan registri. Untuk memastikan hasil yang akurat, jalankan pekerjaan kumpulan utas di utas persisten dengan menggunakan fungsi SetThreadpoolCallbackPersistent , atau buat utas Anda sendiri menggunakan fungsi CreateThread . (Untuk API kumpulan utas asli, tentukan WT_EXECUTEINPERSISTENTTHREAD menggunakan fungsi QueueUserWorkItem .)
Fungsi ini tidak boleh dipanggil beberapa kali dengan nilai yang sama untuk hKey tetapi nilai yang berbeda untuk parameter bWatchSubtree dan dwNotifyFilter . Fungsi akan berhasil tetapi perubahan akan diabaikan. Untuk mengubah
watch parameter, Anda harus terlebih dahulu menutup handel kunci dengan memanggil RegCloseKey, membuka kembali handel kunci dengan memanggil RegOpenKeyEx, lalu memanggil RegNotifyChangeKeyValue dengan parameter baru.
Setiap kali proses memanggil RegNotifyChangeKeyValue dengan serangkaian parameter yang sama, proses ini menetapkan operasi tunggu lain, membuat kebocoran sumber daya. Oleh karena itu, periksa apakah Anda tidak memanggil RegNotifyChangeKeyValue dengan parameter yang sama hingga operasi tunggu sebelumnya selesai.
Untuk memantau operasi registri secara lebih rinci, lihat Registri.
Windows XP/2000: Ketika RegNotifyChangeKeyValue dipanggil untuk handel kunci tertentu, pemberitahuan perubahan terjadi selama handel kunci valid. Ini menyebabkan panggilan kedua ke RegNotifyChangeKeyValue segera kembali, jika ada perubahan yang terjadi sementara antara panggilan pertama dan kedua. Jika fungsi sedang digunakan secara asinkron, handel peristiwa yang diteruskan akan segera disinyalir jika ada perubahan yang terjadi di sementara.
Contoh
Program berikut ini menggambarkan cara menggunakan RegNotifyChangeKeyValue.
#include <windows.h>
#include <tchar.h>
#include <stdio.h>
//void main(int argc, char *argv[])
void __cdecl _tmain(int argc, TCHAR *argv[])
{
DWORD dwFilter = REG_NOTIFY_CHANGE_NAME |
REG_NOTIFY_CHANGE_ATTRIBUTES |
REG_NOTIFY_CHANGE_LAST_SET |
REG_NOTIFY_CHANGE_SECURITY;
HANDLE hEvent;
HKEY hMainKey;
HKEY hKey;
LONG lErrorCode;
// Display the usage error message.
if (argc != 3)
{
_tprintf(TEXT("Usage: notify [HKLM|HKU|HKCU|HKCR|HCC] [<subkey>]\n"));
return;
}
// Convert parameters to appropriate handles.
if (_tcscmp(TEXT("HKLM"), argv[1]) == 0) hMainKey=HKEY_LOCAL_MACHINE;
else if(_tcscmp(TEXT("HKU"), argv[1]) == 0) hMainKey=HKEY_USERS;
else if(_tcscmp(TEXT("HKCU"), argv[1]) == 0) hMainKey=HKEY_CURRENT_USER;
else if(_tcscmp(TEXT("HKCR"), argv[1]) == 0) hMainKey=HKEY_CLASSES_ROOT;
else if(_tcscmp(TEXT("HCC"), argv[1]) == 0) hMainKey=HKEY_CURRENT_CONFIG;
else
{
_tprintf(TEXT("Usage: notify [HKLM|HKU|HKCU|HKCR|HCC] [<subkey>]\n"));
return;
}
// Open a key.
lErrorCode = RegOpenKeyEx(hMainKey, argv[2], 0, KEY_NOTIFY, &hKey);
if (lErrorCode != ERROR_SUCCESS)
{
_tprintf(TEXT("Error in RegOpenKeyEx (%d).\n"), lErrorCode);
return;
}
// Create an event.
hEvent = CreateEvent(NULL, TRUE, FALSE, NULL);
if (hEvent == NULL)
{
_tprintf(TEXT("Error in CreateEvent (%d).\n"), GetLastError());
return;
}
// Watch the registry key for a change of value.
lErrorCode = RegNotifyChangeKeyValue(hKey,
TRUE,
dwFilter,
hEvent,
TRUE);
if (lErrorCode != ERROR_SUCCESS)
{
_tprintf(TEXT("Error in RegNotifyChangeKeyValue (%d).\n"), lErrorCode);
return;
}
// Wait for an event to occur.
_tprintf(TEXT("Waiting for a change in the specified key...\n"));
if (WaitForSingleObject(hEvent, INFINITE) == WAIT_FAILED)
{
_tprintf(TEXT("Error in WaitForSingleObject (%d).\n"), GetLastError());
return;
}
else _tprintf(TEXT("\nChange has occurred.\n"));
// Close the key.
lErrorCode = RegCloseKey(hKey);
if (lErrorCode != ERROR_SUCCESS)
{
_tprintf(TEXT("Error in RegCloseKey (%d).\n"), GetLastError());
return;
}
// Close the handle.
if (!CloseHandle(hEvent))
{
_tprintf(TEXT("Error in CloseHandle.\n"));
return;
}
}
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 |