NOTIFYICONDATA structure

Contains information that the system needs to display notifications in the notification area. Used byShell_NotifyIcon.包含了系统在通知区域显示通知所需要的信息。Shell_NotifyIcon使用这个结构体。

Syntax

C++

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

Members

cbSize

Type: DWORD

The size of this structure, in bytes.按字节计算的结构体。

hWnd

Type: HWND

A handle to the window that receives notifications associated with an icon in the notification area.接收通知区域消息的窗口句柄。

uID

Type: UINT

The application-defined identifier of the taskbar icon. The Shell uses either (hWnd plus uID) or guidItem to identify which icon to operate on whenShell_NotifyIcon is invoked. You can have multiple icons associated with a single hWnd by assigning each a differentuID. If guidItem is specified,uID is ignored.应用程序定义的任务栏图标的ID。Shell使用窗口句柄+uID或者GUID的方式来标识Shell_使用到的图标。你可以使用不同的uID来把多个图标关联到一个窗口句柄上。如果指定了GUID，那么uID就会被忽略。

uFlags

Type: UINT

Flags that either indicate which of the other members of the structure contain valid data or provide additional information to the tooltip as to how it should display. This member can be a combination of the following values:一个标志，用来表示结构体中剩下的字段哪些是可用的，或者提供提示条应当如何显示的附加信息。可以是下面一些值的组合：

NIF_MESSAGE (0x00000001)

0x00000001. The uCallbackMessage member is valid.uCallbackMessage可用。

NIF_ICON (0x00000002)

0x00000002. The hIcon member is valid.Icon可用。

NIF_TIP (0x00000004)

0x00000004. The szTip member is valid.szTip可用。

NIF_STATE (0x00000008)

0x00000008. The dwState and dwStateMask members are valid.dwState和dwStateMask可用。

NIF_INFO (0x00000010)

0x00000010. Display a balloon notification. The szInfo, szInfoTitle, dwInfoFlags, and uTimeout members are valid. Note thatuTimeout is valid only in Windows 2000 and Windows XP.显示气泡通知。szInfo、szInfoTitle、dwInfoFlags和uTimeout可用。注意“uTimeout只在2000和xp系统中可用。

To display the balloon notification, specify NIF_INFO and provide text in szInfo.要显示气泡通知，需要指定NIF_INFO标志并且给szInfo提供文本信息。
To remove a balloon notification, specify NIF_INFO and provide an empty string through szInfo.要移除气泡通知，需要指定NIF_INFO标志并且给szInfo提供一个空的字符串。
To add a notification area icon without displaying a notification, do not set the NIF_INFO flag.如果要添加一个不显示通知的通知区域图标，请不要使用NIF_INFO标志。

NIF_GUID (0x00000020)

0x00000020.

Windows 7 and later: The guidItem is valid.对于Windows7及其之后的系统，guidItem是可用的。
Windows Vista and earlier: Reserved.对于Vista及其之前的系统，作为保留字段。（这意味着不可用。）

NIF_REALTIME (0x00000040)

0x00000040. Windows Vista and later. If the balloon notification cannot be displayed immediately, discard it. Use this flag for notifications that represent real-time information which would be meaningless or misleading if displayed at a later time. For example, a message that states "Your telephone is ringing." NIF_REALTIME is meaningful only when combined with the NIF_INFO flag.仅限于Vista及其之后的系统。如果气泡通知不能立即显示，就会被丢弃。使用这个标志来显示那些一旦延时显示就会变得没有意义的实时消息。例如，显示“你的电话正在响”这条消息。

NIF_SHOWTIP (0x00000080)

0x00000080. Windows Vista and later. Use the standard tooltip. Normally, when uVersion is set to NOTIFYICON_VERSION_4, the standard tooltip is suppressed and can be replaced by the application-drawn, pop-up UI. If the application wants to show the standard tooltip with NOTIFYICON_VERSION_4, it can specify NIF_SHOWTIP to indicate the standard tooltip should still be shown.Vista及其之后的系统。使用标准工具提示。通常，当uVersion设置为NOTIFYICON_VERSION_4的时候，标准工具提示是可用的，并且可以使用一个由程序画的可以弹出的UI界面来替代。如果程序在使用NOTIFYICON_VERSION_4时想要显示标准的工具提示，可以指定NIF_SHOWTIP标志来明确指出。

