Estrutura NOTIFYICONDATAA (shellapi.h)

Contém informações de que o sistema precisa exibir notificações na área de notificação. Usado por Shell_NotifyIcon.

Sintaxe

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;

Membros

cbSize

Tipo: DWORD

O tamanho dessa estrutura, em bytes.

hWnd

Digite: HWND

Um identificador para a janela que recebe notificações associadas a um ícone na área de notificação.

uID

Tipo: UINT

O identificador definido pelo aplicativo do ícone da barra de tarefas. O Shell usa (hWnd mais uID) ou guidItem para identificar em qual ícone operar quando Shell_NotifyIcon é invocado. Você pode ter vários ícones associados a um único hWnd atribuindo a cada um um uID diferente. Se guidItem for especificado, uID será ignorado.

uFlags

Tipo: UINT

Sinalizadores que indicam quais dos outros membros da estrutura contêm dados válidos ou fornecem informações adicionais à dica de ferramenta sobre como ela deve ser exibida. Esse membro pode ser uma combinação dos seguintes valores:

NIF_MESSAGE (0x00000001)

0x00000001. O membro uCallbackMessage é válido.

NIF_ICON (0x00000002)

0x00000002. O membro hIcon é válido.

NIF_TIP (0x00000004)

0x00000004. O membro szTip é válido.

NIF_STATE (0x00000008)

0x00000008. Os membros dwState e dwStateMask são válidos.

NIF_INFO (0x00000010)

0x00000010. Exibir uma notificação de balão. Os membros szInfo, szInfoTitle, dwInfoFlags e uTimeout são válidos. Observe que uTimeout é válido somente no Windows 2000 e no Windows XP.

• Para exibir a notificação de balão, especifique NIF_INFO e forneça texto em szInfo.
• Para remover uma notificação de balão, especifique NIF_INFO e forneça uma cadeia de caracteres vazia por meio de szInfo.
• Para adicionar um ícone de área de notificação sem exibir uma notificação, não defina o sinalizador NIF_INFO.

NIF_GUID (0x00000020)

0x00000020.

• Windows 7 e posterior: o guidItem é válido.
• Windows Vista e anteriores: Reservado.

NIF_REALTIME (0x00000040)

0x00000040. Windows Vista e posteriores. Se a notificação de balão não puder ser exibida imediatamente, descarte-a. Use esse sinalizador para notificações que representam informações em tempo real que seriam insignificantes ou enganosas se exibidas posteriormente. Por exemplo, uma mensagem informando "Seu telefone está tocando". NIF_REALTIME é significativo somente quando combinado com o sinalizador NIF_INFO.

NIF_SHOWTIP (0x00000080)

0x00000080. Windows Vista e posteriores. Use a dica de ferramenta padrão. Normalmente, quando uVersion é definido como NOTIFYICON_VERSION_4, a dica de ferramenta padrão é suprimida e pode ser substituída pela interface do usuário pop-up desenhada pelo aplicativo. Se o aplicativo quiser mostrar a dica de ferramenta padrão com NOTIFYICON_VERSION_4, ele poderá especificar NIF_SHOWTIP para indicar que a dica de ferramenta padrão ainda deve ser mostrada.

uCallbackMessage

Tipo: UINT

Um identificador de mensagem definido pelo aplicativo. O sistema usa esse identificador para enviar mensagens de notificação para a janela identificada em hWnd. Essas mensagens de notificação são enviadas quando um evento ou foco do mouse ocorre no retângulo delimitador do ícone, quando o ícone é selecionado ou ativado com o teclado ou quando essas ações ocorrem na notificação de balão.

Quando o membro uVersion é 0 ou NOTIFYICON_VERSION, o parâmetro wParam da mensagem contém o identificador do ícone da barra de tarefas no qual o evento ocorreu. Esse identificador pode ter 32 bits de comprimento. O parâmetro lParam contém a mensagem de mouse ou teclado associada ao evento. Por exemplo, quando o ponteiro se move sobre um ícone de barra de tarefas, lParam é definido como WM_MOUSEMOVE.

Quando o membro uVersion é NOTIFYICON_VERSION_4, os aplicativos continuam recebendo eventos de notificação na forma de mensagens definidas pelo aplicativo por meio do membro uCallbackMessage , mas a interpretação dos parâmetros lParam e wParam dessa mensagem é alterada da seguinte maneira:

