When working in C\C++ you register for conditional notification by passing the NOTIFICATIONCONDITION structure to the RegistryNotifyWindow function. The NOTIFICATIONCONDITION structure enables you to specify both the target value against which you would like to compare the state value, and what kind of comparison that you would like to perform. You specify the kind of comparison that you would like to perform by using the REG_COMPARISONTYPE enumeration. Table 1 shows the list of REG_COMPARISONTYPE enumeration values.

Table 1. REG_COMPARISONTYPE enumeration members

Note:

All comparison enumeration values can be used with string state values and with DWORD state values, with the exception of REG_CT_CONTAINS, REG_CT_STARTS_WITH and REG_CT_ENDS_WITH, all of which can only be used with string state values. The State and Notifications Broker performs string comparisons by using the CompareString function. When performing greater-than and less-than comparisons, the CompareString function uses the sort order of the device's currently set default locale. String comparisons are all case insensitive.

Using the NOTIFICATIONCONDITION structure, you can instruct the State and Notifications Broker to only notify the application when the new PhoneIncomingCallerName state value contains the string "Mrs. Wilson".

The following code example modifies the call to the RegistryNotifyWindow function, which was shown in the first code example in the “Conditional Notifications” section, to use the NOTIFICATIONCONDITION structure to create the appropriate conditional notification.

                NOTIFICATIONCONDITION condition;
condition.ctComparisonType = REG_CT_CONTAINS;
condition.TargetValue.psz = _T("Mrs. Wilson");

HRESULT hResult = RegistryNotifyWindow(SN_PHONEINCOMINGCALLERNAME_ROOT, 
  SN_PHONEINCOMINGCALLERNAME_PATH, SN_PHONEINCOMINGCALLERNAME_VALUE, 
  g_hWnd, WM_REGISTRYNOTIFY, 0, &condition,
  &_hPhoneIncomingCallerName);

One thing to note about the NOTIFICATIONCONDITION structure is the TargetValue member, which is defined as a union. The union has two members, psz and dw, which correspond to the two State and Notifications Broker API notification data types, string and DWORD. Just as you would expect, the above example uses the psz member because the PhoneIncomingCallerName state value is a string.

With the State and Notifications Broker now sending notifications only when the incoming caller name contains the desired value of "Mrs. Wilson", the notification message handler code in the application WndProc function no longer needs to perform the condition check.

The following code example modifies the message handler code that was contained in the WndProc code example that was shown earlier to now handle the conditional notification.

    case WM_REGISTRYNOTIFY:
    {
      TCHAR callerName[256];
      RegistryGetString(SN_PHONEINCOMINGCALLERNAME_ROOT,
        SN_PHONEINCOMINGCALLERNAME_PATH, 
        SN_PHONEINCOMINGCALLERNAME_VALUE, callerName,
        sizeof(callerName)/sizeof(callerName[0]));
    // No longer required to check contents of state value
    UpdateAppStatusBar(_T("Mommy's Calling"));

    break;
    }

Although the conditional notification only slightly reduces the amount of code that is used to handle the notification, the conditional notification's effect is more far reaching than that. In the case of the unconditional notification, the State and Notifications Broker sends a notification on every incoming call. For someone who receives lots of phone calls, the State and Notifications Broker may send tens or even hundreds of notifications each day, with most of them being ignored by the application.

By using a conditional notification, the State and Notifications Broker sends a notification only when the state value meets the criteria that you specify. As a result, only a few notifications are sent, and each one is pertinent to the application. This reduction in notifications improves the performance of both the application and the device. In some situations, the use of conditional notifications can significantly increase the battery life as compared to sending a notification on every value change especially on frequently changing values.

As you'll recall from Part 1 of this column, not all state values can be used directly. Some DWORD state values require the use of bitmasks because the DWORD value that is stored in the registry may contain several distinct state values. In such situations, the state value that is of interest occupies only a portion of the bits of the DWORD value that is stored in the registry. To find the state value, you must use the bitwise-AND operator to apply the bitmask to the registry value. All DWORD state values have a bitmask that is defined in snapi.h. For those state values that are represented by the entire registry value, the bitmask is defined as -1 (0xFFFFFFFF) – all bits on.

