SHNotificationUpdate

Article
08/28/2006

This function updates a notification icon.

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 that contains the new data for the icon.

Return Values

This function returns ERROR_SUCCESS when successful.

The following list shows the return values on failure, for a Windows Mobile-based Pocket PC.

ERROR_INVALID_PARAMETER
ERROR_OUTOFMEMORY
ERROR_DLL_INIT_FAILED
ERROR_NO_MATCH

The following list shows the return values on failure, for a Windows Mobile-based Smartphone.

ERROR_INVALID_PARAMETER

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

Remarks

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.

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.

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 notificaion (PocketPC only)
    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);
    SHNotificationGetData(&CLSID_SHNAPI_Test, 1, &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;
    SHNotificationUpdate(SHNUM_TITLE | SHNUM_HTML | SHNUM_ICON | SHNUM_SOFTKEYCMDS | SHNUM_SOFTKEYS, &sn2);

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

Requirements

OS Versions: Windows CE 5.01 and later
Header: aygshell.h
Link Library: aygshell.lib