Windows Mobile 5.0 Productivity APIs

State and Notification Broker

Mobile devices function in a very fluid environment where, being on the move, their environment changes frequently. It thus becomes important for an application to know what state the device is in at any one time. Examples of interesting states include battery power remaining, or GPRS availability. It was previously difficult to determine a device?s current state and respond to state changes effectively and efficiently because each different component of the device kept its own state information and may not even have provided a means to get to the data. With Windows Mobile 5.0, the operating system has centralised its state information into a single store. What is more, an API set is now exposed so that you can access state information in a standard way. The new state store is based on the system registry and state is both recorded and monitored there. The states provided by the operating system are extensive and covers among other things:

• Phone (e.g. Missed Call, Phone Status, Caller ID)
• Network Connections (e.g. WiFi, GPRS, modem)
• Calendar (e.g. Current and Next Appointments)
• Messaging (e.g. Unread Mail Count, SMS)
• Many others (e.g. Display Orientation, Cradled)

Additionally, you can extend the states tracked with custom states. The broker, through the API set, allows states to be changed or monitored for change. When a change is detected, a notification is sent to an application that can then react accordingly. You can have transient notifications, which work when the application requesting it is running. The notification takes the form of a window message, a callback or message in a message queue. The following example uses the RegistryNotifyWindow API to send a window message when phone signal strength changes.

#include <RegExt.h>
#include <SnApi.h>

// Set up the notification
HREGNOTIFY hNotify = NULL;

RegistryNotifyWindow(
	SN_PHONESIGNALSTRENGTH_ROOT,
	SN_PHONESIGNALSTRENGTH_PATH,
	SN_PHONESIGNALSTRENGTH_VALUE,
	hWnd, 
	WM_MY_WINDOW_MESSAGE,
	dwUserDefinedValue,
	NULL,
	&hNotify);

However, the more powerful version is persistent notifications. This type of notification will cause your application to be started by the operating system if it isn?t already running. Use the RegistryNotifyApp API to request this

#include <RegExt.h>
#include <SnApi.h>

NOTIFICATIONCONDITION nc;
					    
nc.ctComparisonType = REG_CT_EQUAL;
nc.TargetValue.dw = 1;  
nc.dwMask = 0xFFFFFFFF;

RegistryNotifyApp(
	SN_CRADLEPRESENT_ROOT,
	SN_CRADLEPRESENT_PATH,
	SN_CRADLEPRESENT_VALUE,
	TEXT(?OSServices.CradlePresent?),
	TEXT(?\?\\Program Files\\OSServices\\OSServices.exe\??),
	NULL,
	NULL,
	0,
	0,
	&nc);