Using the State and Notifications Broker in Native Code

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

State and Notification Broker can be used to monitor any registry key in the system. The header file snapi.h contains registry definitions for all the base notifications that are provided by the system. For each notification, snapi.h contains the registry root - either HKEY_CURRENT_USER or HKEY_LOCAL_MACHINE, the registry path under the root, and the registry value under the path that contains the value of the notification.

For example the ActiveApplication notification, located at HKEY_CURRENT_USER\System\State\"Active Application" in the registry has the following definitions:

#define SN_ACTIVEAPPLICATION_ROOT HKEY_CURRENT_USER
#define SN_ACTIVEAPPLICATION_PATH TEXT("System\\State\\Shell")
#define SN_ACTIVEAPPLICATION_VALUE TEXT("Active Application")

Some notifications also have a bitmask defined. For example the PhoneNoSim notification has the following definitions:

#define SN_PHONENOSIM_ROOT HKEY_LOCAL_MACHINE
#define SN_PHONENOSIM_PATH TEXT("System\\State\\Phone")
#define SN_PHONENOSIM_VALUE TEXT("Status")
#define SN_PHONENOSIM_BITMASK 2

The bitmask indicates which bit or bits contain the state value of the notification. When registering the notification, it is important to set the bitmask in the NOTIFICATIONCONDITION structure. When receiving the notification, this bitmask is used again to look at only the bits containing the value that has changed.

Code Example

The following code example demonstrates how to use bitmasks when registering a notification and when receiving the notification event.

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.

#include <regext.h>
#include <snapi.h>

// Register the window notification
HRESULT RegisterWindows()
{
  HRESULT hr;
  NOTIFICATIONCONDITION nc;

  // Register the phone call calling notification.
  // By setting dwMask = SN_PHONECALLCALLING_BITMASK, we will get a notification only when there is a 
  // change in the bit indicating whether the phone is currently attempting to connect an outgoing call.

  nc.ctComparisonType = REG_CT_ANYCHANGE;
  nc.dwMask           = SN_PHONECALLCALLING_BITMASK;
  nc.TargetValue.dw   = 0;

  hr = RegistryNotifyCallback(
                SN_PHONECALLCALLING_ROOT,     // registry root to monitor
                SN_PHONECALLCALLING_PATH,     // registry path to monitor
                SN_PHONECALLCALLING_VALUE,    // registry value to monitor
                PhoneCallCallingCallback,     // callback to be called when bit changes
                0,       
                &nc,
                &g_NotifyPhoneCallCalling
                );

  return hr;
}


// Callback function that is called when the bit indicating a call is being made changes
void PhoneCallCallingCallback(HREGNOTIFY hNotify, DWORD dwUserData, const PBYTE pData, const UINT cbData)
{
  DWORD PhoneCallCallingStatus;
  PDWORD pdwData;
  TCHAR PhoneCallCallingStr[STATUS_STRING_LEN];

  StringCchCopy(PhoneCallCallingStr, STATUS_STRING_LEN, L"");

  // get the changed value
  pdwData = (DWORD *)pData;
  PhoneCallCallingStatus = *pdwData;

  // only look at the value of the bit we are interested in
  if (PhoneCallCallingStatus & SN_PHONECALLCALLING_BITMASK)
  {
    StringCchCopy(PhoneCallCallingStr, STATUS_STRING_LEN, L"Attempting to connect an outgoing call");
  }
  else 
  {
    StringCchCopy(PhoneCallCallingStr, STATUS_STRING_LEN, L"Not connecting");
  }

  // TODO: use PhoneCallCallingStr as needed

}

The battery state and battery strength notifications use the high word and low word of the registry setting to determine their values. See the Battery State Application in the SDK for an example on how to use these bitmasks. The table below outlines how to interpret these values.

Notification	Description	Bitmask	Value
PowerBatteryBackupState	Current backup battery state (for example, it is low, and charging). This enumeration allows a bitwise combination of its member values. The actual combinations returned depend on the battery driver implementation. See the header snapi.h for definitions of the state levels.	0x0000FFFF	0 Normal 1 NotPresent 2 Charging 4 Low 8 Critical
PowerBatteryBackupStrength	Remaining backup battery power level.	0xFFFF0000	0 VeryLow 21 Low 41 Medium 61 High 81 VeryHigh
PowerBatteryState	Current battery state (for example, it is low, and charging). This enumeration allows a bitwise combination of its member values. The actual combinations returned depend on the battery driver implementation. See the header snapi.h for definitions of the state levels.	0x0000FFFF	0 Normal 1 NotPresent 2 Charging 4 Low 8 Critical
PowerBatteryStrength	Remaining battery power level.	0xFFFF0000	0 VeryLow 21 Low 41 Medium 61 High 81 VeryHigh

See Also

Reference

State and Notifications Broker Reference

Other Resources

State and Notifications Broker