User Notification

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).

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.

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;
  }
}