uCallbackMessage

Type: UINT

An application-defined message identifier. The system uses this identifier to send notification messages to the window identified in hWnd. These notification messages are sent when a mouse event or hover occurs in the bounding rectangle of the icon, when the icon is selected or activated with the keyboard, or when those actions occur in the balloon notification.应用程序定义的消息ID。系统使用这个ID向由hWnd指定的窗口发送通知消息。当鼠标事件在图标区域发生、鼠标在图标的相关区域晃悠时，发送这个消息；当用鼠标或者键盘选中了图标、或者这些行为发生在气泡通知区域时，发送消息。

When the uVersion member is either 0 or NOTIFYICON_VERSION, thewParam parameter of the message contains the identifier of the taskbar icon in which the event occurred. This identifier can be 32 bits in length. ThelParam parameter holds the mouse or keyboard message associated with the event. For example, when the pointer moves over a taskbar icon,lParam is set toWM_MOUSEMOVE.当uVersion为0或者NOTIfYICON_VERSION时，消息的wParam参数包含了发生事件的图标的ID。这个ID可以是32字节长。lParam参数包含了与该事件相关的鼠标或者键盘消息。例如，当鼠标指针经过任务栏图标时，发送WM_MOUSEMOVE消息。

When the uVersion member is NOTIFYICON_VERSION_4, applications continue to receive notification events in the form of application-defined messages through theuCallbackMessage member, but the interpretation of thelParam and wParam parameters of that message is changed as follows:当uVersion为NOTIFYICON的时候，应用程序通过uCallbackMessage成员继续接收应用程序自定义消息的通知事件，但是lParam和wParam参数意义发生了改变：

LOWORD(lParam) contains notification events, such as NIN_BALLOONSHOW, NIN_POPUPOPEN, or WM_CONTEXTMENU.lParamde低字：包含了通知事件，例如NIN_BALLOONSHOW、NIN_POPUPOPEN、WM_CONTEXTMENU。
HIWORD(lParam) contains the icon ID. Icon IDs are restricted to a length of 16 bits.lParam的高字：包含了16位的图标ID。
GET_X_LPARAM(wParam) returns the X anchor coordinate for notification events NIN_POPUPOPEN, NIN_SELECT, NIN_KEYSELECT, and all mouse messages between WM_MOUSEFIRST and WM_MOUSELAST. If any of those messages are generated by the keyboard,wParam is set to the upper-left corner of the target icon. For all other messages,wParam is undefined.使用GET_X_LPARAM(wParam)返回NIN_POPUPOPEN, NIN_SELECT, NIN_KEYSELECT事件的X锚坐标（--？），以及WM_MOUSEFIRST和WM_MOUSELAST消息之间的所有鼠标消息。如果这些消息有由键盘产生的，那么wParam设置为目标图标的左上角，并且不使用wParam参数。
GET_Y_LPARAM(wParam) returns the Y anchor coordinate for notification events and messages as defined for the X anchor.GET_Y_LPARAM(wParam)返回通知事件的Y坐标锚以及和X坐标锚一样的消息。

hIcon

Type: HICON

A handle to the icon to be added, modified, or deleted. Windows XP and later support icons of up to 32 BPP.将要添加/修改/删除的图标句柄。

If only a 16x16 pixel icon is provided, it is scaled to a larger size in a system set to a high dpi value. This can lead to an unattractive result. It is recommended that you provide both a 16x16 pixel icon and a 32x32 icon in your resource file. UseLoadIconMetric to ensure that the correct icon is loaded and scaled appropriately. See Remarks for a code example.如果只提供了16×16的像素图标，系统会所放到一个大尺寸来适应高dpi。这将导致一个非常难看的显示效果。所以建议你在资源中提供16×16和32×32两种图标。使用LoadIconMetric函数来确定装载了正确的图标并且被适当的缩放。

szTip

Type: TCHAR[64]

