Share via


SHNotificationUpdate

Send Feedback

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

See Also

SHNotificationRemove | SHNotificationAdd | SHNotificationGetData | SHNOTIFICATIONDATA

Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.