• LOWORD(lParam) contém eventos de notificação, como NIN_BALLOONSHOW, NIN_POPUPOPEN ou WM_CONTEXTMENU.
• HIWORD(lParam) contém a ID do ícone. As IDs de ícone são restritas a um comprimento de 16 bits.
• GET_X_LPARAM(wParam) retorna a coordenada de âncora X para eventos de notificação NIN_POPUPOPEN, NIN_SELECT, NIN_KEYSELECT e todas as mensagens do mouse entre WM_MOUSEFIRST e WM_MOUSELAST. Se qualquer uma dessas mensagens for gerada pelo teclado, wParam será definido como o canto superior esquerdo do ícone de destino. Para todas as outras mensagens, wParam é indefinido.
• GET_Y_LPARAM(wParam) retorna a coordenada de âncora Y para eventos de notificação e mensagens, conforme definido para a âncora X.

hIcon

Tipo: HICON

Um identificador para o ícone a ser adicionado, modificado ou excluído. O Windows XP e posteriores dão suporte a ícones de até 32 BPP.

Se apenas um ícone de 16 x 16 pixels for fornecido, ele será dimensionado para um tamanho maior em um sistema definido como um valor dpi alto. Isso pode levar a um resultado pouco atraente. É recomendável que você forneça um ícone de 16 x 16 pixels e um ícone 32x32 no arquivo de recurso. Use LoadIconMetric para garantir que o ícone correto seja carregado e dimensionado adequadamente. Consulte Comentários para obter um exemplo de código.

szTip[64]

Tipo: TCHAR[64]

Uma cadeia de caracteres terminada em nulo que especifica o texto para uma dica de ferramenta padrão. Ele pode ter no máximo 64 caracteres, incluindo o caractere nulo de terminação.

Para o Windows 2000 e posterior, szTip pode ter no máximo 128 caracteres, incluindo o caractere nulo de terminação.

szTip[128]

Tipo: TCHAR[64]

Uma cadeia de caracteres terminada em nulo que especifica o texto para uma dica de ferramenta padrão. Ele pode ter no máximo 64 caracteres, incluindo o caractere nulo de terminação.

Para o Windows 2000 e posterior, szTip pode ter no máximo 128 caracteres, incluindo o caractere nulo de terminação.

dwState

Tipo: DWORD

Windows 2000 e posterior. O estado do ícone. Um ou ambos os seguintes valores:

NIS_HIDDEN (0x00000001)

0x00000001. O ícone está oculto.

NIS_SHAREDICON (0x00000002)

0x00000002. O recurso de ícone é compartilhado entre vários ícones.

dwStateMask

Tipo: DWORD

Windows 2000 e posterior. Um valor que especifica quais bits do membro dwState são recuperados ou modificados. Os valores possíveis são os mesmos para dwState. Por exemplo, definir esse membro como NIS_HIDDEN faz com que apenas o estado oculto do item seja modificado enquanto o bit de compartilhamento de ícone é ignorado, independentemente de seu valor.

szInfo[256]

Tipo: TCHAR[256]

Windows 2000 e posterior. Uma cadeia de caracteres terminada em nulo que especifica o texto a ser exibido em uma notificação de balão. Ele pode ter no máximo 256 caracteres, incluindo o caractere nulo de terminação, mas deve ser restrito a 200 caracteres em inglês para acomodar a localização. Para remover a notificação de balão da interface do usuário, exclua o ícone (com NIM_DELETE) ou defina o sinalizador NIF_INFO em uFlags e defina szInfo como uma cadeia de caracteres vazia.

DUMMYUNIONNAME

DUMMYUNIONNAME.uTimeout

Tipo: UINT

Windows 2000 e posterior.

União com uVersion. O valor de tempo limite, em milissegundos, para notificação. O sistema impõe valores mínimos e máximos de tempo limite. Os valores especificados em uTimeout que são muito grandes são definidos como o valor máximo. Valores que são muito pequenos padrão para o valor mínimo. Atualmente, os valores de tempo limite mínimo e máximo do sistema são definidos em 10 segundos e 30 segundos, respectivamente. Consulte Comentários para obter mais discussões sobre uTimeout.

DUMMYUNIONNAME.uVersion

Tipo: UINT

Windows 2000 e posterior. União com uTimeout (preterido a partir do Windows Vista). Especifica qual versão da interface de ícone de notificação do Shell deve ser usada. Para obter mais informações sobre as diferenças nessas versões, consulte Shell_NotifyIcon. Esse membro é empregado somente ao usar Shell_NotifyIcon para enviar uma mensagem NIM_SETVERSION .

szInfoTitle[64]

Tipo: TCHAR[64]

Windows 2000 e posterior. Uma cadeia de caracteres terminada em nulo que especifica um título para uma notificação de balão. Esse título aparece em uma fonte maior imediatamente acima do texto. Ele pode ter no máximo 64 caracteres, incluindo o caractere nulo de terminação, mas deve ser restrito a 48 caracteres em inglês para acomodar a localização.

dwInfoFlags

