RegNotifyChangeKeyValue 関数 (winreg.h)

指定したレジストリ キーの属性または内容の変更について呼び出し元に通知します。

構文

LSTATUS RegNotifyChangeKeyValue(
  [in]           HKEY   hKey,
  [in]           BOOL   bWatchSubtree,
  [in]           DWORD  dwNotifyFilter,
  [in, optional] HANDLE hEvent,
  [in]           BOOL   fAsynchronous
);

Parameters

[in] hKey

開いているレジストリ キーへのハンドル。 このハンドルは、 RegCreateKeyEx または RegOpenKeyEx 関数によって返されます。 また、次のいずれかの 定義済みキーを指定することもできます。

HKEY_CLASSES_ROOT、 HKEY_CURRENT_CONFIG、 HKEY_CURRENT_USER、 HKEY_LOCAL_MACHINE、 HKEY_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 で定義されている 0 以外のエラー コードです。 FORMAT_MESSAGE_FROM_SYSTEM フラグと共に FormatMessage 関数を使用すると、エラーの一般的な説明を取得できます。

注釈

この関数は、1 つの変更を検出します。 呼び出し元は、通知イベントを受信した後、関数をもう一度呼び出して次の通知を受信する必要があります。

指定したキーが閉じている場合、イベントが通知されます。 つまり、アプリケーションは、イベントの待機操作から戻った後に開いているキーに依存しないようにする必要があります。

Windows 8で導入された REG_NOTIFY_THREAD_AGNOSTIC フラグを使用すると、ThreadPool スレッドに対して RegNotifyChangeKeyValue を使用できます。

RegNotifyChangeKeyValue を呼び出したスレッドが終了すると、イベントが通知されます。 キーの値の追加の変更を引き続き監視するには、別のスレッドから RegNotifyChangeKeyValue を再度呼び出します。

REG_NOTIFY_THREAD_AGNOSTICが設定された RegNotifyChangeKeyValue 呼び出しを除き、この関数は永続的なスレッドで呼び出す必要があります。 呼び出し元のスレッドがスレッド プールからのものであり、永続的でない場合は、レジストリの変更がある場合だけでなく、スレッドが終了するたびにイベントが通知されます。 正確な結果を得るには、 SetThreadpoolCallbackPersistent 関数を使用して永続的なスレッドでスレッド プールの作業を実行するか、 CreateThread 関数を使用して独自のスレッドを作成します。 (元のスレッド プール API の場合は、 QueueUserWorkItem 関数を使用してWT_EXECUTEINPERSISTENTTHREADを指定します)。

この関数は 、hKey に同じ値を指定して複数回呼び出すことはできませんが、 bWatchSubtree パラメーターと dwNotifyFilter パラメーターの値は異なります。 関数は成功しますが、変更は無視されます。 を変更するには
ウォッチ パラメーターでは、まず RegCloseKey を呼び出してキー ハンドルを閉じ、 RegOpenKeyEx を呼び出してキー ハンドルを再度開き、新しいパラメーターで RegNotifyChangeKeyValue を呼び出す必要があります。

プロセスが同じパラメーター セットで RegNotifyChangeKeyValue を呼び出すたびに、別の待機操作が確立され、リソース リークが発生します。 したがって、前の待機操作が完了するまで、同じパラメーターで RegNotifyChangeKeyValue を呼び出していないかどうかを確認します。

レジストリ操作の詳細については、「レジストリ 」を参照してください。

Windows XP/2000: RegNotifyChangeKeyValue が特定のキー ハンドルに対して呼び出されると、キー ハンドルが有効である限り、変更通知が発生します。 これにより、最初の呼び出しと 2 番目の呼び出しの中間で変更が発生した場合、 RegNotifyChangeKeyValue の 2 回目の呼び出しが直ちに返されます。 関数が非同期的に使用されている場合、中間で変更が発生した場合、渡されたイベント ハンドルは直ちに通知されます。

Examples

次のプログラムは、 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;
   }
}

Requirements

こちらも参照ください

RegCloseKey

RegDeleteKey

RegEnumKeyEx

RegEnumValue

RegQueryInfoKey

RegQueryValueEx

レジストリ関数