Структура NOTIFYICONDATAA (shellapi.h)

Статья
03/08/2023

Содержит сведения, необходимые системе для отображения уведомлений в области уведомлений. Используется 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

Определяемый приложением идентификатор значка панели задач. Оболочка использует (hWnd плюс uID) или guidItem , чтобы определить, с каким значком следует работать при вызове Shell_NotifyIcon . С одним hWnd можно связать несколько значков, назначив каждому из них свой идентификатор uID. Если указан 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_REALTIME имеет смысл только в сочетании с флагом NIF_INFO.

NIF_SHOWTIP (0x00000080)

0x00000080. Windows Vista и более поздних версий. Используйте стандартную подсказку. Как правило, если для uVersion задано значение NOTIFYICON_VERSION_4, стандартная подсказка подавляется и может быть заменена нарисованный приложением всплывающий пользовательский интерфейс. Если приложение хочет отобразить стандартную подсказку с 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) содержит идентификатор значка. Длина идентификаторов значков ограничена 16 битами.
GET_X_LPARAM(wParam) возвращает координату привязки X для событий уведомлений NIN_POPUPOPEN, NIN_SELECT, NIN_KEYSELECT и всех сообщений мыши между WM_MOUSEFIRST и WM_MOUSELAST. Если какое-либо из этих сообщений создается с помощью клавиатуры, wParam устанавливается в левый верхний угол целевого значка. Для всех остальных сообщений wParam не определен.
GET_Y_LPARAM(wParam) возвращает координату привязки Y для событий уведомлений и сообщений, как определено для привязки X.

hIcon

Тип: HICON

Дескриптор значка для добавления, изменения или удаления. Windows XP и более поздних версий поддерживают значки до 32 BPP.

Если указан только значок размером 16x16 пикселей, он масштабируется до большего размера в системе с высоким значением точек на дюйм. Это может привести к непривлекательным результатам. Рекомендуется указать в файле ресурсов значок 16x16 пикселей и значок 32x32. Используйте LoadIconMetric , чтобы убедиться, что правильный значок загружен и масштабирован соответствующим образом. Пример кода см. в разделе Примечания.

szTip[64]

Тип: TCHAR[64]

Строка, завершающаяся значением NULL, задающая текст стандартной подсказки. Он может содержать не более 64 символов, включая завершающий символ NULL.

Для Windows 2000 и более поздних версий szTip может содержать не более 128 символов, включая завершающий символ NULL.

szTip[128]

Тип: TCHAR[64]

Для 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 символами на английском языке. Чтобы удалить всплывающее уведомление из пользовательского интерфейса, удалите значок (с NIM_DELETE) или установите флаг NIF_INFO в uFlags и задайте для szInfo пустую строку.

DUMMYUNIONNAME

DUMMYUNIONNAME.uTimeout

Тип: UINT

Windows 2000 и более поздних версий.

Примечание Этот элемент не рекомендуется использовать в Windows Vista. Время отображения уведомлений теперь зависит от параметров специальных возможностей системы.

Объединение с uVersion. Значение времени ожидания (в миллисекундах) для уведомления. Система применяет минимальное и максимальное значения времени ожидания. Для слишком больших значений, указанных в uTimeout , устанавливается максимальное значение. Значения, которые слишком малы, по умолчанию равны минимальному значению. Минимальное и максимальное значения времени ожидания системы в настоящее время устанавливаются в 10 секунд и 30 секунд соответственно. Дополнительные сведения о uTimeout см. в разделе Примечания.

DUMMYUNIONNAME.uVersion

Тип: UINT