Tipo: DWORD

Windows 2000 e posterior. Sinalizadores que podem ser definidos para modificar o comportamento e a aparência de uma notificação de balão. O ícone é colocado à esquerda do título. Se o membro szInfoTitle for de comprimento zero, o ícone não será mostrado.

NIIF_NONE (0x00000000)

0x00000000. Nenhum ícone.

NIIF_INFO (0x00000001)

0x00000001. Um ícone de informações.

NIIF_WARNING (0x00000002)

0x00000002. Um ícone de aviso.

NIIF_ERROR (0x00000003)

0x00000003. Um ícone de erro.

NIIF_USER (0x00000004)

0x00000004. Windows XP SP2 e posterior.

• Windows XP: use o ícone identificado no hIcon como o ícone de título do balão de notificação.
• Windows Vista e posterior: use o ícone identificado em hBalloonIcon como o ícone de título do balão de notificação.

NIIF_NOSOUND (0x00000010)

0x00000010. Windows XP e posterior. Não reproduza o som associado. Aplica-se somente a notificações.

NIIF_LARGE_ICON (0x00000020)

0x00000020. Windows Vista e posteriores. A versão grande do ícone deve ser usada como o ícone de notificação. Isso corresponde ao ícone com dimensões SM_CXICON x SM_CYICON. Se esse sinalizador não estiver definido, o ícone com dimensões SM_CXSMICON x SM_CYSMICON será usado.

• Esse sinalizador pode ser usado com todos os ícones de estoque.
• Os aplicativos que usam ícones personalizados mais antigos (NIIF_USER com hIcon) devem fornecer uma nova versão SM_CXICON x SM_CYICON no ícone de bandeja (hIcon). Esses ícones são reduzidos horizontalmente quando são exibidos na Bandeja do Sistema ou na SCA (Área de Controle do Sistema).
• Novos ícones personalizados (NIIF_USER com hBalloonIcon) devem fornecer uma versão SM_CXICON x SM_CYICON no ícone fornecido (hBalloonIcon).

NIIF_RESPECT_QUIET_TIME (0x00000080)

0x00000080. Windows 7 e posterior. Não exiba a notificação de balão se o usuário atual estiver em "tempo de silêncio", que é a primeira hora após um novo usuário fazer logon em sua conta pela primeira vez. Durante esse tempo, a maioria das notificações não deve ser enviada ou mostrada. Isso permite que um usuário se acostume com um novo sistema de computador sem essas distrações. O tempo de silêncio também ocorre para cada usuário após uma atualização do sistema operacional ou limpo instalação. Uma notificação enviada com esse sinalizador durante o tempo de silêncio não está na fila; ele é simplesmente ignorado desacompartada. O aplicativo poderá reenviar a notificação posteriormente se ela ainda for válida nesse momento.

Como um aplicativo não pode prever quando pode encontrar um tempo tranquilo, recomendamos que esse sinalizador sempre seja definido em todas as notificações apropriadas por qualquer aplicativo que signifique respeitar o tempo de silêncio.

Durante o tempo de silêncio, determinadas notificações ainda devem ser enviadas porque são esperadas pelo usuário como comentários em resposta a uma ação do usuário, por exemplo, quando ele conecta um dispositivo USB ou imprime um documento.

Se o usuário atual não estiver em tempo de silêncio, esse sinalizador não terá efeito.

NIIF_ICON_MASK (0x0000000F)

0x0000000F. Windows XP e posterior. Reservado.

guidItem

Tipo: GUID

Windows XP e posterior.

• Windows 7 e posterior: um GUID registrado que identifica o ícone. Esse valor substitui uID e é o método recomendado para identificar o ícone. O sinalizador NIF_GUID deve ser definido no membro uFlags .
• Windows XP e Windows Vista: Reservado; deve ser definido como 0.

Se o aplicativo pretende ser executado no Windows Vista e no Windows 7, é imperativo que você marcar a versão do Windows e especifique apenas um guidItem diferente de zero se estiver no Windows 7 ou posterior.

Se você identificar o ícone de notificação com um GUID em uma chamada para Shell_NotifyIcon, deverá usar esse mesmo GUID para identificar o ícone em qualquer Shell_NotifyIcon chamadas subsequentes que lidam com esse mesmo ícone.

Para gerar um GUID para uso neste membro, use uma ferramenta geradora de GUID, como Guidgen.exe.

hBalloonIcon

Tipo: HICON

Windows Vista e posteriores. O identificador de um ícone de notificação personalizado fornecido pelo aplicativo que deve ser usado independentemente do ícone da área de notificação. Se esse membro não for NULL e o sinalizador NIIF_USER for definido no membro dwInfoFlags , esse ícone será usado como o ícone de notificação. Se esse membro for NULL, o comportamento herdado será realizado.