Note   If you would like a refresher on the role of bitmasks in the State and Notifications Broker API, check out the section "Working with DWORD Values and Bitmasks in Native Code" in Part 1 of this column.

For conditional notifications of DWORD state values to work correctly, you must always assign the state value's bitmask to the dwMask member of the NOTIFICATIONCONDITION structure. This is true even when the state value occupies the entire DWORD state value in the registry because the State and Notifications Broker always performs the conditional test in two parts: first, the State and Notifications Broker determines the actual state value by performing a bitwise-AND operation between the DWORD value that is stored in the registry and the bitmask that is contained in the dwMask member. The condition is then tested by using the state value as determined by using the bitwise-AND operator.

The following example shows how to register for a notification when the device's main battery reaches a critical state.

NOTIFICATIONCONDITION condition;
condition.ctComparisonType = REG_CT_EQUAL;
condition.dwMask = SN_POWERBATTERYSTATE_BITMASK;
condition.TargetValue.dw = BATTERYSTATE_CRITICAL;

HRESULT hResult = RegistryNotifyWindow(SN_POWERBATTERYSTATE_ROOT, 
  SN_POWERBATTERYSTATE_PATH, SN_POWERBATTERYSTATE_VALUE, 
  g_hWnd, WM_BATTERYSTATECRITICAL, 0, &condition, 
  &g_hBatteryStateCritical);

Note:
The constant value BATTERYSTATE_CRITICAL is borrowed from the bitmask example code in Part 1 of this column. BATTERYSTATE_CRITICAL is defined as the value 8 which is the documented state value for a critical battery state.

As you'll recall from Part 1 of this column, notification handling when using the managed State and Notifications Broker API is an extension of the .NET delegate/event model. Your application need only create an instance of the SystemState class, pass the appropriate SystemProperty enumeration for the state value of interest and then associate a delegate with the SystemState instance's Change event. The application function associated with the Change event is then called each time the state value associated with the SystemState instance changes.

Note:
If you would like a refresher on the managed State and Notifications Broker API's notification handling see the section “Receiving Notifications in Managed Code” in Part 1 of this column.

All of the information about raising state change notifications is part of the SystemState instance. To make the change events raised by the SystemState instance conditional, set the ComparisonType property and the ComparisonValue property of the SystemState instance.

The ComparisonType property accepts the StatusComparisonType enumeration, the values of which correspond to the values of the C\C++ enumeration REG_COMPARISONTYPE. Table 2 lists and describes the StatusComparisonType enumeration values.

Table 2. StatusComparisonType enumeration members

Just like in the earlier native example code, the following code example also demonstrates how to use managed code to create a conditional notification that enables the State and Notifications Broker to only notify the application of a change in the PhoneIncomingCallerName state value when the incoming caller name contains "Mrs. Wilson".

SystemState _incomingCallerName;

public Form1()
{
  InitializeComponent();

  _incomingCallerName = 
    new SystemState(SystemProperty.PhoneIncomingCallerName);
  _incomingCallerName.ComparisonType = StatusComparisonType.Contains;
  _incomingCallerName.ComparisonValue = "Mrs. Wilson";
  _incomingCallerName.Changed += 
    new ChangeEventHandler(IncomingCallerName_Changed);
}

void IncomingCallerName_Changed(object sender, ChangeEventArgs args)
{
  messageStatusBar.Text = "Mommy's Calling";
}

One thing to remember when creating conditional notifications with the SystemState class is that you must set the ComparisonType property and the ComparisonValue properties before you attach a delegate to the Changed event. If you try to set either of these properties after you have attached a delegate to the Changed event, they will throw a StateException exception.

As you know, the managed State and Notifications Broker API ultimately uses the native API to interact with the State and Notifications Broker. This doesn't mean that every action that is performed on a managed class such as the SystemState class results in a call to the native API; rather, the managed API creates an abstraction and calls the native API at the appropriate times. One such situation where the SystemState class calls the native API is when the delegate is attached to the Changed event.

