You use the CeSetUserNotification function to register a user notification. It specifies the time when the notification should occur, the name of the associated application, and the way the notification appears to the user, such as a flashing LED or a sound.
At the specified time, the system places the application icon into the taskbar. If the specified time has already passed, the system places the icon in the taskbar immediately. An icon placed into the taskbar is called a taskbar annunciator. The taskbar can contain multiple annunciator icons at the same time, if they are for different applications. But only one icon for a specified application will be displayed at any time.
When the user taps the annunciator icon, the system starts a new instance of the corresponding application. It also passes a command-line parameter that tells the application why it is being started. If an instance of the application is already running, the new instance must send an application-defined message to the previous instance. The new instance then shuts down.
User notifications exist in either a registered state or an active state. The notification is registered from the time you call CeSetUserNotification until the time the user is notified. The notification is active from the time the user is notified until the event is handled.
Depending on what user notifications an H/PC supports, the operating system notifies the user of an event in one of the following ways:
The user can choose a specific sound for each notification. The user can override sound notifications using the Volume/Sounds setup from the Control Panel.
When a notification causes the LED to flash, the flashing continues until the user handles the notification. If multiple notifications cause the LED to flash, the flashing stops only when the user has handled all notifications.
A notification dialog box contains an application-defined title, application-defined text, an OK button, and a Snooze button. Clicking the OK button handles the notification. If the user clicks the Snooze button, the dialog box disappears and is redisplayed after five minutes. Clicking the Snooze button does not handle the notification.
The actions that the system performs for a particular notification should be based on preferences selected by the user. The system obtains a user's preferences by calling CeGetUserNotificationPreferences. This function displays a dialog box that contains the options available on the Windows CE-based device. The OEM determines available options. The system places the user's choices into a CE_USER_NOTIFICATION structure. The structure's address is specified in the call to CeSetUserNotification, which makes the user's preferences available to the system. CeSetUserNotification is used both for creating a new user notification and for modifying an existing notification.
User notifications are handled in two ways. For notifications that display a dialog box, clicking the OK button handles the notification. For notifications that do not display a dialog box, the application started by the user handles the notification by calling CeHandleAppNotifications. This function marks all active notifications for the application as "handled" and also removes the taskbar annunciator icon. CeHandleAppNotifications handles only active notifications, not registered notifications.
To delete registered user notifications, use CeClearUserNotification. For example, if a user sets a calendar appointment and then deletes the appointment before the specified time, this function removes the notification.
The taskbar annunciator for an active notification remains in the taskbar until the user handles the notification. In cases where an application has multiple active notifications, all of its active notifications must be handled before the annunciator icon is removed.