Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
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:

Copy Code
#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:

Copy Code
#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.
Copy Code
#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