RegNotifyChangeKeyValue

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

RegNotifyChangeKeyValue hKey, bWatchSubtree, dwNotifyFilter, hEvent, fAsynchronous

hKey : [intptr] 開かれているレジストリキーへのハンドル。このハンドルは RegCreateKeyEx または RegOpenKeyEx 関数が返す。以下の定義済みキーのいずれかを指定することもできる:
bWatchSubtree : [int] このパラメータが TRUE の場合、関数は指定したキーとそのサブキーの変更を報告する。FALSE の場合、指定したキーの変更のみを報告する。
dwNotifyFilter : [int] 
hEvent : [intptr] イベントへのハンドル。fAsynchronous パラメータが TRUE の場合、関数はただちに復帰し、変更はこのイベントをシグナル状態にすることで報告される。fAsynchronous が FALSE の場合、hEvent は無視される。
fAsynchronous : [int] このパラメータが TRUE の場合、関数はただちに復帰し、指定したイベントをシグナル状態にすることで変更を報告する。このパラメータが FALSE の場合、関数は変更が発生するまで復帰しない。

(プラグイン / モジュール : advapi32.dll)

解説

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

[戻り値]
関数が成功した場合、戻り値は ERROR_SUCCESS となる。関数が失敗した場合、戻り値は Winerror.h で定義された 0
以外のエラーコードとなる。FormatMessage 関数に FORMAT_MESSAGE_FROM_SYSTEM
フラグを指定して呼び出すと、エラーの一般的な説明を取得できる。

[備考]
この関数は単一の変更を検出する。呼び出し側が通知イベントを受け取った後、次の通知を受けるにはこの関数を再度呼び出す必要がある。注意:
Windows NT、Windows 2000、Windows XP では、特定のキーハンドルに対して
RegNotifyChangeKeyValue
を呼び出すと、そのキーハンドルが有効である限り変更通知が継続して発生する。これにより、最初の呼び出しと 2
回目の呼び出しの間に変更が発生していた場合、2 回目の RegNotifyChangeKeyValue 呼び出しはただちに復帰する。API
が非同期で使用されている場合、間に変更が発生していれば渡されたイベントハンドルはただちにシグナル状態になる。この関数は、RegRestoreKey
関数の使用に起因するレジストリへの変更を検出するために使用できない。指定したキーが閉じられると、イベントはシグナル状態になる。つまり、アプリケーションはイベントに対する待機操作から復帰した後もキーが開いたままであると想定すべきではない。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
回目の呼び出しの間に変更が発生していた場合、2 回目の RegNotifyChangeKeyValue
呼び出しはただちに復帰する。関数が非同期で使用されている場合、間に変更が発生していれば渡されたイベントハンドルはただちにシグナル状態になる。

情報