Applications: Displaying a notification using SHNOTIFICATIONDATA

Sometimes you may want to display a notification to the user to inform her of an event or a pending task. You might say a message box will serve your purpose mostly, but there will be times when a message box is not the appropriate choice. For example when I was developing a call block application with a colleague of mine, we had to display the blocked call notification to the user, and the bubble notification was the most appropriate one. The notification shows an icon on the system tray and displays a message to the user. Lets see how we can do that.

To display a notification we use the SHNotificationAdd() function. This API takes a pointer to SHNOTIFICATIONDATA structure and this contains all the details about the notification that you want to show. The structure is defined as below,

typedef struct _SHNOTIFICATIONDATA{

DWORD cbStruct;

DWORD dwID;

SHNP npPriority;

DWORD csDuration;

HICON hicon;

DWORD grfFlags;

CLSID clsid;

HWND hwndSink;

LPCTSTR pszHTML;

LPCTSTR pszTitle;

LPARAM lParam;

union

{

SOFTKEYMENU skm;

SOFTKEYNOTIFY rgskn[NOTIF_NUM_SOFTKEYS];

}

LPCTSTR pszTodaySK;

LPCTSTR pszTodayExec;

} SHNOTIFICATIONDATA;

cbStruct: size of the structure in bytes

dwID: identifier of this notification, you can give any unique number here

npPriority: priority of the notification. This can take two values, SHNP_INFORM or SHNP_ICONIC

csDuration: duration in seconds, contains the number of seconds that the notification should be displayed for

hicon: handle to the icon which will be displayed on the tray

grfFlags: this contains some flags for the notification, this can take values like, SHNF_CRITICAL (displays the notification with a red border), SHNF_DISPLAYON (the device display is forced to turn on), SHNF_HASMENU (the notification is created with a softkey bar), SHNF_SILENT (does not vibrate or play a sound on the device) etc

clsid: defines a CLSID (a GUID) for the notification, you can create a GUID by using the GuidGen.exe tool which ships with Visual Studio

hwndSink: handle to the window which will receive messages from the notification (for e.g. if the user selects a menu item)

pszHTML: HTML content of the notification

pszTitle: contains the title of the notification

lParam: user defined param

skm: SOFTKEYMENU structure that defines menu for the softkey bar, the SHNF_HASMENU flag in grfFlags member must be set

rgskn: used if the notification is to have two softkeys

pszTodaySK: this contains the string that is displayed on the left softkey when csDuration seconds have elapsed, by default the text used is "Notification"

pszTodayExec: defines the name of the executable file which will run when the user presses the left softkey

The below program displays a notification for 5 seconds,

// {1F1C029E-95B2-4b5d-A2C5-AEF74BFCA979}

static const GUID CLSID_SHOW_NOTI =

{ 0x1f1c029e, 0x95b2, 0x4b5d, { 0xa2, 0xc5, 0xae, 0xf7, 0x4b, 0xfc, 0xa9, 0x79 } };

static HINSTANCE g_hInst = NULL;

int WinMain(HINSTANCE hInst, HINSTANCE hPrevInst, LPWSTR lpCmdLine, int nShowCmd)

{

   SHNOTIFICATIONDATA shNotiData = {0};

   g_hInst = hInst;

   shNotiData.cbStruct = sizeof(shNotiData);

   shNotiData.dwID = 1;

   shNotiData.npPriority = SHNP_INFORM;

   shNotiData.csDuration = 5; //time in seconds

   shNotiData.hicon = LoadIcon(g_hInst, MAKEINTRESOURCE(IDI_ICON1));

   shNotiData.clsid = CLSID_SHOW_NOTI;

   //shNotiData.clsid = CLSID_SHNAPI_OemNotif1;

   shNotiData.grfFlags = SHNF_TITLETIME | SHNF_CRITICAL;//0;

   shNotiData.pszTitle = TEXT("My Notification");

   shNotiData.pszHTML = TEXT("<html><body>This program shows how to display a notification.</body></html>");

   shNotiData.rgskn[0].pszTitle = TEXT("Dismiss");

   shNotiData.rgskn[0].skc.wpCmd = 1001;

   shNotiData.pszTodaySK = TEXT("Alert!");

   Sleep(500);

   SHNotificationAdd(&shNotiData);

   return 0;

}

To remove a notification use SHNotificationRemove() api. And SHNotificationUpdate() and SHNotificationGetData(), update and get the information about a notification, respectively.

Below is a video of the above program, running.

Leave a Reply Cancel reply