Windows 2000 и более поздних версий. Объединение с uTimeout (не рекомендуется использовать в Windows Vista). Указывает, какую версию интерфейса значка уведомления оболочки следует использовать. Дополнительные сведения о различиях в этих версиях см. в разделе 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 с пакетом обновления 2 (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), должны предоставлять новую версию SM_CXICON x SM_CYICON в значке области (hIcon). Эти значки масштабируются, когда они отображаются в области задач или в области управления системой (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 и является рекомендуемым методом идентификации значка. Флаг NIF_GUID должен быть установлен в элементе uFlags .
Windows XP и Windows Vista: зарезервировано; значение должно иметь значение 0.

Если приложение предназначено для работы в Windows Vista и Windows 7, необходимо проверка версию Windows и указать ненулевой guidItem только в Windows 7 или более поздней версии.

Если вы идентифицируете значок уведомления с помощью GUID в одном вызове Shell_NotifyIcon, необходимо использовать этот же GUID для идентификации значка во всех последующих вызовах Shell_NotifyIcon , которые имеют дело с этим значком.

Чтобы создать GUID для использования в этом элементе, используйте средство создания GUID, например Guidgen.exe.

hBalloonIcon

Тип: HICON

Windows Vista и более поздних версий. Дескриптор настраиваемого значка уведомления, предоставляемого приложением, который должен использоваться независимо от значка области уведомлений. Если этот элемент не равен NULL и в элементе dwInfoFlags установлен флаг NIIF_USER, этот значок используется в качестве значка уведомления. Если этот элемент имеет значение NULL, выполняется устаревшее поведение.

Дополнительные сведения о рекомендациях по пользовательскому интерфейсу и содержимому см. в разделе Уведомления в руководстве по взаимодействию с пользователем Windows.

Если вы задали флаг NIF_INFO в элементе uFlags , используется уведомление в стиле выноски. Дополнительные сведения об этих уведомлениях см. в разделе Всплывающие подсказки.

На панели задач одновременно может отображаться не более одного всплывающего уведомления. Если приложение пытается отобразить уведомление, когда оно уже отображается, новое уведомление помещается в очередь и отображается, когда старое уведомление исчезает. В версиях Windows, предшествующих Windows Vista, новое уведомление не будет отображаться до тех пор, пока существующее уведомление не будет отображаться по крайней мере в течение минимального времени ожидания системы, независимо от значения 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, определив соответствующий номер версии (см . статью Версии оболочки и common Controls). Однако это может привести к проблемам, если приложение также должно работать в более новых системах.

Вы можете поддерживать совместимость приложений со всеми версиями Shell32.dll, но при этом использовать текущие файлы заголовков, задав соответствующий размер структуры NOTIFYICONDATA . Перед инициализацией структуры используйте 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 позволяет приложению использовать NOTIFYICONDATA в методе, совместимом с более ранними Shell32.dll версиями.

В следующем примере кода показана проверка версии, которая позволяет приложению, использующим элемент guidItem , выполняться в Windows Vista и Windows 7. Она предоставляет логическую функцию, которая возвращает значение TRUE , если операционная система windows 7. Если этот элемент не возвращает значение 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 для загрузки значка для использования с высоким разрешением.

// 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. После идентификации значка уведомления с помощью GUID в одном вызове Shell_NotifyIcon необходимо использовать этот же идентификатор GUID для идентификации значка во всех последующих вызовах Shell_NotifyIcon , которые имеют дело с этим значком.
Двоичный файл, содержащий значок, был перемещен. Путь к двоичному файлу включается в регистрацию GUID значка и не может быть изменен. Параметры, связанные со значком, сохраняются при обновлении только в том случае, если путь к файлу и GUID не изменяются. Если необходимо изменить путь, приложение должно удалить все данные GUID, добавленные при регистрации существующего значка. После удаления этой информации можно переместить двоичный файл в новое расположение и повторно зарегистрировать его с помощью нового GUID. Все параметры, связанные с исходной регистрацией GUID, будут потеряны.
Это также происходит в случае параллельной установки. При параллельной установке новые версии приложения должны обновлять GUID двоичного файла.

Примечание Единственное исключение из перемещенного файла возникает, когда исходный и перемещенный двоичные файлы подписаны на Authenticode одной и той же компанией. В этом случае параметры сохраняются при перемещении.

Примечание

Заголовок shellapi.h определяет NOTIFYICONDATA в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	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)

Комментарии

Устранение неполадок

Требования

См. также раздел

Обратная связь

Дополнительные ресурсы