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_CONFIGHKEY_CURRENT_USERHKEY_LOCAL_MACHINEHKEY_USERS このパラメーターはローカル ハンドルである必要があります。 RegNotifyChangeKeyValue がリモート ハンドルで呼び出されると、ERROR_INVALID_HANDLEが返されます。

キーは、KEY_NOTIFYアクセス権で開かれている必要があります。 詳細については、「 レジストリ キーのセキュリティとアクセス権」を参照してください。

[in] bWatchSubtree

このパラメーターが TRUE の場合、関数は指定したキーとそのサブキーの変更を報告します。 パラメーターが FALSE の場合、関数は指定されたキー内でのみ変更を報告します。

[in] dwNotifyFilter

報告する必要がある変更を示す 値。 このパラメーターには、次の 1 つ以上の値を指定できます。

[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 をもう一度呼び出します。

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

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

プロセスは、同じパラメーター セットを使用して RegNotifyChangeKeyValue を呼び出すたびに、別の待機操作を確立し、リソース リークを作成します。 したがって、前の待機操作が完了するまで、同じパラメーターで RegNotifyChangeKeyValue を呼び出していないチェック。

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

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

例

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

要件

関連項目

RegCloseKey

RegDeleteKey

RegEnumKeyEx

RegEnumValue

RegQueryInfoKey

RegQueryValueEx

レジストリ関数