NOTIFYICONDATAA 结构 （shellapi.h）
包含系统需要在通知区域中显示通知的信息。 由 Shell_NotifyIcon使用。
语法
typedef struct _NOTIFYICONDATAA {
DWORD cbSize;
HWND hWnd;
UINT uID;
UINT uFlags;
UINT uCallbackMessage;
HICON hIcon;
#if ...
CHAR szTip[64];
#else
CHAR szTip[128];
#endif
DWORD dwState;
DWORD dwStateMask;
CHAR szInfo[256];
union {
UINT uTimeout;
UINT uVersion;
} DUMMYUNIONNAME;
CHAR szInfoTitle[64];
DWORD dwInfoFlags;
GUID guidItem;
HICON hBalloonIcon;
} NOTIFYICONDATAA, *PNOTIFYICONDATAA;
成员
cbSize
类型：DWORD
此结构的大小（以字节为单位）。
hWnd
类型：HWND
接收与通知区域中图标关联的通知的窗口句柄。
uID
类型：UINT
任务栏图标的应用程序定义标识符。 Shell 使用（hWnd 加 uID）或 guidItem 来标识调用 Shell_NotifyIcon 时要操作的图标。 可以通过为每个不同的
uFlags
类型：UINT
指示结构中哪些其他成员包含有效数据的标志，或者向工具提示提供有关其显示方式的其他信息。 此成员可以是以下值的组合：
NIF_MESSAGE（0x00000001）
0x00000001。 uCallbackMessage 成员有效。
NIF_ICON（0x00000002）
0x00000002。 hIcon 成员有效。
NIF_TIP（0x00000004）
0x00000004。 szTip 成员有效。
NIF_STATE（0x00000008）
0x00000008。 dwState 和 dwStateMask 成员有效。
NIF_INFO（0x00000010）
0x00000010。 显示气球通知。 szInfo、szInfoTitle、dwInfoFlags，uTimeout 成员有效。 请注意，uTimeout 仅在 Windows 2000 和 Windows XP 中有效。
- 若要显示气球通知，请指定NIF_INFO并在 szInfo中提供文本。
- 若要删除气球通知，请指定NIF_INFO并通过 szInfo提供空字符串。
- 若要添加通知区域图标而不显示通知，请不要设置NIF_INFO标志。
NIF_GUID（0x00000020）
0x00000020。
- Windows 7 及更高版本：guidItem 有效。
- Windows Vista 及更早版本：保留。
NIF_REALTIME（0x00000040）
0x00000040。 Windows Vista 及更高版本。 如果无法立即显示气球通知，请将其丢弃。 将此标志用于表示实时信息的通知，如果稍后显示这些信息是毫无意义的或误导性的。 例如，一条消息指出“你的电话正在响铃”。仅当与NIF_INFO标志结合使用时，NIF_REALTIME才有意义。
NIF_SHOWTIP（0x00000080）
0x00000080。 Windows Vista 及更高版本。 使用标准工具提示。 通常，当 uVersion 设置为NOTIFYICON_VERSION_4时，将取消标准工具提示，并可由应用程序绘制的弹出 UI 替换。 如果应用程序想要使用 NOTIFYICON_VERSION_4 显示标准工具提示，则可以指定NIF_SHOWTIP来指示仍应显示标准工具提示。
uCallbackMessage
类型：UINT
应用程序定义的消息标识符。 系统使用此标识符将通知消息发送到 hWnd中标识的窗口。 当鼠标事件或悬停在图标的边界矩形中、使用键盘选择或激活图标时，或在气球通知中发生这些操作时，将发送这些通知消息。
当 uVersion 成员为 0 或NOTIFYICON_VERSION时，消息的 wParam 参数包含发生事件的任务栏图标的标识符。 此标识符长度可以为 32 位。 lParam 参数保存与事件关联的鼠标或键盘消息。 例如，当指针在任务栏图标上移动时，lParam 设置为 WM_MOUSEMOVE。
当 uVersion 成员NOTIFYICON_VERSION_4时，应用程序将继续通过 uCallbackMessage 成员以应用程序定义消息的形式接收通知事件，但 lParam 和 wParam 参数的解释将更改如下：
- LOWORD（lParam） 包含通知事件，例如NIN_BALLOONSHOW、NIN_POPUPOPEN或WM_CONTEXTMENU。
- HIWORD（lParam） 包含图标 ID。 图标 ID 限制为 16 位。
-
GET_X_LPARAM（wParam） 返回通知事件NIN_POPUPOPEN、NIN_SELECT、NIN_KEYSELECT以及WM_MOUSEFIRST和WM_MOUSELAST之间的所有鼠标消息的 X 定位点坐标。 如果这些消息由键盘生成，wParam 设置为目标图标的左上角。 对于所有其他消息，未定义 wParam
。 - GET_Y_LPARAM（wParam） 返回为 X 定位点定义的通知事件和消息的 Y 定位点坐标。
hIcon
类型：HICON
要添加、修改或删除的图标的句柄。 Windows XP 及更高版本支持最多 32 BPP 的图标。
如果仅提供 16x16 像素图标，则会在设置为高 dpi 值的系统中将其缩放为更大的大小。 这可能会导致无吸引力的结果。 建议在资源文件中同时提供 16x16 像素图标和 32x32 图标。 使用 LoadIconMetric 来确保正确加载和缩放正确的图标。 有关代码示例，请参阅“备注”。
szTip[64]
类型：TCHAR[64]
一个以 null 结尾的字符串，指定标准工具提示的文本。 最多可以有 64 个字符，包括终止 null 字符。
对于 Windows 2000 及更高版本，szTip 最多可以包含 128 个字符，包括终止 null 字符。
szTip[128]
类型：TCHAR[64]
一个以 null 结尾的字符串，指定标准工具提示的文本。 最多可以有 64 个字符，包括终止 null 字符。
对于 Windows 2000 及更高版本，szTip 最多可以包含 128 个字符，包括终止 null 字符。
dwState
类型：DWORD
Windows 2000 及更高版本。 图标的状态。 以下值之一或两个值：
NIS_HIDDEN（0x00000001）
0x00000001。 图标已隐藏。
NIS_SHAREDICON（0x00000002）
0x00000002。 图标资源在多个图标之间共享。
dwStateMask
类型：DWORD
Windows 2000 及更高版本。 一个值，该值指定检索或修改 dwState 成员的位。 可能的值与 dwState的值相同。 例如，将此成员设置为 NIS_HIDDEN 会导致忽略图标共享位时仅修改项目的隐藏状态，而不考虑其值。
szInfo[256]
类型：TCHAR[256]
Windows 2000 及更高版本。 一个以 null 结尾的字符串，指定要在气球通知中显示的文本。 最多可以有 256 个字符，包括终止 null 字符，但应限制为 200 个字符（英语），以适应本地化。 若要从 UI 中删除气球通知，请删除图标（带有 NIM_DELETE），或在 uFlags 中设置 NIF_INFO 标志，并将 szInfo 设置为空字符串。
DUMMYUNIONNAME
DUMMYUNIONNAME.uTimeout
类型：UINT
Windows 2000 及更高版本。
DUMMYUNIONNAME.uVersion
类型：UINT
Windows 2000 及更高版本。 与 uTimeout（已弃用到 Windows Vista）的联合。 指定应使用哪个版本的 Shell 通知图标接口。 有关这些版本差异的详细信息，请参阅 Shell_NotifyIcon。 仅当使用 Shell_NotifyIcon 发送 NIM_SETVERSION 消息时，才使用此成员。
szInfoTitle[64]
类型：TCHAR[64]
Windows 2000 及更高版本。 一个以 null 结尾的字符串，指定气球通知的标题。 此标题显示在文本上方的较大字体中。 它最多可以有 64 个字符，包括终止 null 字符，但应限制为 48 个字符（英语），以适应本地化。
dwInfoFlags
类型：DWORD
Windows 2000 及更高版本。 可以设置为修改气球通知的行为和外观的标志。 图标放置在标题左侧。 如果 szInfoTitle 成员长度为零，则不显示图标。
NIIF_NONE（0x00000000）
0x00000000。 无图标。
NIIF_INFO （0x00000001）
0x00000001。 信息图标。
NIIF_WARNING（0x00000002）
0x00000002。 警告图标。
NIIF_ERROR（0x00000003）
0x00000003。 错误图标。
NIIF_USER（0x00000004）
0x00000004。 Windows XP SP2 及更高版本。
- Windows XP：使用在 hIcon 中标识的图标作为通知气球的标题图标。
- Windows Vista 及更高版本：使用在 hBalloonIcon 中标识的图标作为通知气球的标题图标。
NIIF_NOSOUND（0x00000010）
0x00000010。 Windows XP 及更高版本。 不要播放关联的声音。 仅适用于通知。
NIIF_LARGE_ICON（0x00000020）
0x00000020。 Windows Vista 及更高版本。 图标的大版本应用作通知图标。 这对应于SM_CXICON x SM_CYICON维度的图标。 如果未设置此标志，则使用维度SM_CXSMICON x SM_CYSMICON的图标。
- 此标志可用于所有 股票图标。
- 使用较旧的自定义图标（NIIF_USER与 hIcon）的应用程序必须在托盘图标（hIcon）中提供新的SM_CXICON x SM_CYICON 版本。 当这些图标显示在系统托盘或系统控制系统区域（SCA）中时，这些图标会缩减。
- 新的自定义图标（NIIF_USER 具有 hBalloonIcon）必须在提供的图标中提供SM_CXICON x SM_CYICON 版本（hBalloonIcon）。
NIIF_RESPECT_QUIET_TIME（0x00000080）
0x00000080。 Windows 7 及更高版本。 如果当前用户处于“静默时间”，则不显示气球通知，这是新用户首次登录其帐户后的第一小时。 在此期间，不应发送或显示大多数通知。 这样，用户就可以习惯于新的计算机系统，而不会分散注意力。 操作系统升级或干净安装后，每个用户也会有安静时间。 在安静时间使用此标志发送的通知未排队;它只是被解开了。 如果应用程序当时仍然有效，应用程序稍后可以重新发送通知。
由于应用程序无法预测它何时可能会遇到静默时间，因此我们建议此标志始终由任何应用程序针对所有适当的通知进行设置，以纪念静默时间。
在安静时间内，仍应发送某些通知，因为用户应将其作为响应用户操作的反馈，例如，当他或她插入 USB 设备或打印文档时。
如果当前用户未处于安静时间，则此标志不起作用。
NIIF_ICON_MASK（0x0000000F）
0x0000000F。 Windows XP 及更高版本。 保留。
guidItem
类型：GUID
Windows XP 及更高版本。
- Windows 7 及更高版本：标识图标的已注册 GUID。 此值替代 uID，并且是标识图标的建议方法。 必须在 uFlags 成员中设置NIF_GUID标志。
- Windows XP 和 Windows Vista：保留;必须设置为 0。
如果在一次调用 Shell_NotifyIcon中使用 GUID 标识通知图标，则必须使用同一 GUID 来标识处理同一图标的任何后续 Shell_NotifyIcon 调用中的图标。
若要生成用于此成员的 GUID，请使用 GUID 生成工具，例如 Guidgen.exe。
hBalloonIcon
类型：HICON
Windows Vista 及更高版本。 应用程序提供的自定义通知图标的句柄，该图标应独立于通知区域图标使用。 如果此成员为非 NULL，并且NIIF_USER标志在 dwInfoFlags 成员中设置，则此图标用作通知图标。 如果此成员 NULL，则会执行旧行为。
言论
有关通知 UI 和内容最佳做法的详细信息，请参阅 Windows 用户体验交互指南中的“通知”。
如果在 uFlags 成员中设置 NIF_INFO 标志，则使用气球样式通知。 有关这些通知的更多讨论，请参阅 气球工具提示。
任务栏一次只能显示多个气球通知。 如果应用程序尝试在显示通知时显示通知，则新通知将排入队列，并在旧通知消失时显示。 在 Windows Vista 之前的 Windows 版本中，无论原始通知的 uTimeout 值如何，在现有通知至少为系统最小超时长度可见之前，新通知才会显示。 如果用户似乎未使用计算机，则系统不会将此时间计入超时。
此结构的多个成员仅支持 Windows 2000 及更高版本。 若要启用这些成员，请在标头中包含以下行之一：
// 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
请注意，必须用其大小初始化结构。 如果使用当前定义的结构的大小，则应用程序可能无法与早期版本的 Shell32.dll一起运行，这需要较小的结构。 可以通过定义适当的版本号（请参阅 Shell 和 Common Controls 版本）来针对早期版本的 Shell32.dll 运行应用程序。 但是，如果应用程序还需要在较新的系统上运行，这可能会导致问题。
可以通过适当地设置 NOTIFYICONDATA 结构的大小，来保持与所有 Shell32.dll 版本的应用程序兼容性，同时仍使用当前头文件。 在初始化结构之前，请使用 DllGetVersion 来确定系统上安装了哪个 Shell32.dll 版本，并使用以下值之一初始化 cbSize：
| Shell32.dll 版本 | cbSize |
|---|---|
| 6.0.6 或更高版本（Windows Vista 及更高版本） | sizeof（NOTIFYICONDATA） |
| 6.0 （Windows XP） | NOTIFYICONDATA_V3_SIZE |
| 5.0 （Windows 2000） | NOTIFYICONDATA_V2_SIZE |
| 低于 5.0 的版本 | NOTIFYICONDATA_V1_SIZE |
将此值用于 cbSize 允许应用程序在与早期 Shell32.dll 版本兼容的方法中使用 NOTIFYICONDATA。
以下代码示例演示版本检查，该检查可启用使用 guidItem 成员的应用程序在 Windows Vista 和 Windows 7 上运行。 它提供一个布尔函数，如果操作系统为 Windows 7，则返回 true
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);
}
下面的代码示例演示了如何使用 LoadIconMetric 加载用于高 DPI 的图标。
// 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;
故障排除
如果使用 guidItem 成员标识图标，并且该图标未看到或某些调用 Shell_NotifyIcon 失败，则以下情况之一可能是原因：- NIF_GUID标志未在每次调用 Shell_NotifyIcon中设置。 在一次调用 Shell_NotifyIcon中使用 GUID 标识通知图标后，必须使用同一 GUID 来标识处理同一图标的任何后续 Shell_NotifyIcon 调用中的图标。
-
包含图标的二进制文件已移动。 二进制文件的路径包含在图标 GUID 的注册中，无法更改。 仅当文件路径和 GUID 保持不变时，才会通过升级来保留与图标关联的设置。 如果必须更改路径，应用程序应删除注册现有图标时添加的任何 GUID 信息。 删除该信息后，可以将二进制文件移动到新位置，并使用新的 GUID 重新注册它。 与原始 GUID 注册关联的任何设置都将丢失。
在并行安装的情况下，也会发生这种情况。 处理并行安装时，应用程序的新版本应更新二进制文件的 GUID。
注意 当原始文件和移动的二进制文件 由同一公司签名的验证码时，才会发生移动文件的唯一异常。 在这种情况下，通过移动保留设置。
注意
shellapi.h 标头将 NOTIFYICONDATA 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。 有关详细信息，请参阅函数原型的
要求
| 要求 | 价值 |
|---|---|
| 最低支持的客户端 | Windows XP [仅限桌面应用] |
| 支持的最低服务器 | Windows 2000 Server [仅限桌面应用] |
| 标头 | shellapi.h |