Before you attach a delegate to the SystemState.Changed event, the SystemState instance is simply a managed object; it makes no calls to the native State and Notifications Broker API. But when you attach a delegate to the Changed event, the SystemState class creates the actual notification by calling the native RegistryNotifyWindow function. Once the call is made to the RegistryNotifyWindow function, the SystemState instance is directly associated with the newly created notification. Just as in the case of the native API, once you create a notification, you cannot change or add a condition to the notification; instead, you must create a new notification which, in the managed API, requires a new instance of the SystemState class.

As you'll recall from Part 1 of this column, the SystemState class hides the fact that the use of a bitmask is required to access some values. This same encapsulation is true when performing conditional notifications; therefore, bitmasks require no special handling.

Note:
The SystemState class exposes a BitMask property but it is not used. This BitMask property is an artifact of the StateBase class, which is the base class of the SystemState class. Any attempt to set or to access the SystemState.Bitmask property will throw a NotSupportedException exception.

With the bitmask details encapsulated in the SystemState class, the managed implementation of the critical battery state notification, shown earlier in C\C++, is basically the same as the managed implementation of the PhoneIncomingCallerName state value above. The following code example shows you how to set up a battery state notification so that it’s only sent when the battery reaches a critical state.

SystemState _batteryState;

void SetupCriticalBatteryStateNotification()
{
  _batteryState = new SystemState(SystemProperty.PowerBatteryState);
  _batteryState.ComparisonType = StatusComparisonType.Equal;
  _batteryState.ComparisonValue = BatteryState.Critical;
  _batteryState.Changed += 
    new ChangeEventHandler(BatteryStateCritical);
}

void BatteryStateCritical(object sender, ChangeEventArgs args)
{
  // Turn off unneeded features
}

Unlike a conditional notification in which the conditional criteria are provided to the notification at the time that you create the notification, a batch notification operates on an existing notification. You create a notification just as you normally would, by using the RegistryNotifyWindow structure, with or without a condition associated. Then, you make that notification a batch notification by passing the notification handle to the RegistryBatchNotification function.

Again unlike conditional notifications, in which the condition that is associated with a notification cannot be changed, you can change the idle time and the maximum delay time for batch notifications whenever you want. This enables you to modify the notification timing based on any number of factors, including user input, battery power, other activity on the device, and so on.

The following code example demonstrates how to create a batch notification for the Microsoft® Windows Media® Player Mobile track title state value.

HREGNOTIFY g_hTrackTitle;
const DWORD idleTime = 3000;
const DWORD maxDelay = 10000;
// Create initial notification
HRESULT hResult = RegistryNotifyWindow(SN_MEDIAPLAYERTRACKTITLE_ROOT, 
  SN_MEDIAPLAYERTRACKTITLE_PATH, SN_MEDIAPLAYERTRACKTITLE_VALUE, 
  g_hWnd, WM_TRACKTITLECHANGE, 0, NULL, 
  &g_hTrackTitle); 
// Now make it a batch notification
if (SUCCEEDED(hResult))
  RegistryBatchNotification(g_hTrackTitle, idleTime, maxDelay);

As you can see, the notification is created normally, and is then made a batch notification that requires that the track title remain constant for three seconds, in order for the State and Notifications Broker to notify the application about the track title change. In the event that the track title keeps changing for a long period of time without being stable for at least three seconds, a notification is still sent every 10 seconds.

The managed State and Notifications Broker API does not provide a way to create batch notifications. I found this a little disappointing at first. Managed applications handle notifications by calling a delegate, which has a higher overhead as compared to a native application, which simply handles window messages. Given the cost of calling a delegate, it's important that managed applications avoid processing notifications unnecessarily, especially in situations where state values are rapidly changing.

But there is no need to worry about the fact that the managed API does not explicitly support batch notifications—where there's a will, there's a way. After spending some time spelunking through the Microsoft.WindowsMobile.Status assembly, I found that with a little help from reflection and platform invoke, it is relatively easy to modify notifications that are created using the SystemState class to be batch notifications.

As we just discussed in the “Batch Notification in Native Code” section, the RegistryBatchNotification function needs the notification handle of an existing notification. Because the managed State and Notifications Broker API ultimately uses the native API, the SystemState class must store the handle that is returned by the SystemState class' call to the RegistryNotifyWindow function. Using reflection, you can access the stored notification handle but accessing the handle is a bit indirect.

