通知

WinCE应用程序可以注册一个通知，该通知可以在一个预设的时间启动，或者在某个系统事件发生时启动。应用程序也可以注册一个用户通知。设定用户通知后，系统将在指定的时间通知用户，而不用单独运行一个应用程序等到那个时间来通知用户。另外一种类型的通知可以显示消息窗口，或者气泡窗口，在里面用纯文本甚至是格式化HTML文本来显示信息。

1.用户通知

设置用户通知 CeSetUserNotificationEx（）

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

HANDLE CeSetUserNotificationEx(
HANDLE hNotification, 
CE_NOTIFICATION_TRIGGER *pcnt, 
CE_USER_NOTIFICATION *pceun 
);

Parameters

hNotification

[in] Handle to the notification to overwrite or 0 to add a new notification.

pcnt

[in] Pointer to a CE_NOTIFICATION_TRIGGER structure that defines what event activates a notification.

pceun

[in] Pointer to the CE_UserNotificationType structure that defines how the system should respond when a notification occurs. For example, the system could launch a dialog box or another application.

Return Values

Returns a handle to the notification event if successful. Returns NULL if unsuccessful.

///

This structure defines what event activates a notification.

typedef struct UserNotificationTrigger {
DWORD dwSize;
DWORD dwType;//对于用户通知，这个为CNT_TIME，CNT_PERIOD
DWORD dwEvent;
WCHAR *lpszApplication;
WCHAR *lpszArguments;
SYSTEMTIME stStartTime;
SYSTEMTIME stEndTime;
} CE_NOTIFICATION_TRIGGER, *PCE_NOTIFICATION_TRIGGER;

Members

dwSize

DWORD that specifies the size of this structure in bytes.

dwType

DWORD that specifies the type of notification. The following table shows the possible values.

Value
Description

CNT_EVENT
System event notification.

CNT_TIME       //该类性通知在用户不操作的情况下自动解除
Time-based notification.

CNT_PERIOD //该通知在等待一段时间后自动解除

Time-based notification that is active for the time period between stStartTime and stEndTime.

CNT_CLASSICTIME
Equivalent to using the CeSetUserNotification function. The standard command line is supplied.

 

dwEvent

DWORD that specifies the type of event if dwType is CNT_EVENT. The following table shows the possible values.

Value
Description

NOTIFICATION_EVENT_DEVICE_CHANGE
A PC Card device changed.

NOTIFICATION_EVENT_IR_DISCOVERED
The device discovered a server by using infrared communications.

NOTIFICATION_EVENT_NET_CONNECT
The device connected to a network.

NOTIFICATION_EVENT_NET_DISCONNECT
The device disconnected from a network.

NOTIFICATION_EVENT_NONE
No events occurred. Remove all event registrations for this application.

NOTIFICATION_EVENT_OFF_AC_POWER
The user turned the alternating current (AC) power off.

NOTIFICATION_EVENT_ON_AC_POWER
The user turned the AC power on.

NOTIFICATION_EVENT_RESTORE_END
A full device data restore completed.

NOTIFICATION_EVENT_RS232_DETECTED
An RS232 connection was made.

NOTIFICATION_EVENT_SYNC_END
Data synchronization finished.

NOTIFICATION_EVENT_TIME_CHANGE
The system time changed.

NOTIFICATION_EVENT_TZ_CHANGE
The time zone changed.

NOTIFICATION_EVENT_WAKEUP
The device woke up.

 

lpszApplication

Pointer to a null-terminated string that contains the name of the application to execute. You can also use this string to support a named event instead of launching an application. The following code example shows the format that you should use for the string pointed to by lpszApplication when you want to use lpszApplication to support a named event instead of launching an application.

".//Notifications//NamedEvents//Event Name"

Event Name represents the application-defined name of the event to signal. When you use this format for lpszApplication, the event is opened and signaled. Named events are supported in Microsoft® Windows® CE .NET.

 

lpszArguments

Pointer to a null-terminated string that contains the arguments for the command line used to execute the application. This string does not include the application name.

stStartTime

SYSTEMTIME structure that specifies the beginning of the notification period.

