Shell_NotifyIcon

Declaration

BOOL
Shell_NotifyIcon (
    DWORD dwMessage,
    PNOTIFYICONDATA lpdata);

The function has an ANSI form, both with and without the A suffix, and a Unicode form, with the W suffix.

Parameters

The dwMessage argument loosely describes the operation to perform with the information in the NOTIFYICONDATA structure addressed by the lpdata argument. The following are the values that EXPLORER.EXE recognises for dwMessage:

The NOTIFYICONDATA structure is described separately, for although it is used only for this function, it is quite large and is complicated by having gone through several expansions which all remain valid.

Return Value

The function returns FALSE to indicate failure. Call GetLastError to retrieve an error code.

Behaviour

Though SHELL32 implements the function, its role is almost entirely that of a switchboard, to direct the call to the taskbar window. The function therefore has some behaviour originating in SHELL32.DLL and some in EXPLORER.EXE (which is the ordinary provider of the taskbar window).

SHELL32

If there is no top-level window with the class name expected of the taskbar, namely “Shell_TrayWnd”, then the function has nowhere to send the request, and fails.

As a switchboard, SHELL32 is mostly unconcerned with interpreting the function’s arguments. However, the NOTIFYICONDATA structure expected at lpdata has had several layouts through successive SHELL32 versions. The caller of this function may be old and be using an old layout. SHELL32 has the job of detecting this and of repackaging the input so that the taskbar window need deal only with the latest layout. Details of this repackaging are presently beyond the scope of these notes.

The taskbar may be, and typically is, implemented in another process. The function’s input is passed to the taskbar window as a WM_COPYDATA message, blocking the calling thread even from nonqueued messages until a reply is obtained, but with a timeout of 4 seconds and a direction to abort the message if the target process seems hung. If these delivery conditions are frustrated, the function fails.

ANSI Form

This function is nowadays implemented as natively Unicode. As for callers who provide old versions of the structure, SHELL32 repackages ANSI input so that the taskbar window need only deal with Unicode. The details are presently beyond the scope of these notes.

EXPLORER

What the taskbar window does with the passed data is presently beyond the scope of these notes. Treat the following as nothing more than incidental.

If the REST_NOTRAYITEMSDISPLAY restriction was in force when the taskbar was created, then the taskbar does not accommodate notification-area icons except for the clock (which is an internal implementation of the Windows Explorer and not subject to this function). In this configuration, EXPLORER sets the function to succeed, even for otherwise invalid values of dwMessage. The only non-trivial provision is to respect NIM_SETFOCUS: if there is a notification area to show, meaning that the clock is not also disabled, then the focus is set to the clock.

Availability

The Shell_NotifyIcon function is exported by name in an ANSI form (with and without an A suffix) and a Unicode form (with a W suffix). The function has long been documented.

This is an ancient SHELL32 function. It is found in version 1.30 from Win32s and 3.51 from Windows NT 3.51, though admittedly with implementations that fail trivially (returning FALSE having done nothing but set ERROR_CALL_NOT_IMPLEMENTED as the error code). The function has been “live” since version 4.00.

The Windows implementations do not bother with Unicode. Version 4.00 has no Unicode form to export. Later versions export a Unicode form, but only in a trivial coding (which just returns FALSE, without setting an error code).