Sends a message to the taskbar's status area.

Syntax

BOOL Shell_NotifyIcon(      
    DWORD dwMessage,
    PNOTIFYICONDATA lpdata
);

Parameters

dwMessage

[in] A variable of type DWORD that specifies the action to be taken. It can have one of the following values.

NIM_ADD

0x00000000. Adds an icon to the status area. The hWnd and uID members of the NOTIFYICONDATA structure pointed to by lpdata will be used to identify the icon in later calls to Shell_NotifyIcon.

NIM_MODIFY

0x00000001. Modifies an icon in the status area. Use the hWnd and uID members of the NOTIFYICONDATA structure pointed to by lpdata to identify the icon to be modified.

NIM_DELETE

0x00000002. Deletes an icon from the status area. Use the hWnd and uID members of the NOTIFYICONDATA structure pointed to by lpdata to identify the icon to be deleted.

NIM_SETFOCUS

0x00000003. Shell32.dll version 5.0 and later only. Returns focus to the taskbar notification area. Taskbar icons should use this message when they have completed their user interface operation. For example, if the taskbar icon displays a shortcut menu, but the user presses ESC to cancel it, use NIM_SETFOCUS to return focus to the taskbar notification area.

NIM_SETVERSION

0x00000004. Shell32.dll version 5.0 and later only. Instructs the taskbar to behave according to the version number specified in the uVersion member of the structure pointed to by lpdata. This message allows you to specify whether you want the version 5.0 behavior found on Microsoft Windows 2000 systems, or the behavior found on earlier Shell versions. The default value for uVersion is zero, indicating that the original Windows 95 notify icon behavior should be used. For details, see the Remarks section.

lpdata

[in] A pointer to a NOTIFYICONDATA structure. The content of the structure depends on the value of dwMessage.

Return Value

Returns TRUE if successful, or FALSE otherwise. If dwMessage is set to NIM_SETVERSION, the function returns TRUE if the version was successfully changed, or FALSE if the requested version is not supported.

You can call GetLastError for more specific information about a failure case. The most common cause of failure is that the taskbar window doesn't exist or is unresponsive. GetLastError in that case returns E_FILE_NOT_FOUND.

Remarks

As of Windows 2000 (Shell32.dll version 5.0), Shell_NotifyIcon mouse and keyboard events are handled differently than in earlier Shell versions found on Microsoft Windows NT 4.0, Windows 95, and Windows 98. The differences include the following:

• If a user selects a notify icon's shortcut menu with the keyboard, the Shell now sends the associated application a WM_CONTEXTMENU message. Earlier versions send WM_RBUTTONDOWN and WM_RBUTTONUP messages.
• If a user selects a notify icon with the keyboard and activates it with the SPACEBAR or ENTER key, the version 5.0 Shell sends the associated application an NIN_KEYSELECT notification. Earlier versions send WM_RBUTTONDOWN and WM_RBUTTONUP messages.
• If a user selects a notify icon with the mouse and activates it with the ENTER key, the Shell now sends the associated application an NIN_SELECT notification. Earlier versions send WM_RBUTTONDOWN and WM_RBUTTONUP messages.

As of Windows XP (Shell32.dll version 6.0), if a user passes the mouse pointer over an icon with which a balloon ToolTip is associated, the Shell sends the following messages:

• NIN_BALLOONSHOW. Sent when the balloon is shown (balloons are queued).
• NIN_BALLOONHIDE. Sent when the balloon disappears. For example, when the icon is deleted. This message is not sent if the balloon is dismissed because of a timeout or if the user clicks the mouse.
• NIN_BALLOONTIMEOUT. Sent when the balloon is dismissed because of a timeout.
• NIN_BALLOONUSERCLICK. Sent when the balloon is dismissed because the user clicked the mouse.

In addition to those messages, as of Windows Vista (Shell32.dll version 6.0.6), if a user passes the mouse pointer over an icon with which a balloon ToolTip is associated, the Windows Vista Shell also adds the following messages:

• NIN_POPUPOPEN. Sent when the user hovers the cursor over an icon to indicate that the richer pop-up user interface (UI) should be used in place of a standard textual ToolTip.
• NIN_POPUPCLOSE. Sent when a cursor no longer hovers over an icon to indicate that the rich pop-up UI should be closed.

Regardless of the operating system version, you can select which way the Shell should behave by calling Shell_NotifyIcon with dwMessage set to NIM_SETVERSION. Set the uVersion member of the NOTIFYICONDATA structure pointed to by lpdata to indicate whether you want Windows 2000, Windows Vista, or pre-version 5.0 (Windows 95) behavior.

Note  The messages discussed above are not conventional Windows messages. They are sent as the lParam value of the application-defined message that is specified in the uCallbackMessage member of the NOTIFYICONDATA structure pointed to by lpdata, when Shell_NotifyIcon is called with the NIM_ADD flag set in dwMessage.

As of Windows XP Service Pack 2 (SP2), a custom icon can be displayed in the notification balloon. This allows the calling process to customize the notification beyond the previously available options of info, warning, and error, and distinguish it from other types of notification for the user.

Function Information

Minimum DLL Version	shell32.dll version 4.0 or later
Custom Implementation	No
Header	shellapi.h
Import library	shell32.lib
Minimum operating systems	Windows NT 4.0, Windows 95
Unicode	Implemented as ANSI and Unicode versions.