A null-terminated string that specifies the text for a standard tooltip. It can have a maximum of 64 characters, including the terminating null character.一个标准提示字符串，以NULL结尾。包括结尾NULL字符，最多可以64个。

For Windows 2000 and later, szTip can have a maximum of 128 characters, including the terminating null character.对于2000及其以后的版本，szTip可以容纳包括NULL结尾在内的128个字符。

dwState

Type: DWORD

Windows 2000 and later. The state of the icon. One or both of the following values:2000及其以后的系统支持此项。图标的状态。可以是下面的一个或者几个值。

NIS_HIDDEN (0x00000001)

0x00000001. The icon is hidden.隐藏。

NIS_SHAREDICON (0x00000002)

0x00000002. The icon resource is shared between multiple icons.共享图标。

dwStateMask

Type: DWORD

Windows 2000 and later. A value that specifies which bits of the dwState member are retrieved or modified. The possible values are the same as those for dwState. For example, setting this member to NIS_HIDDEN causes only the item's hidden state to be modified while the icon sharing bit is ignored regardless of its value.2000及其以后的系统支持。指定了dwState的哪些位是可以被检索或者修改的。取值和dwState相同。例如，dwStateMask设置了NIS_HIDDEN，则当图标的共享字节被忽略时，无论dwState是什么值，只有MIS_HIDDEN状态可以修改。（这块英文没看懂。）

szInfo

Type: TCHAR[256]

Windows 2000 and later. A null-terminated string that specifies the text to display in a balloon notification. It can have a maximum of 256 characters, including the terminating null character, but should be restricted to 200 characters in English to accommodate localization. To remove the balloon notification from the UI, either delete the icon (withNIM_DELETE) or set the NIF_INFO flag in uFlags and set szInfo to an empty string.2000及其以后的系统支持。气泡通知中显示的文本，该文本以NULL结尾。最多可以有包括NULL在内的256个字符，但是因为要调整区域所以应该限制在200个以内。如果要从UI删除气泡通知，可以（用NIM_DELETE）删除图标，或者在uFlags中设置NIF_INFO并且设置szInfo为空字符串。

uTimeout

Type: UINT

Windows 2000 and later.

Note This member is deprecated as of Windows Vista. Notification display times are now based on system accessibility settings.在Vista中不赞成使用这个成员。通知显示的时间现在基于系统的辅助功能设置。

Union with uVersion. The timeout value, in milliseconds, for notification. The system enforces minimum and maximum timeout values. Values specified inuTimeout that are too large are set to the maximum value. Values that are too small default to the minimum value. The system minimum and maximum timeout values are currently set at 10 seconds and 30 seconds, respectively. See Remarks for further discussion of uTimeout.和uVersion配合使用，通知的超时值，以微妙计。由系统强制确保最大和最小的超时值。超过最大值的uTimeout值会被替换为最大值，超过最小值的uTimeout值也会被替换为最小值。系统最小和最大的超时值被本别设置为10秒和30秒。Remarks里有更多讨论。

uVersion

Type: UINT

Windows 2000 and later. Union with uTimeout (deprecated as of Windows Vista). Specifies which version of the Shell notification icon interface should be used. For more information on the differences in these versions, seeShell_NotifyIcon. This member is employed only when using Shell_NotifyIcon to send an NIM_SETVERSION message.2000及其以后的系统支持。配合uTimeout使用（不建议Vista使用此项）。指定Shell通知图标界面采用哪一种版本。更多的关于版本的信息，参见Shell_NotifyIcon。仅当调用Shell_NotifyIcon发送NIM_SETVERSION消息时，这个成员才是有用的。

Use this value for applications designed for Windows versions prior to Windows 2000.2000之前的系统使用这个值。

NOTIFYICON_VERSION

Use the Windows 2000 behavior. Use this value for applications designed for Windows 2000 and later.使用2000系统风格的效果。2000及其以后的系统可以使用这个值。

NOTIFYICON_VERSION_4

Use the current behavior. Use this value for applications designed for Windows Vista and later.使用当前的行为。Vista及其以后的系统可以使用这个值。

szInfoTitle

Type: TCHAR[64]

