共用方式為

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

值，表示應該報告的變更。 此參數可以是下列一或多個值。

值 意義
REG_NOTIFY_CHANGE_NAME
0x00000001L
 如果新增或刪除子機碼，請通知呼叫端。
REG_NOTIFY_CHANGE_ATTRIBUTES
0x00000002L
 通知呼叫端金鑰屬性的變更，例如安全性描述項資訊。
REG_NOTIFY_CHANGE_LAST_SET
0x00000004L
 通知呼叫端對索引鍵值的變更。 這包括新增或刪除值，或變更現有的值。
REG_NOTIFY_CHANGE_SECURITY
0x00000008L
 通知呼叫端金鑰之安全性描述項的變更。
REG_NOTIFY_THREAD_AGNOSTIC
0x100000000L
 表示註冊的存留期不得系結至發出 RegNotifyChangeKeyValue 呼叫之執行緒的存留期。
注意 只有 Windows 8 和更新版本才支援這個旗標值。
 

[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 NT、Windows 2000 和 Windows XP 針對特定金鑰控制碼呼叫 RegNotifyChangeKeyValue 時，只要金鑰控制碼有效，變更通知就會繼續發生。 這會導致第二次呼叫 RegNotifyChangeKeyValue 立即傳回，如果在第一次和第二次呼叫之間的過渡期間發生任何變更。 如果 API 是以非同步方式使用，則如果發生任何過渡性變更，則傳遞的事件控制碼將會立即發出訊號。
 
此函式無法用來偵測使用 RegRestoreKey 函式所產生的登錄變更。

如果指定的索引鍵已關閉，事件就會發出訊號。 這表示應用程式不應該相依于從事件的等候作業傳回之後所開啟的金鑰。

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

另請參閱

RegCloseKey

RegDeleteKey

RegEnumKeyEx

RegEnumValue

RegQueryInfoKey

RegQueryValueEx

登錄函式