SHNotificationUpdate

Article
11/18/2015

A version of this page is also available for

4/8/2010

This function updates aspects of a pending notification.

Syntax

LRESULT SHNotificationUpdate(
  DWORD grnumUpdateMask,
  SHNOTIFICATIONDATA* pndNew
);

Parameters

grnumUpdateMask
[in] Bitfield that consists of one or more flags which specify which members of pndNew are updated. The following table shows the possible flag values.

Flag	Description
SHNUM_PRIORITY	The npPriority member has been updated.
SHNUM_DURATION	The csDuration member has been updated.
SHNUM_ICON	The hicon member has been updated.
SHNUM_HTML	The pszHTML member has been updated.
SHNUM_TITLE	The pszTitle member has been updated.
SHNUM_SOFTKEYS	The skm or rgskn member has been updated.
SHNUM_TODAYKEY	The pszTodaySK member has been updated.
SHNUM_TODAYEXEC	The pszTodayExec member has been updated.
SHNUM_SOFTKEYCMDS	The skm or rgskn member and grfFlags member have been updated.
SHNUM_FLAGS	The grfFlags member has been updated.

pndNew
[in] Pointer to an SHNOTIFICATIONDATA structure containing the new data to place into the notification. At a minimum, the dwId and clsid members of this structure must be specified for the correct notification in order for that notification to be updated.

Return Value

This function returns ERROR_SUCCESS when successful.

For Windows Mobile the following list shows the return values on failure, for a Windows Mobile Professional and Windows Mobile Classic.

ERROR_INVALID_PARAMETER
ERROR_OUTOFMEMORY
ERROR_DLL_INIT_FAILED
ERROR_NO_MATCH

For Windows Mobile the following is the return value on failure, for Windows Mobile Standard.

ERROR_INVALID_PARAMETER

For a description of these error values, see System Errors - Alphabetical Order.

Code Example

The following code example demonstrates how to use SHNotificationUpdate.

Note

To make the following code example easier to read, security checking and error handling are not included. This code example should not be used in a release configuration unless it has been modified to include them.

static const GUID CLSID_SHNAPI_Test = { 0x33765136, 0x8cb9, 0x449a, { 0xb0, 0x20, 0x43, 0xed, 0x40, 0xa, 0xb8, 0xfc } };
void SHNotificationExample()
{
    // This code will add an SHNotification notification
    SHNOTIFICATIONDATA sn  = {0};
    SHNOTIFICATIONDATA sn2 = {0};
    sn.cbStruct = sizeof(sn);
    sn.dwID = 1;
    sn.npPriority = SHNP_INFORM;
    sn.csDuration = 15;
    sn.hicon = LoadIcon(g_hInstance, MAKEINTRESOURCE(IDI_SAMPLEICON));
    sn.clsid = CLSID_SHNAPI_Test;
    sn.grfFlags = 0;
    sn.pszTitle = TEXT("Sample Notification");
    sn.pszHTML = TEXT("<html><body>This is <b>sample html</b> in a notification!</body></html>");
    sn.rgskn[0].pszTitle = TEXT("Dismiss");
    sn.rgskn[0].skc.wpCmd = 100;
    //Add the notification to the tray
    SHNotificationAdd(&sn);
    //Put the data from an existing notification into a second SHNOTIFICATIONDATA struct
    sn2.cbStruct = sizeof(sn2);

    //Update the title, HTML, icon, and softkeys of the notification
    sn2.pszTitle = TEXT("Updated - Sample Notification");
    sn2.pszHTML = TEXT("<html><body>This notification has been <b>updated!</b></body></html>");
    sn2.hicon = LoadIcon(g_hInstance, MAKEINTRESOURCE(IDI_SAMPLEICON2));
    sn2.rgskn[0].pszTitle = TEXT("Disabled");
    sn2.rgskn[0].skc.wpCmd = 100;
    sn2.rgskn[0].skc.grfFlags = NOTIF_SOFTKEY_FLAGS_DISABLED;

    //Remove the notification from the tray
    SHNotificationRemove(&CLSID_SHNAPI_Test, 1);
    //Add a new notification that utilizes the MRE functionality
    sn.cbStruct = sizeof(sn);
    sn.dwID = 1;
    sn.npPriority = SHNP_INFORM;
    sn.csDuration = 15;
    sn.hicon = LoadIcon(g_hInstance, MAKEINTRESOURCE(IDI_SAMPLEICON));
    sn.clsid = CLSID_SHNAPI_Test;
    sn.grfFlags = SHNF_STRAIGHTTOTRAY;
    sn.pszTodaySK = TEXT("New Task");
    sn.pszTodayExec = TEXT("\\windows\\tasks.exe");
    //Add the notification to the tray
    SHNotificationAdd(&sn);
    //Remove the notification from the tray
    SHNotificationRemove(&CLSID_SHNAPI_Test, 1);
}

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.

When calling SHNotificationUpdate, set the bits in grnumUpdateMask and fill the corresponding members in pndNew. The other members are ignored.

If SHNUM_SOFTKEYS is set, it means softkeys are being updated due to a new HMENU in the SOFTKEYMENU structure pointed to by skm (and SHNF_HASMENU is set in grfFlags in SHNOTIFICATIONDATA structure), or new titles in the SOFTKEYNOTIFY structure pointed to by rgskn.

Note

Beginning with Windows Mobile 6.5.3, soft keys are replaced by touchable tiles on Windows Mobile Professional phones.

If SHNUM_SOFTKEYCMDS is set, it means the command identifiers and behavior flags are being updated. If SHNF_HASMENU is set in grfFlags in SHNOTIFICATION structure, the prgskc and csk members of SOFTKEYMENU structure pointed to by skm will contain new data. If SHNF_HASMENU is not set in grfFlags in SHNOTIFICATION structure, the skc members of SOFTKEYNOTIFY structure pointed to by rgskn will contain new data.

The following updates can be enabled using SHNotificationUpdate function.

Update a menu-based soft keys with new menu-based soft keys
Update basic soft keys with menu-based soft keys
Update basic soft keys with new basic soft keys

You cannot update menu based soft keys with basic soft keys.

Requirements

Header	aygshell.h
Library	aygshell.lib
Windows Embedded CE	Windows Embedded CE 6.0 and later
Windows Mobile	Windows Mobile Version 5.0 and later