RegNotifyChangeKeyValue: Build a Correct Windows Registry Watcher

RegNotifyChangeKeyValue signals that selected attributes or contents of an open registry key changed. It does not tell you which value changed, provide the old or new data, or preserve a complete change history. Use it as an invalidation signal: after notification, reread the configuration you care about and validate the result. This avoids a fragile design that assumes every intermediate update is observable or that an event itself contains the new setting.

Open the key for notification, not for administration

The key handle must include KEY_NOTIFY; use the least access needed for the follow-up read as well. A watcher that only needs to observe values should not request KEY_ALL_ACCESS. Registry access is also scoped to a particular view and user context: choose the intended hive, subkey, and 32-bit or 64-bit view explicitly when that distinction matters. RegNotifyChangeKeyValue requires a local registry handle; it returns ERROR_INVALID_HANDLE for a remote handle. For remote configuration, use an explicitly supported management channel rather than treating this API as a remote subscription mechanism.

The filter should reflect the data contract. REG_NOTIFY_CHANGE_NAME reports subkey add/remove changes; REG_NOTIFY_CHANGE_LAST_SET reports value changes; REG_NOTIFY_CHANGE_ATTRIBUTES and REG_NOTIFY_CHANGE_SECURITY cover other classes. A broad filter on a high-churn parent hive can wake the process frequently and force unnecessary scans. Subscribe as close as possible to the settings the consumer owns.

Notifications are one-shot

Each registration detects one change notification. After the event is signaled, call RegNotifyChangeKeyValue again to request the next one. Treat the signal as “the watched region may be dirty,” not as a count of updates. Several writes may happen before the consumer runs, and the notification does not identify which one mattered. A robust consumer coalesces activity into a dirty flag, rereads the relevant values, validates their types and bounds, then publishes a complete configuration snapshot to its own readers.

The asynchronous form returns immediately and signals an event supplied by the caller. The event, key handle, and state needed by the watcher must remain valid until the registration has completed or been canceled by closing its key handle. A manual-reset event is commonly used so the owner can reset it deliberately before registering again. Check the LSTATUS returned directly by the registry function; registry APIs return Win32 status codes and do not require GetLastError for the returned error.

LSTATUS arm_registry_watch(HKEY key, HANDLE changed) {
    if (!ResetEvent(changed)) {
        return static_cast<LSTATUS>(GetLastError());
    }

    return RegNotifyChangeKeyValue(
        key,
        FALSE,
        REG_NOTIFY_CHANGE_LAST_SET,
        changed,
        TRUE);
}

This helper assumes the caller owns a valid local key opened with KEY_NOTIFY and a valid event handle. Production code should propagate the LSTATUS without confusing it with an HRESULT, and it must serialize calls that would otherwise register overlapping watches with the same key and parameters.

Re-arm and reconcile without inventing event detail

Because the API is one-shot, a long-running watcher should re-arm promptly. One safe approach is to wake on the event, mark configuration dirty, re-arm, then reread the desired values into a temporary snapshot. If the event is signaled again while the snapshot is being read, repeat the reconciliation before publishing. This narrows the interval in which a second change could be missed and makes the final state authoritative even if multiple edits coalesce. Keep the handler idempotent so repeating a snapshot read is harmless.

Do not interpret the event as “one registry value has just changed” or call RegQueryValueEx for an assumed value name. A key can contain several values and subkeys; a transaction or installer may update several related settings over multiple calls. Read and validate the complete group of related values, apply defaults explicitly for absent optional settings, and reject malformed or out-of-range values. If the configuration schema has a version or generation field, use it to detect partial updates and to decide whether to retry.

The API is not a security auditing feed. It does not provide actor identity, operation details, or a durable record of changes. If the product needs forensic attribution or a full audit trail, use a supported auditing or eventing facility. A watcher is for keeping a live process current, not proving who made a past change.

The thread that registers the watch is part of its lifetime

Without REG_NOTIFY_THREAD_AGNOSTIC, notification lifetime is tied to the thread that calls RegNotifyChangeKeyValue. If that thread exits, the event is signaled and monitoring stops. Microsoft also warns that ordinary thread-pool callback threads are not persistent: thread termination can signal the event even when no registry change occurred. Use the thread-agnostic flag on supported Windows versions (Windows 8 and later), a persistent thread-pool callback, or an owned long-lived thread. Include this choice in the minimum supported OS policy rather than assuming the watcher behaves the same everywhere.

Closing the key handle also signals the event. Therefore, a signaled event can mean the key was closed, the registering thread ended, or the requested registry change occurred. Use a separate stop event or an explicit state flag so shutdown is not mistaken for a configuration update. On shutdown, stop rearming, close or otherwise release the registration according to the owner’s design, wait for the watcher to exit, and then close its event and key handles.

The registry’s logical path may have more than one view. A 32-bit process and a 64-bit process can observe different redirected portions of some keys, and per-user state differs from machine-wide state. Match the notification handle to the same view and identity that the consumer later reads; otherwise, the watcher can correctly report changes in one view while the application queries another. Make the intended hive, user, and view part of diagnostic output, while avoiding disclosure of sensitive values.

There is no supported way to change bWatchSubtree or the filter on an existing key handle by simply issuing a second registration with different parameters. Reopen the key with the desired configuration and register again. Also avoid issuing the same registration repeatedly before the earlier one has completed; each call creates another wait operation and can leak resources.

Keep read/write races and privilege boundaries explicit

A value can change between the notification and the subsequent read. It can change again while a group of values is being read. Use RegQueryMultipleValues where its provider and value layout make it appropriate, or use a versioned configuration update protocol in which writers publish a complete generation. For ordinary application settings, a bounded retry loop that rereads until the generation is stable may be enough. Do not make a worker spin indefinitely while an installer continuously changes values.

For machine-wide configuration under HKEY_LOCAL_MACHINE, expect writes to require elevation or a service boundary. A watcher should not elevate simply to read when a narrower read permission suffices. Validate registry data as untrusted input: the registry can contain strings without expected terminators, unexpected value types, or lengths that exceed application buffers. This is especially important when configuration comes from third-party installers or policy extensions.

Test the lifecycle, not only the happy path

In a disposable test key, verify value changes, value deletion, subkey creation, and subkey removal against the filters selected. Test a rapid series of writes before the consumer wakes, a change during a reread, event closure, key closure, and watcher-thread shutdown. If using a thread pool, repeatedly exercise the callback to ensure the chosen thread-agnostic or persistent-thread policy does not generate false wakeups. Confirm the watcher re-arms after every real notification and stops cleanly without retaining duplicate waits.

Log the watched key identifier (not secret value data), filter, registration result, wake reason, reread duration, parse failures, rearm result, and shutdown cause. A health indicator should distinguish a quiet registry from a dead watcher. Periodically checking the watcher’s registered state and using a controlled test notification can provide stronger evidence than interpreting “no event lately” as proof of health.

The reliable contract is intentionally modest: RegNotifyChangeKeyValue tells a live watcher to reconsider a key. Correctness comes from rereading state, validating it, handling thread and handle lifetimes, and treating the event as a coalesced invalidation rather than a transaction log.

Related:

Sources: