RegNotifyChangeKeyValue 函式 (winreg.h)
通知呼叫端對指定登錄機碼的屬性或內容所做的變更。
語法
LSTATUS RegNotifyChangeKeyValue(
[in] HKEY hKey,
[in] BOOL bWatchSubtree,
[in] DWORD dwNotifyFilter,
[in, optional] HANDLE hEvent,
[in] BOOL fAsynchronous
);
參數
[in] hKey
開啟登錄機碼的控制碼。 RegCreateKeyEx或RegOpenKeyEx函式會傳回此控制碼。 它也可以是下列其中一個 預先定義的索引鍵：
HKEY_CLASSES_ROOTHKEY_CURRENT_CONFIG HKEY_CURRENT_USER HKEY_LOCAL_MACHINEHKEY_USERS此參數必須是本機控制碼。 如果使用遠端控制碼呼叫 RegNotifyChangeKeyValue ，則會傳回ERROR_INVALID_HANDLE。
金鑰必須已以KEY_NOTIFY存取權限開啟。 如需詳細資訊，請參閱 登錄機碼安全性和存取權限。
[in] bWatchSubtree
如果此參數為 TRUE，函式會報告指定索引鍵及其子機碼中的變更。 如果參數為 FALSE，函式只會報告指定索引鍵中的變更。
[in] dwNotifyFilter
值，表示應該報告的變更。 此參數可以是下列一或多個值。
[in, optional] hEvent
事件的控制碼。 如果 fAsynchronous 參數為 TRUE，函式會立即傳回，並透過發出此事件的訊號來報告變更。 如果 fAsynchronous 為 FALSE， 則會忽略 hEvent 。
[in] fAsynchronous
如果此參數為 TRUE，函式會立即傳回 ，並透過發出指定事件的訊號來報告變更。 如果此參數為 FALSE，則函式不會在發生變更之前傳回。
如果 hEvent 未指定有效的事件， 則 fAsynchronous 參數不可以是 TRUE。
傳回值
如果函式成功，傳回值會ERROR_SUCCESS。
如果函式失敗，傳回值是 Winerror.h 中定義的非零錯誤碼。 您可以使用 FormatMessage 函式搭配 FORMAT_MESSAGE_FROM_SYSTEM 旗標，以取得錯誤的一般描述。
備註
此函式會偵測單一變更。 呼叫端收到通知事件之後，應該再次呼叫 函式以接收下一個通知。
如果指定的索引鍵已關閉，事件就會發出訊號。 這表示應用程式不應該相依于從事件的等候作業傳回之後所開啟的金鑰。
Windows 8 中引進 的REG_NOTIFY_THREAD_AGNOSTIC 旗標可讓您使用 RegNotifyChangeKeyValue for ThreadPool 執行緒。
如果呼叫 RegNotifyChangeKeyValue 的執行緒結束，就會發出事件訊號。 若要繼續監視機碼值中的其他變更，請再次從另一個執行緒呼叫 RegNotifyChangeKeyValue 。
除了已設定REG_NOTIFY_THREAD_AGNOSTIC的RegNotifyChangeKeyValue呼叫之外，必須在持續性執行緒上呼叫此函式。 如果呼叫執行緒來自執行緒集區且不持續，則每次執行緒終止時都會發出事件訊號，而不只是發生登錄變更時。 若要確保正確結果，請使用 SetThreadpoolCallbackPersistent 函式在持續性執行緒中執行執行緒集區工作，或使用 CreateThread 函式建立您自己的執行緒。 (針對原始執行緒集區 API，請使用 QueueUserWorkItem 函式指定WT_EXECUTEINPERSISTENTTHREAD。)
此函式不應多次呼叫 hKey 的值相同，但 bWatchSubtree 和 dwNotifyFilter 參數的值不同。 函式將會成功，但將會忽略變更。 若要變更
watch參數，您必須先呼叫RegCloseKey來關閉金鑰控制碼、藉由呼叫RegOpenKeyEx重新開啟金鑰控制碼，然後使用新的參數呼叫RegNotifyChangeKeyValue。
每次進程使用相同的參數集呼叫 RegNotifyChangeKeyValue 時，都會建立另一個等候作業，並建立資源流失。 因此，請檢查您未使用相同的參數呼叫 RegNotifyChangeKeyValue ，直到先前的等候作業完成為止。
若要更詳細地監視登錄作業，請參閱 登錄。
Windows XP/2000： 針對特定金鑰控制碼呼叫 RegNotifyChangeKeyValue 時，只要金鑰控制碼有效，就會發生變更通知。 這會導致第二次呼叫 RegNotifyChangeKeyValue 立即傳回，如果在第一次和第二次呼叫之間發生任何變更。 如果函式是以非同步方式使用，如果過渡期間發生任何變更，則傳遞的事件控制碼會立即發出訊號。
範例
下列程式說明如何使用 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;
}
}
規格需求
| 最低支援的用戶端 | Windows 2000 Professional [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows 2000 Server [僅限桌面應用程式] |
| 目標平台 | Windows |
| 標頭 | winreg.h (包含 Windows.h) |
| 程式庫 | Advapi32.lib |
| Dll | Advapi32.dll |