The SystemState class is primarily a simplified wrapper over another class, called RegistryState, that is also in the Microsoft.WindowsMobile.Status namespace. We'll talk about the RegistryState class in the Part 3 of this paper. For now, though, all we need to understand is that the SystemState class contains an instance of the RegistryState class, and that the RegistryState class actually does the work of calling the native State and Notifications Broker API.

Using tools like the MSIL Disassembler (Ildasm.exe) or the .NET Reflector, we can look in the Microsoft.WindowsMobile.Status assembly and see that the SystemState class stores the RegistryState instance in a private field that is named registryState. We can then look at the RegistryState class and see that the RegistryState class stores, in a private field that is named notifyHandle, the notification handle that is returned by the native RegistryNotifyWindow function. We can now write a simple function that uses reflection to retrieve the notification handle for a SystemState instance. This function is shown in the following code example.

IntPtr GetSystemStateHandle(SystemState notification)
{
  // Get type information for SystemState and for RegistryState
  Type ssType = typeof(SystemState);
  Type regStateType = typeof(RegistryState);

  // Get field information for SystemState.registryState
  FieldInfo registryStateField =
    ssType.GetField("registryState",
    BindingFlags.Instance | BindingFlags.NonPublic);

  // Get field information for RegistryState.notifyHandle
  FieldInfo handleField = regStateType.GetField("notifyHandle",
    BindingFlags.Instance | BindingFlags.NonPublic);

  // Get the RegistryState instance from the SystemState instance
  object regStateInstance = registryStateField.GetValue(notification);
  // Get the notification handle from the RegistryState instance
  object handleInstance = handleField.GetValue(regStateInstance);

  // Return the notification handle
  return (IntPtr)handleInstance;

}

Using basic reflection features, the GetSystemStateHandle function that is shown in the above code example first gets the Type information for both the SystemState class and for the RegistryState class. The function then retrieves the RegistryState instance, which is named registryState, from the SystemState instance. Next, the GetSystemStateHandle function retrieves the notification handle, which is named notifyHandle, from the RegistryState instance.

The following example code demonstrates how to use the GetSystemStateHandle function and the native RegistryBatchNotification function to create a new function that makes the notification that is associated with the SystemState instance a batch notification.

[DllImport("ossvcs.dll", EntryPoint = "#343" SetLastError = true)]
public static extern int RegistryBatchNotification(IntPtr hNotify, 
   int dwIdle, int dwMax);

void SetupBatchNotification(SystemState notification, int idleTimeout, int maxTimeout)
{
  int hResult;
  
  IntPtr handle = GetSystemStateHandle(notification);
  hResult = RegistryBatchNotification(handle, idleTimeout, maxTimeout);
  if (0 != hResult)
  {
    throw new ApplicationException(
      "RegistryBatchNotification Win32 Error = " + 
      Marshal.GetLastWin32Error().ToString());
  }
}

As you can see, making the notification that is associated with a SystemState instance a batch notification is now pretty simple. You simply retrieve the native notification handle by using the GetSystemStateHandle function, and then call the native RegistryBatchNotification function.

You can now easily make any SystemState notification a batch notification, as shown in the following code example.

public partial class Form1 : Form
{
  SystemState _trackTitle;
  const int batchIdleTimeout = 3000;
  const int maxIdleTimeout = 10000;

  public Form1()
  {
    InitializeComponent();
  
    _trackTitle = 
       new SystemState(SystemProperty.MediaPlayerTrackTitle);
    _trackTitle.Changed += new ChangeEventHandler(TrackTitle_Changed);

    SetupBatchNotification(_trackTitle, batchIdleTimeout,
       maxIdleTimeout);
  }

  //...
}

As you can see in this code example, you simply create the SystemState instance as normal, and attach a delegate to the Changed event. Next, you make the SystemState instance a batch notification by calling the SetupBatchNotification function, passing the SystemState instance and the timeout values.

This code works well, but you must exercise caution.

• You must call SetupBatchNotification after you attach a delegate to the Changed event. As mentioned earlier in this article, the notification handle does not exist until you attach a delegate to the Changed event.
  
