Share via


RegistryNotifyWindow

Send Feedback

This function registers a transient change notification request. The specified window receives a notification when a specified value changes.

HRESULT WINAPI RegistryNotifyWindow( 
  HKEY hKey,
  LPCTSTR pszSubKey,
  LPCTSTR pszValueName,
  HWND hWnd,
  UINT msg,
  DWORD dwUserData,
  NOTIFICATIONCONDITION* pCondition,
  HREGNOTIFY* phNotify
);

Parameters

  • hKey
    [in] Handle to the open key or a predefined root value.

  • pszSubKey
    [in] Key where the value is stored. If this value is NULL, then pszValueName is assumed to be under hkey.

  • pszValueName
    [in] Named value on which the notification is based. If the value is NULL, the change notification will be based on the default value.

  • hWnd
    [in] Handle to the window receiving the message.

  • msg
    [in] Message passed to the window.

  • dwUserData
    [in] User data passed back to the window with the notification.

  • pCondition
    [in] Condition that determines when to send the notification. When the comparison between pCondition and the new registry value is TRUE, then a notification is sent.

    If pCondition is NULL, then any change in the specified registry value results in a notification.

  • phNotify
    [out] Handle that receives the notification. This handle must be closed by using RegistryCloseNotification when notifications are no longer needed. Resetting the device also stops the notification.

Return Values

The following table shows the return values for this function.

Value Description
S_OK Request for change notification is registered.
E_ALREADY_REGISTERED Request for notification already exists.
E_INVALIDARG Invalid hKey, phNotify, or hWnd.
An error value returned. Error value wrapped as a FACILITY_WIN32 HRESULT.

Remarks

Success indicates that the caller will be notified every time the specified value changes and the specified condition are true. Failure does not cause any change.

For a client to differentiate between multiple notifications, the msg parameter should be unique for each call to RegistryNotifyWindow made by a client.

To stop notification and to close the notification handle, the caller must call RegistryCloseNotification. However, this type of notification is transient. Resetting the device stops the notification.

When pszValueName changes, PostMessage notifies the client. If PostMessage fails or if hWnd is no longer valid, then the registered notification request is removed and phNotify handle is closed. The following table shows the parameters passed to PostMessage.

Variable names Description
WPARAM For data type REG_DWORD, the new value (or zero if the value was deleted), and zero (0 ) for all other data types.
LPARAM Value passed in dwUserData.

If the value does not exist when RegistryNotifyWindow is called, then the client will be notified when the value is added.

This function can be used to monitor any registry key in the system. The header file snapi.h contains definitions for the registry keys, paths, values, and bitmasks for all the base notifications that are provided by the system.

If the key specified by hKey and pszSubKey doesn't exist, then hKey is monitored until pszSubKey is created, after which pszSubKey is monitored and changes to the key will trigger notifications as requested. To minimize possible performance degradation stemming from a large nuimber of subkeys being monitored, it is a best practice to pass (as hKey) the handle to a key that's as close as possible to pszSubKey rather than passing a root key. For example, if the client is a game and it is monitoring the key structure HKEY_CURRENT_USER\...\MyCoolGame\Player1 and the game could later create HKEY_CURRENT_USER\...\MyCoolGame\Player2, two possible ways to approach notification of changes to the Player2 key include:

Potential performance degradation Fewer potential problems
hKey = handle to HKEY_CURRENT_USER
and
pszSubKey=the full path to Player2
hKey = handle to HKEY_CURRENT_USER\...\MyCoolGame\
and
pszSubKey=Player2

Code Example

The following code example demonstrates how to use RegistryNotifyWindow.

Note   To make the following code example easier to read, security checking and error handling are not included. This code example should not be used in a release configuration unless it has been modified to include them.

// Register to be notified when the next Appointment location changes, 
// and contains the string "Downtown".

LRESULT RegistryNotifyWindowProc(HWND hDlg, UINT msg, UINT wParam, LONG lParam)
{

    TCHAR szLocation[256];
    NOTIFICATIONCONDITION nc;

    LRESULT lRet       = FALSE;
    HREGNOTIFY hNotify = NULL;
    TCHAR szDowntown[] = TEXT("Downtown");

    switch (msg)
    {

        case WM_CREATE:
            // Initialize the notification structure 
            // Note that StatStor is not case sensitive.
            nc.ctComparisonType = REG_CT_CONTAINS;
            nc.TargetValue.psz = szDowntown;

            // A value of zero indicates a string comparison.
            nc.dwMask = 0;

            RegistryNotifyWindow(SN_CALENDARNEXTAPPOINTMENTLOCATION_ROOT, 
                                 SN_CALENDARNEXTAPPOINTMENTLOCATION_PATH, 
                                 SN_CALENDARNEXTAPPOINTMENTLOCATION_VALUE, 
                                 hDlg, 
                                 WM_USER, 
                                 0, 
                                 &nc, 
                                 &hNotify);

            lRet = 0;
            break;

        case WM_USER:
            // You can read the full location with the RegistryGetString function.
            RegistryGetString(SN_CALENDARNEXTAPPOINTMENTLOCATION_ROOT,
                              SN_CALENDARNEXTAPPOINTMENTLOCATION_PATH,
                              SN_CALENDARNEXTAPPOINTMENTLOCATION_VALUE,
                              szLocation, 
                              256);

            // Add your own processing statements here.

            lRet = TRUE;
            break;

        case WM_DESTROY:
            RegistryCloseNotification(hNotify);
            lRet = 0;
            break;

        // Add your own statements for handling other messages, here.

    }

    return lRet;

}

Requirements

Pocket PC: Windows Mobile 5.0 and later.
Smartphone: Windows Mobile 5.0 and later.
OS Versions: Windows CE 5.01 and later.
Header: Regext.h
Link Library: Aygshell.lib

See Also

RegistryBatchNotification | State and Notifications Broker Functions | State and Notifications Broker Reference | State and Notifications Broker | Using the State and Notifications Broker in Native Code

Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.