Windows 2000 and later. A null-terminated string that specifies a title for a balloon notification. This title appears in a larger font immediately above the text. It can have a maximum of 64 characters, including the terminating null character, but should be restricted to 48 characters in English to accommodate localization.

dwInfoFlags

Type: DWORD

Windows 2000 and later. Flags that can be set to modify the behavior and appearance of a balloon notification. The icon is placed to the left of the title. If theszInfoTitle member is zero-length, the icon is not shown.2000及其以后的系统支持。可以用来设置气泡通知的外观和行为。图标被放在标题的左侧。如果szInfoTitle成员的字符长度为0，那么图标不会显示。

NIIF_NONE (0x00000000)

0x00000000. No icon.没有图标。

NIIF_INFO (0x00000001)

0x00000001. An information icon.信息图标。

NIIF_WARNING (0x00000002)

0x00000002. A warning icon.警告图标。

NIIF_ERROR (0x00000003)

0x00000003. An error icon.错误图标。

NIIF_USER (0x00000004)

0x00000004. Windows XP SP2 and later.XP SP2及其之后的系统才支持此项。

Windows XP: Use the icon identified in hIcon as the notification balloon's title icon.对于XP：使用关联hIcon的图标ID作为通知气泡的标题图标。
Windows Vista and later: Use the icon identified in hBalloonIcon as the notification balloon's title icon.对于Vista及其之后的系统：使用关联hBalloomIcon的图标ID作为通知气泡的标题图标。

NIIF_NOSOUND (0x00000010)

0x00000010. Windows XP and later. Do not play the associated sound. Applies only to notifications.XP及其之后系统支持。不播放关联的声音。仅通知。

NIIF_LARGE_ICON (0x00000020)

0x00000020. Windows Vista and later. The large version of the icon should be used as the notification icon. This corresponds to the icon with dimensions SM_CXICON x SM_CYICON. If this flag is not set, the icon with dimensions XM_CXSMICON x SM_CYSMICON is used.Vista及其之后的系统支持。大图版的图标作为通知图标。这个对应的图标尺寸为：SM_CXICON ×SM_CYICON。如果没有启用这个标志，那么图标的尺寸就是XM_CXSMICON x SM_CYSMICON。

This flag can be used with all stock icons.所有的Stock图标都可以使用这个标志。
Applications that use older customized icons (NIIF_USER with hIcon) must provide a new SM_CXICON x SM_CYICON version in the tray icon (hIcon). These icons are scaled down when they are displayed in the System Tray or System Control Area (SCA).使用旧的自定义图标的应用程序必须提供一个新的SM_CXICON×SM_CYICON做为通知区域驻留图标。当在System Tray和SCA中显示时，这些图标会被缩小。
New customized icons (NIIF_USER with hBalloonIcon) must supply an SM_CXICON x SM_CYICON version in the supplied icon (hBalloonIcon).新的定制图标必须提供SM_CXICON×SM_CYICON的尺寸。

NIIF_RESPECT_QUIET_TIME (0x00000080)

0x00000080. Windows 7 and later. Do not display the balloon notification if the current user is in "quiet time", which is the first hour after a new user logs into his or her account for the first time. During this time, most notifications should not be sent or shown. This lets a user become accustomed to a new computer system without those distractions. Quiet time also occurs for each user after an operating system upgrade or clean installation. A notification sent with this flag during quiet time is not queued; it is simply dismissed unshown. The application can resend the notification later if it is still valid at that time.在安静时间下请勿显示通知图标，所谓的安静模式就是一个新用户初次登录帐户的第一个小时。在此期间，大多数的通知都不应该推送或者显示。这可以让用户专心熟悉一个新的计算机系统。安静时间也发生在系统更新或者清理安装的时候。在安静时间发送的通知不会进入排队队列，它仅仅是会不显示。如果应用程序仍旧在运行，那么应用可以重新发送通知。

Because an application cannot predict when it might encounter quiet time, we recommended that this flag always be set on all appropriate notifications by any application that means to honor quiet time.因为应用程序不能够预测何时是安静时间，所以我们微软建议你在所有的通知上都加上这个标志，这样一来就当我们尊重了了安静时间这个设置（我们该干嘛干嘛）。（我了割草，我英语弱爆了。）

