User Notification

< BACK  NEXT >

[oR]

You can use the function CeSetUserNotification to notify at a given time using a flashing LED, dialog box, or other technique supported by the Windows CE device. This function will place an icon (the 'annunciator icon') in the tool box at the bottom left of the screen. When this icon is double-clicked by the user, an application specified in CeSetUserNotification will be run. This annunciator icon should be removed by calling CeHandleAppNotifications it cannot be removed by the user.

The code in Listing 7.8 used CeSetUserNotification to notify the user at 7: 15 on the current day by playing the WAV file Alarm2.wav repeatedly. The function returns a handle that can be used to further manipulate the notification. Table 7.3 describes the CeSetUserNotification parameters.

Listing 7.8 Setting user notification

 void Listing7_8() {   HANDLE hNotify;   SYSTEMTIME sysTime;   CE_USER_NOTIFICATION ceNot;   GetLocalTime(&sysTime);   sysTime.wHour = 7;   sysTime.wMinute= 15;   ceNot.ActionFlags = PUN_SOUND | PUN_REPEAT;   ceNot.pwszSound =  _T("\\Windows\\Alarm2.wav");   hNotify = CeSetUserNotification(           NULL,           _T("\\Notify.exe"),           &sysTime,           &ceNot);   if(hNotify == NULL)     cout    _T("Could not set user notification")              endl;   else     cout   _T("User notification set")   endl; } 

The application specified in pwszAppName will be run when the annunciator icon is clicked by the user. The application (Notify.exe in Listing 7.8) will be passed the command line string APP_RUN_TO_HANDLE_NOTIFICATION and the notification handle (converted to a string).

Table 7.3. CeSetUserNotification

CeSetUserNotification
HANDLE hNotification	Handle of the notification to modify, or NULL for a new notification.
TCHAR *pwszAppName	Name of the associated application. This does not have to be the application setting the notification.
SYSTEMTIME *lpTime	SYSTEMTIME structure specifying the time for the notification to occur.
PCE_USER_NOTIFICATION lpUserNotification	CE_USER_NOTIFICATION structure containing information on how to notify the user.
HANDLE Return Value	Returns a HANDLE to the event.

The CE_USER_NOTIFICATION structure specifies how the user will be notified by setting the ActionFlags member with one or more of the following flags shown in Table 7.4.

Table 7.4. CE_USER_NOTIFICATION ActionFlags values

Value	Description
PUN_LED	Flash the LED.
PUN_VIBRATE	Vibrate the device.
PUN_DIALOG	Display a dialog to the user. The CE_USER_NOTIFICATION members pwszDialogTitle and pwszDialogText specify the dialog's caption text and body text.
PUN_SOUND	Plays a WAV file specified in the CE_USER_NOTIFICATION member pwszSound.
PUN_REPEAT	Repeats playing the WAV file for around 10 to 15 seconds.

The application associated with the notification will be run when the user clicks the annunciator icon, and this application should remove the icon. This is done by calling the CeHandleAppNotifications function, passing in the name of the application associated with the notification (Listing 7.9).

Listing 7.9 Removes the annunciator icon

 void Listing7_9() {   if(CeHandleAppNotifications(_T("\\Notify.exe")))     cout   _T("Annunciator cleared")   endl;   else     cout   _T("Annunciator could not be cleared")   endl; } 

The handle returned from CeSetUserNotification can be used to modify or remove the notification as long as the notification time has not passed. A notification can be modified by passing the notification handle as the first argument, and passing in new values for the time or CE_USER_NOTIFICATION structure. A notification can be removed entirely by passing the handle to the CeClearUserNotification function.

   if(CeClearUserNotification (hNotify)))     cout   _T("Notification cleared")   endl;   else     cout   _T("Notification could not be cleared")            endl; 

Users can specify their preference on how they wish to be notified, and these preferences should be honored by your application. The function CeGetUserNotificationPreferences can be used to display a dialog prompting the user for his or her preferred notification options. The dialog will then populate a CE_USER_NOTIFICATION structure with these preferences, and this structure can be passed to CeSetUserNotification to set the notification. Note that the CE_USER_NOTIFICATION structure can be initialized before calling CeGetUserNotificationPreferences to set default values in the dialog box.

Listing 7.10 Getting user preferences for notifications

 void Listing7_10(HWND hWnd) {   CE_USER_NOTIFICATION ceNot;   TCHAR szSound[MAX_PATH + 1];   ceNot.ActionFlags = PUN_SOUND | PUN_REPEAT;   ceNot.pwszSound = szSound;   ceNot.nMaxSound = MAX_PATH;   if(!CeGetUserNotificationPreferences(hWnd, &ceNot))     cout   _T("Could not get settings")   endl;   else   {     if(ceNot.ActionFlags & PUN_SOUND)     {       cout   _T("SOUND:")   endl;       if(ceNot.ActionFlags & PUN_REPEAT)         cout   _T("Repeat")   endl;       else         cout   _T("Don't repeat")   endl;       cout   _T("Sound: ") ceNot.pwszSound               endl;     }     if(ceNot.ActionFlags & PUN_LED)       cout   _T("FLASH")   endl;     if(ceNot.ActionFlags & PUN_VIBRATE)       cout   _T("VIBRATE")   endl;     if(ceNot.ActionFlags & PUN_DIALOG)       cout   _T("DIALOG")   endl;   } } 

< BACK  NEXT >