Thursday, July 2, 2009

State and Notifications Broker API

The State and Notification Broker API provide an easy way to get notified while system state changed or registry content changed. This API is available for both Windows Embedded and Windows Mobile operating systems, and works with a provider and client.

The Provider:
The provider create in registry one entry per state managed, and is in charge of the update of those entries when states changed. Usually system states are defined in HKEY_CURRENT_USER\System\State and HKEY_LOCAL_MACHINE\System\State, and user defined (or applicative) states are located in HKEY_CURRENT_USER\Software\State and HKEY_LOCAL_MACHINE\Software\State. The snapi.h header file defines most of the system states notifications for various system functionalities like Phone, Mails, SMS Appointment, Battery, Screen Rotation ... and custom entries should be managed by your own.

The Client:
The client register to a state defined in registry by the Provider, and get notified by the operating system while value changed. Different notifications mechanism can be used :
  • Application activation : can start a client application while registry content changed (or state changed)
  • Message Queue : signal a state notification through a Message Queue
  • Window message : signal a state notification via a Windows Message loop (WindowProc)
  • Callback : signal a state notification using a call back function

The client should register for state notification using one of the following function depending on the type of notification required (RegistryNotifyApp, RegistryNotifyWindow, RegistryNotifyCallback or RegistryNotifyMsgQueue). When state change notification is received the client should read the value using the regular regsitry functions access, or RegistryGetDWORD or RegistryGetString. While notification is no longer required, the client have to call RegistryCloseNotification to close the notification.

No specific action is required by the provider except to update the registry values while internal application transition should generate external state notifications.

You can find a usage sample in the Windows Mobile SDK sample source code of the Battery Statistic :
%ProgramFiles%\Windows Mobile 6 SDK\Samples\PocketPC\CPP\win32\battstat

- Nicolas

3 comments:

Anonymous said...

Dear nicolas,
I'm working on a WinCe6 device and i didn't find the snapi.h , neither in the corresponding SDK nor the WINCE folder.
is it normal ??
Thanks for your answer

kyle_fr

Nicolas BESSON [MVP] said...

The snapi API is only available for Windows Mobile. You can use CeFindFirstRegChange under Windows CE to get registry notifications. But this require more work than the other API.
Nicolas

Anonymous said...

Thanks a lot Nicolas.

à bientôt :-)