CeSetUserNotification

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function creates a new user notification or modifies an existing one. Applications developed for Windows CE 2.12 and later should use the CeSetUserNotificationEx function instead.

Syntax

HANDLE CeSetUserNotification(
  HANDLE hNotification, 
  TCHAR* pwszAppName, 
  SYSTEMTIME* lpTime, 
  PCE_USER_NOTIFICATION lpUserNotification 
); 

Parameters

• hNotification
  [in] Handle to the notification to overwrite, or zero to add a new notification.

• pwszAppName
  [in] Pointer to a null-terminated string that specifies the name of the application that owns this notification. The system uses the application's primary icon as the taskbar annunciator for the notification. The user can start the application by selecting the annunciator.

• lpTime
  [in] Long pointer to the SYSTEMTIME structure that specifies the time when the notification should occur.

• lpUserNotification
  [in] Long pointer to the CE_USER_NOTIFICATION structure that describes the events that are to occur when the notification time is reached.

Return Value

The handle to the notification indicates success. This handle can then be used with the other Notify functions. Zero indicates failure.

Remarks

The notification occurs at the specified time, without starting the application. The application can specify the notification options, including whether to light the LED, generate a sound, or display a dialog box. However, an application typically uses the CeGetUserNotificationPreferences function to allow the user to set the notification options.

The user can start the owning application after the notification occurs. In this case, the system starts a new instance of the application using the APP_RUN_TO_HANDLE_NOTIFICATION string as the prefix of the command line and the notification handle (converted to a string) as the postfix. If another instance of the application is already running, the new instance must pass a private message to the old instance and then shut down.

To delete a notification and release the handle, use the handle returned by CeSetUserNotification in a call to CeClearUserNotification. To overwrite a notification, use the returned handle in another call to CeSetUserNotification.

If the specified time falls within the platform-dependent period defined by the accuracy of the real-time clock (RTC), the notification is scheduled immediately. The accuracy can be retrieved using IOCTL_KLIB_GETALARMRESOLUTION and ranges from 1 to 60 seconds. If the system does not implement IOCTL_KLIB_GETALARMRESOLUTION, the default RTC accuracy of 10 seconds is assumed.

Requirements

See Also

Reference

CeHandleAppNotifications
Notify Functions

Other Resources