stEndTime  //只有在CNT_PERIOD类型用户通知的情况下，停止时间才有效

SYSTEMTIME structure that specifies the end of the notification period.

Remarks

The new event based trigger enables an application to create a named event by calling the CreateEvent function and then requesting that the notification subsystem set the named event when the notification event occurs. The application can use either a manual or reset event depending on the desired behavior. By default, the notification subsystem only calls the SetEvent function to trigger the event.

//

This structure contains information used to initialize the user notifications settings dialog box, and receives the user's notification preferences entered by way of the dialog box. Also used when setting a user notification.

typedef struct UserNotificationType {
DWORD ActionFlags;
TCHAR *pwszDialogTitle;
TCHAR *pwszDialogText;
TCHAR *pwszSound;
DWORD nMaxSound;
DWORD dwReserved;
} CE_USER_NOTIFICATION, *PCE_USER_NOTIFICATION;

Members

ActionFlags

DWORD that specifies the action to take when a notification event occurs. The following table shows the possible values.

Value
Description

PUN_LED
Flashes the LED.

PUN_VIBRATE
Vibrates the device.

PUN_DIALOG
Displays the user notification dialog box. When this structure is passed to the CeSetUserNotification function, the pwszDialogTitle and pwszDialogText members must provide the title and text of the dialog box.

PUN_SOUND
Plays the sound specified by the pwszSound member. When passed to PSVN, the pwszSound member must provide the name of the sound file.

PUN_REPEAT
Repeats the pwszSound for 10–15 seconds. Only valid if PUN_SOUND is set.

Any flag that is not valid on the current hardware platform is ignored.

 

pwszDialogTitle

Pointer to the string that contains the title of the user notification dialog box. If this member is NULL, no dialog is displayed. The CeGetUserNotificationPreferences function ignores this member.

pwszDialogText

Pointer to the string that contains the text of the user notification dialog box. If this member is NULL, no dialog is displayed. The CeGetUserNotificationPreferences function ignores this member.

pwszSound

Pointer to a buffer that contains the unqualified name of a sound file to play. This member is ignored if the ActionFlags member does not include the PUN_SOUND flag.

nMaxSound

DWORD that specifies the maximum length of the string that the CeGetUserNotificationPreferences function can copy into the pwszSound buffer. Because the string may be a path name in a future release, the buffer must be at least the length derived by the following expression: PATH_MAX * sizeof(TCHAR). This member is ignored by the CeSetUserNotification function.

dwReserved

Reserved; set to zero.

Remarks

The CE_USER_NOTIFICATION structure is passed in the CeGetUserNotificationPreferences function. Initial settings are used to populate the dialog box. If the function returns TRUE, the returned settings should be saved, and considered when calling CeSetUserNotification. Settings for hardware not on the current device will be ignored.

It is also used when calling CeSetUserNotification, to describe what should happen when the notification time is reached.

///

1配置用户通知

为了提供一个统一的用户接口来选择通知方法，WinCE提供了一个对话框来查询用户希望如何被通知。要显示用户配置对话框，调用CeGetUserNotificationPreferences（）；

This function queries the user for notification settings by displaying a dialog box showing options that are valid for the current hardware platform.

BOOL CeGetUserNotificationPreferences(
HWND hWndParent, 
PCE_USER_NOTIFICATION lpNotification 
); 

Parameters

hWndParent

[in] Handle to the parent window for the notification settings dialog box.

lpNotification

[in/out] Long pointer to a CE_USER_NOTIFICATION structure. When calling CeGetUserNotificationPreferences, this structure contains data used to initialize the notification settings dialog box. When the function returns, this structure contains the user's notification settings.

Return Values

TRUE indicates success. FALSE indicates failure or that the user did not change the settings.

2）响应用户通知

用户通知可以被应用程序在他超时之前解除，调用CeClearUserNotification（）；

WinCE系统上，用户可以点击Open按钮来加载一个通知中指定的应用程序。如果用户点击Open按钮，通知不回被自动响应。相反的，应用程序应该通过调用程序调用下面的函数来响应这个通知：

