NOTIFYICONDATA

This structure provides input to the Shell_NotifyIcon function.

Declaration

typedef struct _NOTIFYICONDATA {
    DWORD cbSize;
    HWND hWnd;
    UINT uID;
    UINT uFlags;
    UINT uCallbackMessage;
    HICON hIcon;
    TCHAR szTip [128];
    DWORD dwState;
    DWORD dwStateMask;
    TCHAR szInfo [256];
    union {
        UINT uTimeout;
        UINT uVersion;
    };
    TCHAR szInfoTitle [64];
    DWORD dwInfoFlags;
    GUID guidItem;
} NOTIFYICONDATA, *PNOTIFYICONDATA;

The structure has both ANSI and Unicode forms.

Members

Interpretation varies with the dwMessage argument given to Shell_NotifyIcon. The first three members are required in all cases. The remaining members are ignored if dwMessage is either NIM_DELETE or NIM_SETFOCUS. When dwMessage is NIM_SETVERSION, only uVersion is meaningful (and it is required). For NIM_ADD and NIM_MODIFY, the uFlags member is required but the members that follow it are optional.

The cbSize member gives the size of the structure in bytes. For the structure as shown above, this should be 0x01F8 in the ANSI form and 0x03B8 in the Unicode. However, the structure has progressed through SHELL32 versions by expansion, so that other sizes are taken to indicate older versions in which some of the members shown above are not defined. Details are presently beyond the scope of these notes.

The hWnd and uID members identify the target icon by associating it with a window and providing a per-window identification number. The window is effectively the owner of the icon, which leases space in the taskbar’s notification area. The ID is this owner’s context data for the icon.

When dwMessage is NIM_ADD or NIM_MODIFY, bits in uFlags indicate which of the remaining members are set.

The uCallbackMessage member specifies the window message that is to be sent to the owner window when the taskbar window learns of events that affect the icon.

The hIcon member ...

The szTip member ...

The dwState and dwStateMask members ...

The szInfo member ...

The uTimeout member ...

When dwMessage is NIM_SETVERSION, the uTimeout member is reinterpreted as uVersion. The expected values are 0 and 3, representing old and new behaviour respectively. Anything below 3 is treated as 0. Anything above 3 is invalid. The difference between old and new behaviour is presently beyond the scope of these notes.

The szInfoTitle member ...

The dwInfoFlags member ...

The guidItem member provides a GUID to save with the icon’s persistent data stream, presumably to help retrieve the right state for the right icon in future sessions. Note however that although this GUID is so saved, it is not presently checked when recovering any persistent icon state.