Структура 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

Идентификатор, определенный приложением значка панели задач. Оболочка использует (hWnd plus 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.

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

szTip[64]

Тип: TCHAR[64]

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

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

szTip[128]

Тип: TCHAR[64]

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

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

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

hBalloonIcon

Тип: HICON

Windows Vista и более поздние версии. Дескриптор настраиваемого значка уведомления, предоставляемого приложением, которое должно использоваться независимо от значка области уведомлений. Если этот элемент не равен NULL, а флаг NIIF_USER установлен в элементе dwInfoFlags , этот значок используется в качестве значка уведомления. Если этот элемент имеет значение 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, определив соответствующий номер версии (см. раздел "Оболочка" и "Общие версии элементов управления"). Однако это может привести к проблемам, если приложению также требуется работать в более поздних системах.

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

    Это также происходит в случае параллельной установки. При параллельной установке новые версии приложения должны обновить GUID двоичного файла.

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

Примечание

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

Требования

   
Минимальная версия клиента Windows XP [только классические приложения]
Минимальная версия сервера Windows 2000 Server [только классические приложения]
Верхняя часть shellapi.h

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

Уведомления и область уведомлений