During quiet time, certain notifications should still be sent because they are expected by the user as feedback in response to a user action, for instance when he or she plugs in a USB device or prints a document.在安静时间内，通知仍旧会被发送，因为用户需要它们并且会做出相应的用户行为。例如，当插入USB设备或者打印文档的时候。

If the current user is not in quiet time, this flag has no effect.如果用户当前不是在安静时间，那么这个标志是无效的。

NIIF_ICON_MASK (0x0000000F)

0x0000000F. Windows XP and later. Reserved.XP及其以后的系统：保留。

guidItem

Type: GUID

Windows XP and later.XP及其之后的系统支持此项。

Windows 7 and later: A registered GUID that identifies the icon. This value overrides uID and is the recommended method of identifying the icon. The NIF_GUID flag must be set in theuFlags member.win7及其之后的系统：注册过的GUID来表示图标。这个值会覆盖uID的值，建议用此方法来标识图标。uFlags成员必须包含NIF_GUID标志。
Windows XP and Windows Vista: Reserved; must be set to 0.XP和Vista不使用此标志，置0.（所以为了发布XP和Win7兼容的程序，不要使用这个字段。）

If your application is intended to run on both Windows Vista and Windows 7, it is imperative that you check the version of Windows and only specify a nonzeroguidItem if on Windows 7 or later.如果你的程序想在Vista和Win7上运行，必须检查系统的版本并且只能是在Win7上使用非0值。（意思是，vista不支持此项，如果要写兼容vista和Win7的程序，要么都别用，要么查看系统版本，然后分别写代码。）

If you identify the notification icon with a GUID in one call to Shell_NotifyIcon, you must use that same GUID to identify the icon in any subsequent Shell_NotifyIcon calls that deal with that same icon.如果你在Shell_NotifyIcon中使用了GUID来标识一个通知图标，那么之后对于同一个图标的Shell_No调用，你必须使用同一个GUID。

To generate a GUID for use in this member, use a GUID-generating tool such as Guidgen.exe.可以使用Guidgen.exe来生成一个GUID。

hBalloonIcon

Type: HICON

Windows Vista and later. The handle of a customized notification icon provided by the application that should be used independently of the notification area icon. If this member is non-NULL and the NIIF_USER flag is set in the dwInfoFlags member, this icon is used as the notification icon. If this member is NULL, the legacy behavior is carried out.Vista及其之后的系统支持。程序提供的自定义通知图标的句柄，必须独立于通知区域图标。如果这个字段不为NULL，并且dwInfoFlags设置为NIF_USER，那么这个图标会被用作通知图标。如果这个成员为NULL，合法的动作就是继续执行。（？？）

Remarks

See Notifications in the Windows User Experience Interaction Guidelines for more information on notification UI and content best practices.

If you set the NIF_INFO flag in the uFlags member, the balloon-style notification is used. For more discussion of these notifications, seeBalloon tooltips.

No more than one balloon notification at a time can be displayed for the taskbar. If an application attempts to display a notification when one is already being displayed, the new notification is queued and displayed when the older notification goes away. In versions of Windows before Windows Vista, the new notification would not appear until the existing notification has been visible for at least the system minimum timeout length, regardless of the original notification'suTimeout value. If the user does not appear to be using the computer, the system does not count this time toward the timeout.

Several members of this structure are only supported for Windows 2000 and later. To enable these members, include one of the following lines in your header:

C++

// Windows Vista and later:
#define NTDDI_VERSION NTDDI_WIN2K
#define NTDDI_VERSION NTDDI_WINXP
#define NTDDI_VERSION NTDDI_VISTA// Windows XP and earlier:
#define _WIN32_IE 0x0500

Note that you must initialize the structure with its size. If you use the size of the currently defined structure, the application might not run with earlier versions of Shell32.dll, which expect a smaller structure. You can run your application against earlier versions of Shell32.dll by defining the appropriate version number (see Shell and Common Controls Versions). However, this might cause problems if your application also needs to run on more recent systems.

You can maintain application compatibility with all Shell32.dll versions while still using the current header files by setting the size of theNOTIFYICONDATA structure appropriately. Before you initialize the structure, useDllGetVersion to determine which Shell32.dll version is installed on the system and initializecbSize with one of these values:

