For many Windows Mobile applications, monitoring the various aspects of the state of a Pocket PC or a Smartphone client can be quite daunting. Often, only the heartiest .NET Compact Framework developers with extensive knowledge of the Windows Mobile APIs and P/Invoke coding are up to the challenge of this type of development. Recognizing these issues, Microsoft has responded with a new managed State and Notification Broker API for Windows Mobile 5.0. This new API provides C# or VB.NET developers with a number of benefits in a limited amount of application code.
Anatomy of the State and Notification Broker API
The State and Notification Broker API provides the Windows Mobile 5.0 environment with a new, built-in notification broker structure. Programmers using the .NET Compact Framework Version 2.0 can use this brokering mechanism, but the API is not available for earlier-OS development. It is exposed to .NET Compact Framework development via the Microsoft.WindowsMobile.Status namespace (and associated Microsoft.WindowsMobile.Status.dll assembly). Because the actual assembly is specific to the Windows Mobile 5.0 platform, it is included in the OS installation itself rather than in the deployment CABs for the .NET CF 2.0.
Several major components make up the new State and Notification Broker API. The SystemState class enables access to a specific system state. The SystemProperty enumerator contains the list of available system states to monitor. Finally, a special event handler (incorporated in the Microsoft.WindowsMobile.Status.ChangeEventHandler delegate) is used to monitor system states.
Although this all might seem like quite a bit of information to digest, implementing the code to monitor and respond to a change in a system state is a relatively straightforward process.
Steps to Implement the State and Notification Broker API
To implement the State and Notification Broker API, you must perform several high-level steps:
- Add the necessary references to your .NET Compact Framework project.
- Identify the correct system state to monitor.
- Add an instance of the system state into the project.
- Add an event handler for the system state into the project.
- Write code to respond to the change in system state.
1. Adding References to Your .NET Compact Framework Project
You will need to add two assemblies to your project to use the State and Notification Broker API: Microsoft.WindowsMobile and Microsoft.WindowsMobile.Status (see Figure 1).
Figure 1: WindowsMobile and WindowsMobile.Status Assemblies
While you need to reference the WindowsMobile namespace, you never access it directly through your code. This namespace does, however, contain an interface implemented by the SystemState class.
You should also reference the Status namespace with the using directive:
using Microsoft.WindowsMobile.Status;
2. Identifying the State to Monitor
The State and Notification Broker API provides access to over 100 pieces of state information, so determining the right state to monitor for change requires a bit of research. Using the Object Browser is the best quick way to do this. Specifically, you should look at the SystemProperty enumerator for a complete list. As Figure 2 shows, highlighting a SystemProperty gives you a summary of the property’s purpose.
Figure 2: The Object Browser and System Properties
3. Adding an Instance of the System State to Your Code
Next, you will need to add an instance of the system state to monitor into your application logic. To do this, you need to add some code immediately after your default constructor logic. The following example of the necessary code implements the PhoneRoaming system state, which stores whether or not a Pocket PC Phone Edition or Smartphone device is in Roaming Mode:
InitializeComponent();
SystemState _PhoneRoaming = new SystemState(
SystemProperty.PhoneRoaming);
4. Adding an Event Handler to Your Code
The next step is to add the necessary event handler to your application logic. You can add the event handler immediately after the instance declaration. For example, typing in the instance variable and Change method with the “+=” symbol will cause the Visual Studio 2005 IDE to behave the same way it does for normal event handlers:
_PhoneRoaming.Change += new ChangeEventHandler(
_PhoneRoaming_Changed);
You will be prompted to press the TAB key to complete the statement, and then to press TAB again to generate an associated method for the event:
void _PhoneRoaming_Changed(object sender, ChangeEventArgs args)
{
throw new Exception(“The method or operation is not implemented.”);
}
5. Writing Code to Respond to the State Change
Which code you choose to develop will depend on the system state you are monitoring and the needs of the application. However, at the least some of this code will need to be contained within the event method. The example from the previous step monitors the PhoneRoaming state of the device. You might want to use this state in situations where you rely on a cellular data network (GPRS, 1xRTT, EVDO, EDGE, and so forth) for remote connectivity and want to use the data network only when you are not roaming to avoid additional phone service charges. In this case, you might implement logic like the following:
void _PhoneRoaming_Changed(object sender, ChangeEventArgs args)
{
if (SystemProperty.PhoneRoaming == false)
{
// Perform data network access
}
}
Possible Uses for the State and Notification Broker API
The example in this article is only one of a large number of possibilities. The options are limited only by the system states that you can access and the limits of your imagination. Some of the major categories of the system states include:
- Phone network status: Information regarding availability and signal strength.
- Phone call information: A number of system properties relating to incoming, outgoing, and current calls. (You can use these states to provide information to a user from within the application—displaying contact information for a caller beyond Caller ID, for example.)
- Network information: System properties pertaining to WiFi network information. (You could use these in a fashion similar to cellular data networks.)
- Messaging: A number of system properties around messaging from other e-mail and SMS. (You could use these events for any of a number of possibilities, including displaying notifications and information regarding new messages from within your application.)
- Power: System properties related to power status, including the remaining power of the main or backup battery and current state (charging, low, critical, and so on). (This can be very useful for providing information and taking application-specific actions separate from the standard device behaviors. You could, for example, set your own threshold for network-intensive applications, which can drain battery life, to perform these actions only when the battery has a minimum amount of life remaining.)
- PIM events: System properties relating to Calendar, Contacts, and Tasks that can be monitored and integrated into your application. (You could, for example, take certain actions if the number of High Priority tasks is above a certain number.)
About the Author
Don Sorcinelli has been involved in the design, development, and deployment of enterprise software applications for over 15 years. Don also has worked with mobile and distributed architectures for almost a decade, and has worked with the PDA and Windows Mobile platform since their inceptions. Don is a frequent presenter on Windows Mobile development and technologies for MSDN, developer groups, and conferences. He is also the Manager of the Boston Windows Mobile Developer Group and founder of BostonPocketPC.com, a Web site focused on Microsoft mobile technologies.
