RegistryNotifyMsgQueue

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function registers a transient notification request. The specified message queue receives a notification when a specified value changes.

Syntax

HRESULT WINAPI RegistryNotifyMsgQueue(
  HKEY hKey,
  LPCTSTR pszSubKey,
  LPCTSTR pszValueName,
  LPCTSTR pszMsgQueue,
  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.

• pszMsgQueue
  [in] String that specifies the name of the message queue to notify. If this message queue does not exist, then RegistryNotifyMsgQueue creates it.

• dwUserData
  [in] User data passed back to the client 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 to the notification request. This handle must be closed using RegistryCloseNotification when the notifications are no longer needed. . Resetting the device also stops the notification.

Return Value

The following table shows the return values for this function.

Remarks

Success indicates that the caller will get notification everytime the specified value changes. Failure does not cause any change.

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.

If the specified message queue is too small, the notification request that was registered is removed and the user is notified on any changes.

The client receives notification through the specified message queue. When the client receives notification, the client can retrieve the information about the changed key by using the ReadMsgQueue function. The following code shows the format of the data returned by the function:

| HREGNOTIFY hNotify | DWORD dwUserData | UINT byte count | BYTE[] new value |

The following table shows the variable descriptions. The data sent to the message queue can be cast as described in NOTIFYMSGQUEUEPACKET for easier access.

If the value does not exist when RegistryNotifyMsgQueue 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:

Code Example

The following code example demonstrates how to use RegistryNotifyMsgQueue.

// The maximum size of data allowed in Windows Embedded CE is 4 KB.
#define MAX_DATA_LEN_CB 4096
#define MAX_MSGQUEUE_BUFFER_CB (sizeof(NOTIFYMSGQUEUEPACKET) + MAX_DATA_LEN_CB) 
HRESULT RegistryNotifyMsgQueueExample()
{
    DWORD dwBytesRead;
    TCHAR szBuffer[1024];
    DWORD dwOldSignalStrength;
    TCHAR szOldOperatorName[256]; 
    NOTIFYMSGQUEUEPACKET * pPacket;
    HRESULT hr                          = S_OK;
    HREGNOTIFY hNotifyStrength          = NULL;
    HREGNOTIFY hNotifyOperator          = NULL;
    HANDLE hMsgQueue                    = NULL;
    DWORD dwFlags                       = 0;
    MSGQUEUEOPTIONS msgQueueOpts        = {0};
    msgQueueOpts.dwSize       = sizeof(msgQueueOpts);
    msgQueueOpts.dwFlags      = MSGQUEUE_ALLOW_BROKEN;
    msgQueueOpts.cbMaxMessage = MAX_MSGQUEUE_BUFFER_CB;
    msgQueueOpts.bReadAccess  = TRUE;
    hMsgQueue = CreateMsgQueue(TEXT("MyMsgQueue"), &msgQueueOpts);
    // Because MAX_MSGQUEUE_BUFFER_CB is quite large, allocate memory from the heap.
    pPacket = (NOTIFYMSGQUEUEPACKET*) LocalAlloc(LPTR, MAX_MSGQUEUE_BUFFER_CB);
    // Send a notification whenever Signal Strength and Operator Name change.
    hr = RegistryNotifyMsgQueue(SN_PHONESIGNALSTRENGTH_ROOT, 
                                SN_PHONESIGNALSTRENGTH_PATH, 
                                SN_PHONESIGNALSTRENGTH_VALUE, 
                                TEXT("MyMsgQueue"), 
                                1, 
                                NULL, 
                                &hNotifyStrength);
    hr = RegistryNotifyMsgQueue(SN_PHONEOPERATORNAME_ROOT, 
                                SN_PHONEOPERATORNAME_PATH, 
                                SN_PHONEOPERATORNAME_VALUE,
                                TEXT("MyMsgQueue"), 
                                2, 
                                NULL, 
                                &hNotifyOperator);
    // Read the inital values.
    RegistryGetDWORD(SN_PHONESIGNALSTRENGTH_ROOT, 
                     SN_PHONESIGNALSTRENGTH_PATH,
                     SN_PHONESIGNALSTRENGTH_VALUE, 
                     &dwOldSignalStrength);
    RegistryGetString(SN_PHONEOPERATORNAME_ROOT, 
                      SN_PHONEOPERATORNAME_PATH,
                      SN_PHONEOPERATORNAME_VALUE, 
                      szOldOperatorName, 
                      256);
    // Wait to be notified.
    while(ReadMsgQueue(hMsgQueue, pPacket, MAX_MSGQUEUE_BUFFER_CB, &dwBytesRead, INFINITE, &dwFlags))
    {
        // dwUserData can be used to distinguish between different notifications 
        // when there are more than one notification requests in the same application.
    // Signal Strength changed.
    if(1 == pPacket->dwUserData)
        {                            
            // Put the new value into the string buffer.
            StringCchPrintf(szBuffer, 
                            1024, 
                            TEXT("Signal strength changed from %d to %d\n"), 
                            dwOldSignalStrength, 
                            *(DWORD*) pPacket->rgData);
            MessageBox(NULL, szBuffer, TEXT("Signal"), MB_SETFOREGROUND | MB_OK);
            dwOldSignalStrength = *(DWORD*) pPacket->rgData;
        }
    // Operator name changed.
    else if(2 == pPacket->dwUserData)
        {                   
            // Put the new value into the string buffer.
            StringCchPrintf(szBuffer, 
                            1024, 
                            TEXT("Operator changed from %s to %s\n"), 
                            szOldOperatorName, (LPCTSTR) pPacket->rgData);
            MessageBox(NULL, szBuffer, TEXT("Operator"), MB_SETFOREGROUND | MB_OK);
            StringCchCopy(szOldOperatorName, 256,  (LPCTSTR) pPacket->rgData);
        }
    }
    // Clean up.
    hr = RegistryCloseNotification(hNotifyStrength);
    hr = RegistryCloseNotification(hNotifyOperator);
    CloseMsgQueue(hMsgQueue);
    LocalFree(pPacket);
    return hr;
}

Requirements

See Also

Reference

RegistryBatchNotification
State and Notifications Broker Functions
State and Notifications Broker Reference

Concepts

Using the State and Notifications Broker in Native Code

Other Resources

State and Notifications Broker