This function marks as handled all notifications previously registered by the given application that have occurred. CeHandleAppNotifications turns off the sound and LED and stops vibration (if they were on), and removes the taskbar annunciator.

BOOL CeHandleAppNotifications(
TCHAR *pwszAppName 
); 

Parameters

pwszAppName

[in] Pointer to a null-terminated string that specifies the name of the application whose events are to be marked as handled. This must be the name that was passed in to CeSetUserNotification as the owner of the notification.

Return Values

TRUE indicates success. FALSE indicates failure.

 

//

2.计时器事件通知  dwType = CNT_TIME

在不需要用户干预的情况下，定时运行一个应用程序，应使用定时器事件通知。设定一个计时器事件通知，使用和设置用户通知一样的CeSetUserNotificationEx（）函数，在pceun参数传入NULL。

3.系统事件通知  dwType = CNT_EVENT

一个应用程序自动启动。这种通知在一系列系统事件之一发生时启动一个应用程序。

This function starts running an application when a specified event occurs.

BOOL CeRunAppAtEvent(
TCHAR *pwszAppName, 
LONG lWhichEvent 
); 

已被CeSetUserNotificationEx取代。

但有一个特定的用途--为特定应用程序清除所有的系统通知。在参数lWhichEvent =NOTIFICATION_EVENT_NONE，和应用程序名一起传递，WinCE将清除分配给该应用程序的所有事件通知。这是你会想使用CeSetUserNotificationEx函数传入同样的标记，也能够清除事件，但使用这个函数必须传入原始的句柄，该句柄在你设定通知时返回。

4.查询已设定的通知

CeGetUserNotificationHandles（）；

CeGetUserNotification（）确定每个通知的详细情况。

5.气泡通知

1）添加气泡通知

This function adds a notification to the notification tray.

LRESULT SHNotificationAdd(
  SHNOTIFICATIONDATA* pndAdd
);

Parameters

pndAdd

[in] Pointer to an SHNOTIFICATIONDATA structure describing the notification to be added.

Return Values

This function returns ERROR_SUCCESS when successful.

2）修改气泡通知

This function gets the data for a notification. It is available for querying back the data to another application.

//得到气泡通知配置数据

LRESULT SHNotificationGetData(
  const CLSID* pclsid,
  DWORD dwID, 
  SHNOTIFICATIONDATA* pndBuffer
);

Parameters

pclsid

[in] Pointer to the class ID of the notification.

dwID

[in] Specifies the unique identifier for the notification.

pndBuffer

[out] Pointer to an SHNOTIFICATIONDATA buffer to receive the notification data.

Return Values

This function returns ERROR_SUCCESS when successful.

Remarks

Upon successful return from this function, pndBuffer->pszHTML and pndBuffer->pszTitle are owned by and must be freed by the caller.

///

修改气泡通知的配置参数

This function updates aspects of a pending notification.

LRESULT SHNotificationUpdate(
  DWORD grnumUpdateMask,
  SHNOTIFICATIONDATA* pndNew
); 

Parameters

grnumUpdateMask

[in] Bitfield that specifies which members of pndNew are active.

pndNew

[in] Pointer to an SHNOTIFICATIONDATA structure containing the new data to place into the notification.

Return Values

This function returns ERROR_SUCCESS when successful.

Remarks

The grnumUpdateMask parameter contains of one or more SHNUM_XXXX flags. When calling SHNotificationUpdate, the caller sets the bits in grnumUpdateMask and fills the corresponding members in pndNew.

The other members are ignored.

 

/

删除气泡通知

This function removes a notification. This is usually in response to some action taken on the data that is outside of the notification system.

LRESULT SHNotificationRemove(
  const CLSID* pclsid, 
  DWORD dwID
);

Parameters

pclsid

[in] Class identifier of the notification to remove.

dwID

[in] Specifies the unique identifier of the notification to remove. Do not set the value of this parameter to 0; that option is not implemented. If the value of this parameter is set to 0, the function will return an error.

Return Values

This function returns ERROR_SUCCESS when successful.

Remarks

Notifications are typically removed when the user taps on a link in the notification bubble. This function only needs to be called when the notification needs to be removed because of external changes in state.

Requirements