• Add proper error handling and recovery code to the GetSystemStateHandle function and the SetupBatchNotification function before you use them.
  
• As with all reflection code, the reflection code in the GetSystemStateHandle function which extracts the notification handle from the SystemState instance has a relatively high overhead. Therefore, you should avoid calling the GetSystemStateHandle function multiple times for the same SystemState instance. Instead of retrieving the notification handle multiple times, cache it.
  

Conceptually, the State and Notifications Broker's responsibilities are fairly simple. For both persistent notifications and transient notifications, the State and Notifications Broker keeps a list of programs that have registered interest in a state value; when a state value changes, the State and Notifications Broker notifies the appropriate programs.

In order to reliably meet these responsibilities, the list of persistent notifications is stored in the device's registry, where it won't be destroyed if the device is reset or if the battery exhausts its charge. The registry, like all of the Windows Mobile 5.0 file system, is stored in non-volatile memory on the device, and therefore does not need power to maintain the memory contents.

The State and Notifications Broker stores all of the persistent notifications in the registry under the HKEY_LOCAL_MACHINE\System\Notifications registry key. For each persistent notification, the State and Notifications Broker creates a key that has the same name as the notification appId value. The State and Notifications Broker stores the remaining information for the persistent notification as named values on the newly created key. For each persistent notification, the registry structure is basically a registry representation of the parameters that one passes to the RegistryNotifyApp function.

As an example of a registry key, figure 1 shows the registry entries that are created by the following code example.

                  const TCHAR *pszAppName = 
    _T("\"\\Program Files\\ExampleApp\\ExampleApp.exe\"");
  const TCHAR *pszNotificationName =
    _T("CompanyA.ExampleApp.MediaPlayerTrackTitle");

hResult = RegistryNotifyApp(SN_MEDIAPLAYERTRACKTITLE_ROOT,
  SN_MEDIAPLAYERTRACKTITLE_PATH, SN_MEDIAPLAYERTRACKTITLE_VALUE,
  pszNotificationName, pszAppName, szWindowClass, szTitle,
  WM_TRACKTITLECHANGE, 0, NULL);

Figure 1. Registry entry for a persistent notification

As you can see, the appId value and corresponding values are all stored unchanged in the registry. Table 3 shows the relationship between each registry value and the corresponding parameter.

Table 3. The relationship between notification values in the registry and the parameters passed to the RegistryNotifyApp function

With all of the information related to persistent notifications stored in the registry, the State and Notifications Broker simply reads the list anytime that the device is restarted.

When a state value that is associated with a persistent notification changes, the State and Notifications Broker must determine whether to send a notification message to the application target window, or launch the application and then send the notification message. The decision depends upon whether the program that is associated with the notification is running at the time that the state value changes. To determine if the program is running, the State and Notifications Broker attempts to find a window with the class and the title registered in the call to the RegistryNotifyApp function. If the State and Notifications Broker locates the window, it sends the specified notification message to the window and takes no further action.

If the State and Notifications Broker is not able to find the window with the specified class and title, the State and Notifications Broker assumes that the application is not running, and therefore launches the registered executable. When starting the application, the State and Notifications Broker checks the persistent notification's flag value; and as long as the persistent notification flag's value is not RNAF_NONAMEONCMDLINE, the State and Notifications Broker passes the program the two command-line arguments: /notify and the appId. Once the application starts running, the State and Notifications Broker again attempts to locate the window that has the appropriate class and title. The State and Notifications Broker continues trying once each second until it either finds the window or 10 seconds elapse. If the State and Notifications Broker finds the window before 10 seconds elapse, the State and Notifications Broker sends the notification message to the window; otherwise, the State and Notifications Broker takes no further action to notify the application.

Note:
You should not write your applications to depend on the frequency and duration that the State and Notifications Broker uses to locate the application window. Future updates and/or versions of the Windows Mobile platform may use different time values or may even change the algorithm altogether.

Native programs do not normally need any special handling for a notification that requires the State and Notifications Broker to start the program. In native programs, notification messages are normally handled in the main program window's WndProc function with the same logic used to handle both persistent notifications and transient notifications. The main program window is created very early in the program's execution and is therefore in place to handle the notification message that is sent by the State and Notifications Broker before the State and Notifications Broker’s search for the window times out.