Shell32.dll Version	cbSize
6.0.6 or higher (Windows Vista and later)	sizeof(NOTIFYICONDATA)
6.0 (Windows XP)	NOTIFYICONDATA_V3_SIZE
5.0 (Windows 2000)	NOTIFYICONDATA_V2_SIZE
Versions lower than 5.0	NOTIFYICONDATA_V1_SIZE

Using this value for cbSize allows your application to use NOTIFYICONDATA in a method compatible with earlier Shell32.dll versions.

The following code example shows version checking that can enable an application that uses theguidItem member to run on both Windows Vista and Windows 7. It provides a Boolean function that returnsTRUE if the operating system is Windows 7. Unless this member returnsTRUE, the guidItem member must be set to 0.

Note This code is specific to the Windows 7 version number. It is expected that future versions of Windows and Windows Server will support theguidItem member, and at that time this code must be updated to identify later version numbers as valid as well.

C++

BOOL IsWin7OrLater()
{// Initialize the OSVERSIONINFOEX structure.OSVERSIONINFOEX osvi;ZeroMemory(&osvi, sizeof(OSVERSIONINFOEX));osvi.dwOSVersionInfoSize = sizeof(OSVERSIONINFOEX);osvi.dwMajorVersion = 6;osvi.dwMinorVersion = 1;// Initialize the condition mask.DWORDLONG dwlConditionMask = 0;VER_SET_CONDITION(dwlConditionMask, VER_MAJORVERSION, VER_GREATER_EQUAL);VER_SET_CONDITION(dwlConditionMask, VER_MINORVERSION, VER_GREATER_EQUAL);// Perform the test.return VerifyVersionInfo(&osvi, VER_MAJORVERSION | VER_MINORVERSION,dwlConditionMask);
}

The following code example shows the use of LoadIconMetric to load an icon for use with high DPI.

C++

// Declare NOTIFYICONDATA details.
// Error handling is omitted here for brevity. Do not omit it in your code.NOTIFYICONDATA nid = {};
nid.cbSize = sizeof(nid);
nid.hWnd = hWnd;
nid.uFlags = NIF_ICON | NIF_TIP | NIF_GUID;// Note: This is an example GUID only and should not be used.
// Normally, you should use a GUID-generating tool to provide the value to
// assign to guidItem.
static const GUID myGUID = {0x23977b55, 0x10e0, 0x4041, {0xb8, 0x62, 0xb1, 0x95, 0x41, 0x96, 0x36, 0x69}};
nid.guidItem = myGUID;// This text will be shown as the icon's tooltip.
StringCchCopy(nid.szTip, ARRAYSIZE(nid.szTip), L"Test application");// Load the icon for high DPI.
LoadIconMetric(hInst, MAKEINTRESOURCE(IDI_SMALL), LIM_SMALL, &(nid.hIcon));// Show the notification.
Shell_NotifyIcon(NIM_ADD, &nid) ? S_OK : E_FAIL;

Troubleshooting

If you are using the guidItem member to identify the icon, and that icon is not seen or some calls toShell_NotifyIcon fail, one of the following cases is the likely cause:常见错误：

The NIF_GUID flag was not set in every call to Shell_NotifyIcon. Once you identify the notification icon with a GUID in one call toShell_NotifyIcon, you must use that same GUID to identify the icon in any subsequentShell_NotifyIcon calls that deal with that same icon.
The binary file that contains the icon was moved. The path of the binary file is included in the registration of the icon's GUID and cannot be changed. Settings associated with the icon are preserved through an upgrade only if the file path and GUID are unchanged. If the path must be changed, the application should remove any GUID information that was added when the existing icon was registered. Once that information is removed, you can move the binary file to a new location and reregister it with a new GUID. Any settings associated with the original GUID registration will be lost.

This also occurs in the case of a side-by-side installation. When dealing with a side-by-side installation, new versions of the application should update the GUID of the binary file.

Note The only exception to a moved file occurs when both the original and moved binary files areAuthenticode-signed by the same company. In that case, settings are preserved through the move.

Requirements

Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Header	Shellapi.h