Download [download id="5"]
Windows Mobile State and Notification Broker is a mechanism which provides storing system and application information in registry and send notifications whenever these values changes. An application registers for a particular event and the State and Notification Broker notifies the client application whenever the event occurs. For example an application wants to get notified when the Windows Media Player start playing a media or when the cellular signal level changes.
The State and Notification Broker mechanism works by monitoring any registry key and whenever the key changes send notification to all the registered clients. The Windows Mobile system provides many notifications. The header file SNAPI.H provides the definitions of the registry keys, its path and bitmask for all the notifications the system provides. The general categories of notifications are:
- System state information
Message information
Tasks and appointment information
Windows Media Player information
Phone information
Connection information
Besides these notifications, an application can create its own notification. In this case the application is a provider which provides state notifications. To do this the application creates a registry key and changes this key whenever the state is changes. The State and Notification Broker will notify all the client applications that registered for this event.
A client application does the following steps to get notified about an event:
- A client Register for the notification using RegistryNotifyApp, RegistryNotifyWindow, RegistryNotifyCallback or RegistryNotifyMsgQueue API.
When the notification arrives, the client application reads the specified registry key to get the necessary information
When the client application no longer needs the notification, close the notification using RegistryCloseNotification.
A provider application does these steps to provide notification of the state change:
- A provider application creates a registry key and stores the state information
When a change occurs, the provider application changes this information
The State and Notification Broker notifies all the clients when the change occurs
The State and Notification Broker supports the following notification types:
Transient: In this, the notifications are only valid when the application is running. The request is closed when the application exits or the device is reset.
Persistent: In persistent type, the notification is remains valid even after the application exits or the device is reset.
There are four modes of notifications in State and Notification Broker, they are;
Application Activation: In this mode, the State and Notification Broker starts the application if it is not running already. This mode applies to the persistent notification type.
Window Message: In this mode, the State and Notification Broker sends the specified window message to the application window. This mode applies to the transient notification type.
Message Queue: In this mode, the Broker sends the message to the specified Message Queue. This mode applies to the transient notification type.
Callback Function: In this mode, the Broker calls the specified callback function when the state change occurs. This mode applies to the transient notification type.
Besides these the State and Notification Broker also support Conditional Notification and Batch Notification. In Conditional Notification, an application can specify to send notification only when the state property is changed to a particular value. This way an application can reduce the number of notification sends to the application. In this the system checks the state property value and send the notification only if the property value matches the specified value.
In Batch Notification, an application can tell the system how frequently the notification has to send. Here you can specify maximum idle time before sending the notification. Whenever the change occurs, the system waits the specified idle time before sending the notification. If the value changes during this time, the system resets the idle time and waits another idle time. But this may leads to infinite wait, to prevent this you can specify maximum wait time. The system either waits for the maximum wait time or waits for the value to get settled.
As I stated before there are many notifications provides by the system by default. For a detailed explanation either refer to the SNAPI.H header file or follow this link: http://msdn.microsoft.com/en-us/library/aa455750.aspx
In Native Mode, the header file REGEXT.H contains the function to register and close the notifications. In Managed Mode, it is exposed via the Microsoft.WindowsMobile.Status namespace (Microsoft.WindowsMobile.Status.dll assembly).
In Native Mode, an application uses any of the following function to register for the notification.
HRESULT WINAPI RegistryNotifyApp(HKEY hKey, LPCTSTR pszSubKey, LPCTSTR pszValueName, LPCTSTR pszName, LPCTSTR pszApp, LPCTSTR pszClass, LPCTSTR pszWindow, UINT msg, DWORD dwFlags, NOTIFICATIONCONDITION* pCondition); HRESULT WINAPI RegistryNotifyWindow( HKEY hKey, LPCTSTR pszSubKey, LPCTSTR pszValueName, HWND hWnd, UINT msg, DWORD dwUserData, NOTIFICATIONCONDITION* pCondition, HREGNOTIFY* phNotify); HRESULT WINAPI RegistryNotifyWindow(HKEY hKey,LPCTSTR pszSubKey, LPCTSTR pszValueName, HWND hWnd, UINT msg, DWORD dwUserData, NOTIFICATIONCONDITION* pCondition, HREGNOTIFY* phNotify); HRESULT WINAPI RegistryNotifyMsgQueue(HKEY hKey, LPCTSTR pszSubKey, LPCTSTR pszValueName, LPCTSTR pszMsgQueue, DWORD dwUserData, NOTIFICATIONCONDITION* pCondition, HREGNOTIFY* phNotify);
The RegistryNotifyApp API is used to register for persistent notification mode. The parameters are:
| hKey | Handle to the opened key or the root key |
| pszSubKey | Name of the sub key, this can be null |
| pszValueName | Name of the value in which state is stored |
| pszName | A unique user defined string that represents the notification. Note that it should be unique, you can try something like ApplicationName. |
| pszApp | Complete path of the executable to be start when the event occurs |
| pszClass | Class name of the window that receives the notification message,this can be NULL |
| pszWindow | Name of the window that receives the notification message, this can be NULL |
| msg | Message to be send to the window. If both pszClass and pszWindow are null, the system will just start the application and will not send the message. |
| dwFlags | Notification flags, this should be 0 or RNAF_NONAMEONCMDLINE. If 0 then system will send the pszName as a command line |
| pCondition | A pointer to the NOTIFICATIONCONDITION structure. Using this structure you can specify the conditions to be checked before sending the notification. See Conditional Notification |
The first three parameters are common for all the APIs. The other parameters change according the API.
When the notification receives, client the application can use RegistryGetString or RegistryGetDWORD to read values from the key. Whenever the application finished using the notification, application should close the notification by using the API RegistryCloseNotification or RegistryStopNotification.
To create a notification provider, an application has to create a registry key and change the value of the registry key whenever the state is changed. The system will notify all the client applications about the change.
There are two samples provided, one is uses transient mode and other uses persistent mode. These are very simple ones to get started with the State and Notification Broker mechanism. Hope this will help you to get started.