Managed programs, however, do need to provide special handling for persistent notifications. This special handling is necessary because of two issues: managed programs tend to require a longer startup time than native programs and managed programs must create SystemState instances to handle persistent notifications differently then when handling transient notifications.

The longer startup time required by managed applications is because most of the standard program startup behavior is handled by the .NET Compact Framework runtime; therefore, your managed program doesn't have an opportunity to create the SystemState instance for a particular notification, and attach a delegate to the SystemState.Changed event, until very late in the managed program's startup process. To ensure that your managed application receives the notification event, create the SystemState instance, and attach a delegate to the SystemState.Changed event as early in your application's startup process as you can. In most programs this will be either the application's main form constructor or in the Program.Main function.

Note:

On some desktop computers, the Device Emulator exhibits notably slower performance than a real Windows Mobile device. This is especially true if you are running the Device Emulator within a Virtual PC image. If you find that the Device Emulator is taking more than 10 seconds to start your managed application, the application may not have an opportunity to handle the initial persistent notification that is sent by the State and Notifications Broker after launching the program. The only solutions to the Device Emulator's slow performance are either to use a desktop computer that provides better Virtual PC or Device Emulator performance, or to use a real device. Currently Virtual PC does not support USB connections therefore using a real device is only an option if you’re working directly on your desktop computer outside of a virtual environment or you are using a virtual machine product that provides USB support.

Handling a persistent notification in a managed program is very much like handling a transient notification except that you pass the persistent notification’s appId to the SystemState class constructor rather than pass a member of the SystemProperty enumeration. The SystemState instance uses the passed appId to read the persistent notification's information from the registry. After you construct the SystemState instance, you attach a delegate to the SystemState.Changed event just as you do for transient notifications.

Unlike native applications which, when creating a persistent notification, give you a choice of whether to have the State and Notifications Broker send the appId on the command line when starting the application, a persistent notification that is created by a managed application always creates the persistent notification so that the State and Notifications Broker does not send the appId on the command line. Instead, the SystemState class provides the static IsApplicationLauncherEnabled function which tests to see if the persistent notification that is identified by a particular appId is already defined.

Most commonly, a managed program uses the IsApplicationLauncherEnabled function to determine whether the application should create a new persistent notification or just start handling an existing persistent notification. This behavior is demonstrated in the following code example.

SystemState _mediaPlayerTitle;
const string appId = "CompanyA.ExampleApp.MediaPlayerTrackTitle";

public Form1()
{
  InitializeComponent();

  if (SystemState.IsApplicationLauncherEnabled(appId))
  {
    // Handle existing persistent notification
    _mediaPlayerTitle = new SystemState(appId);
  }
  else
  {
    // Create a new persistent notification
    _mediaPlayerTitle = 
        new SystemState(SystemProperty.MediaPlayerTrackTitle);
    _mediaPlayerTitle.EnableApplicationLauncher(appId);
  }

  // Attach delegate
  _mediaPlayerTitle.Changed += 
      new ChangeEventHandler(MediaPlayerTitle_Changed);
}

The program shown in the above code example starts by declaring a string constant named appId to hold the persistent notification's appId value, CompanyA.ExampleApp.MediaPlayerTrackTitle. The program then uses the IsApplicationLauncherEnabled function to check whether the persistent notification with the appId has already been created. If the IsApplicationLauncherEnabled function returns true, the program creates a new SystemState instance passing the appId. In this case, the program creates the SystemState instance to handle the existing persistent notification. If the IsApplicationLauncherEnabled function returns false, the program creates a new SystemState instance passing the SystemProperty enumeration value that indicates that the notification is associated with the Windows Media Player Mobile track title state value. The program then creates a new persistent notification with the appropriate appId by calling the EnableApplicationLauncher function on the SystemState instance just created. In both cases, once the SystemState instance is created the Changed event fires each time the Windows Media Player Mobile track title changes.

So far in this section, we've discussed the basics of persistent notifications and program startup, there are also some other more involved situations that are useful to understand but we'll save those for Part 3 of this paper.