NOTIFYICONDATAA 结构 (shellapi.h)

项目
03/02/2024

包含系统在通知区域中显示通知所需的信息。由 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 时要针对哪个图标进行操作。可以通过为每个 hWnd 分配不同的 uID 来让多个图标与单个 hWnd 相关联。如果指定 了 guidItem ，则忽略 uID 。

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 及更高版本。

注意自 Windows Vista 起，此成员已弃用。现在通知显示时间是基于系统辅助功能设置。

与 uVersion 联合。通知的超时值（以毫秒为单位）。系统强制实施最小和最大超时值。 在 uTimeout 中指定的过大值将设置为最大值。太小的值默认为最小值。系统最小和最大超时值当前分别设置为 10 秒和 30 秒。有关 uTimeout 的进一步讨论，请参阅备注。

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 的图标。

此标志可以与所有股票图标一起使用。
使用 hIcon) (NIIF_USER 较旧的自定义图标的应用程序必须在托盘图标中提供新的 SM_CXICON x SM_CYICON 版本， (hIcon) 。当这些图标显示在系统托盘或系统控制区 (SCA) 时，它们将纵向缩减。
使用 hBalloonIcon) 的新自定义图标 (NIIF_USER 必须在提供的图标中提供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。

如果应用程序打算在 Windows Vista 和 Windows 7 上运行，则必须检查 Windows 版本，并且仅在 Windows 7 或更高版本上指定非零 guidItem。

如果在一次调用 Shell_NotifyIcon时使用 GUID 标识通知图标，则必须在处理同一图标的任何后续 Shell_NotifyIcon 调用中使用相同的 GUID 来标识该图标。

若要生成用于此成员的 GUID，请使用 GUID 生成工具，例如 Guidgen.exe。

hBalloonIcon

类型： HICON

Windows Vista 及更高版本。应用程序提供的自定义通知图标的句柄，应独立于通知区域图标使用。如果此成员为非 NULL，并在 dwInfoFlags 成员中设置了NIIF_USER标志，则此图标将用作通知图标。如果此成员为 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 一起运行，后者需要较小的结构。可以通过定义适当的版本号来针对早期版本的 Shell32.dll 运行应用程序， (请参阅 Shell 和通用控件版本) 。但是，如果应用程序还需要在较新的系统上运行，这可能会导致问题。

通过适当设置 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 。除非此成员返回 TRUE，否则 guidItem 成员必须设置为 0。

注意此代码特定于 Windows 7 版本号。预期 Windows 和 Windows Server 的未来版本将支持 guidItem 成员，并且此时必须更新此代码，以识别更高版本的版本号，同时有效。

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 的一些调用失败，则可能是以下情况之一：

每次调用 Shell_NotifyIcon 时都没有设置 NIF_GUID标志。在一次调用 Shell_NotifyIcon时使用 GUID 标识通知图标后，必须在处理同一图标的任何后续 Shell_NotifyIcon 调用中使用相同的 GUID 来标识该图标。
移动了包含图标的二进制文件。二进制文件的路径包含在图标 GUID 的注册中，无法更改。仅当文件路径和 GUID 保持不变时，才会通过升级保留与图标关联的设置。如果必须更改路径，应用程序应删除注册现有图标时添加的任何 GUID 信息。删除该信息后，可以将二进制文件移动到新位置，并使用新的 GUID 重新注册它。与原始 GUID 注册关联的任何设置都将丢失。
在并行安装的情况下也会发生这种情况。处理并行安装时，新版本的应用程序应更新二进制文件的 GUID。

注意当原始和移动的二进制文件都由同一公司进行 Authenticode 签名时，唯一的例外是移动文件。在这种情况下，通过移动保留设置。

注意

shellapi.h 标头将 NOTIFYICONDATA 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求

要求	值
最低受支持的客户端	Windows XP [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
标头	shellapi.h

另请参阅

通知和通知区域

通过

NOTIFYICONDATAA 结构 (shellapi.h)

语法

成员

NIF_MESSAGE (0x00000001)

NIF_ICON (0x00000002)

NIF_TIP (0x00000004)

NIF_STATE (0x00000008)

NIF_INFO (0x00000010)

NIF_GUID (0x00000020)

NIF_REALTIME (0x00000040)

NIF_SHOWTIP (0x00000080)

NIS_HIDDEN (0x00000001)

NIS_SHAREDICON (0x00000002)

NIIF_NONE (0x00000000)

NIIF_INFO (0x00000001)

NIIF_WARNING (0x00000002)

NIIF_ERROR (0x00000003)

NIIF_USER (0x00000004)

NIIF_NOSOUND (0x00000010)

NIIF_LARGE_ICON (0x00000020)

NIIF_RESPECT_QUIET_TIME (0x00000080)

NIIF_ICON_MASK (0x0000000F)

注解

故障排除

要求

另请参阅

反馈

其他资源