CeSetUserNotification

The CeSetUserNotification function creates a new user notification or modifies an existing one.

Syntax

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

At a Glance

Header file:	Notify.h
Platforms:	H/PC
Versions:	1.01 and later

Parameters

hNotification: Handle to the notification to overwrite, or zero to add a new notification.
pwszAppName: 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: Pointer to the SYSTEMTIME structure that specfies the time when the notification should occur.
lpUserNotification: Pointer to the CE_USER_NOTIFICATION structure that describes the events that are to occur when the notification time is reached.

Return Values

If the function succeeds, the return value is the handle to the notification. An application can use the handle to overwrite or delete the notification. The return value is zero if the notification could not be set.

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.