Comentários

Confira "Notificações" nas Diretrizes de Interação da Experiência do Usuário do Windows para obter mais informações sobre as práticas recomendadas de interface do usuário de notificação e conteúdo.

Se você definir o sinalizador NIF_INFO no membro uFlags , a notificação no estilo balão será usada. Para obter mais discussões sobre essas notificações, consulte Dicas de ferramentas de balão.

Não é possível exibir mais de uma notificação de balão por vez para a barra de tarefas. Se um aplicativo tentar exibir uma notificação quando uma já estiver sendo exibida, a nova notificação será enfileirada e exibida quando a notificação mais antiga desaparecer. Em versões do Windows antes do Windows Vista, a nova notificação não seria exibida até que a notificação existente estivesse visível pelo menos pelo tempo limite mínimo do sistema, independentemente do valor uTimeout da notificação original. Se o usuário não parece estar usando o computador, o sistema não conta esse tempo para o tempo limite.

Há suporte para vários membros dessa estrutura apenas no Windows 2000 e posterior. Para habilitar esses membros, inclua uma das seguintes linhas no cabeçalho:

// 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

Observe que você deve inicializar a estrutura com seu tamanho. Se você usar o tamanho da estrutura definida no momento, o aplicativo poderá não ser executado com versões anteriores do Shell32.dll, que esperam uma estrutura menor. Você pode executar seu aplicativo em versões anteriores do Shell32.dll definindo o número de versão apropriado (consulte Shell e Common Controls Versions). No entanto, isso poderá causar problemas se o aplicativo também precisar ser executado em sistemas mais recentes.

Você pode manter a compatibilidade do aplicativo com todas as versões Shell32.dll enquanto ainda usa os arquivos de cabeçalho atuais definindo o tamanho da estrutura NOTIFYICONDATA adequadamente. Antes de inicializar a estrutura, use DllGetVersion para determinar qual versão Shell32.dll está instalada no sistema e inicialize cbSize com um destes valores:

versão do Shell32.dll	cbSize
6.0.6 ou superior (Windows Vista e posterior)	sizeof(NOTIFYICONDATA)
6.0 (Windows XP)	NOTIFYICONDATA_V3_SIZE
5.0 (Windows 2000)	NOTIFYICONDATA_V2_SIZE
Versões inferiores à 5.0	NOTIFYICONDATA_V1_SIZE

 

Usar esse valor para cbSize permite que seu aplicativo use NOTIFYICONDATA em um método compatível com versões anteriores do Shell32.dll.

O exemplo de código a seguir mostra a verificação de versão que pode habilitar um aplicativo que usa o membro guidItem para ser executado no Windows Vista e no Windows 7. Ele fornece uma função booliana que retorna TRUE se o sistema operacional for o Windows 7. A menos que esse membro retorne TRUE, o membro guidItem deve ser definido como 0.

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);
}

O exemplo de código a seguir mostra o uso de LoadIconMetric para carregar um ícone para uso com DPI alto.

// 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;

Solucionando problemas

Se você estiver usando o membro guidItem para identificar o ícone e esse ícone não for visto ou algumas chamadas para Shell_NotifyIcon falharem, um dos seguintes casos será a causa provável:

1. O sinalizador NIF_GUID não foi definido em todas as chamadas para Shell_NotifyIcon. Depois de identificar o ícone de notificação com um GUID em uma chamada para Shell_NotifyIcon, você deve usar esse mesmo GUID para identificar o ícone em qualquer Shell_NotifyIcon chamadas subsequentes que lidam com esse mesmo ícone.
2. O arquivo binário que contém o ícone foi movido. O caminho do arquivo binário está incluído no registro do GUID do ícone e não pode ser alterado. As configurações associadas ao ícone serão preservadas por meio de uma atualização somente se o caminho do arquivo e o GUID não forem alterados. Se o caminho precisar ser alterado, o aplicativo deverá remover todas as informações de GUID que foram adicionadas quando o ícone existente foi registrado. Depois que essas informações forem removidas, você poderá mover o arquivo binário para um novo local e registrá-lo novamente com um novo GUID. Todas as configurações associadas ao registro guid original serão perdidas.

   Isso também ocorre no caso de uma instalação lado a lado. Ao lidar com uma instalação lado a lado, novas versões do aplicativo devem atualizar o GUID do arquivo binário.

   Nota A única exceção a um arquivo movido ocorre quando os arquivos binários originais e movidos são assinados por Authenticode pela mesma empresa. Nesse caso, as configurações são preservadas por meio da movimentação.
    

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Cabeçalho	shellapi.h

Confira também

Notificações e a área de notificação