Estructura NOTIFYICONDATAW (shellapi.h)

Contiene información que el sistema necesita para mostrar las notificaciones en el área de notificación. Usado por Shell_NotifyIcon.

Sintaxis

typedef struct _NOTIFYICONDATAW {
  DWORD cbSize;
  HWND  hWnd;
  UINT  uID;
  UINT  uFlags;
  UINT  uCallbackMessage;
  HICON hIcon;
#if ...
  WCHAR szTip[64];
#else
  WCHAR szTip[128];
#endif
  DWORD dwState;
  DWORD dwStateMask;
  WCHAR szInfo[256];
  union {
    UINT uTimeout;
    UINT uVersion;
  } DUMMYUNIONNAME;
  WCHAR szInfoTitle[64];
  DWORD dwInfoFlags;
  GUID  guidItem;
  HICON hBalloonIcon;
} NOTIFYICONDATAW, *PNOTIFYICONDATAW;

Miembros

cbSize

Tipo: DWORD

Tamaño de esta estructura, en bytes.

hWnd

Tipo: HWND

Identificador de la ventana que recibe notificaciones asociadas a un icono en el área de notificación.

uID

Tipo: UINT

Identificador definido por la aplicación del icono de la barra de tareas. El Shell usa (hWnd más uID) o guidItem para identificar en qué icono operar cuando se invoca Shell_NotifyIcon . Puede tener varios iconos asociados a un único hWnd asignando cada uno un uID diferente. Si se especifica guidItem , se omite uID .

uFlags

Tipo: UINT

Marcas que indican cuáles de los demás miembros de la estructura contienen datos válidos o proporcionan información adicional a la información sobre herramientas sobre cómo se debe mostrar. Este miembro puede ser una combinación de los valores siguientes:

NIF_MESSAGE (0x00000001)

0x00000001. El miembro uCallbackMessage es válido.

NIF_ICON (0x00000002)

0x00000002. El miembro hIcon es válido.

NIF_TIP (0x00000004)

0x00000004. El miembro szTip es válido.

NIF_STATE (0x00000008)

0x00000008. Los miembros dwState y dwStateMask son válidos.

NIF_INFO (0x00000010)

0x00000010. Muestra una notificación de globo. Los miembros szInfo, szInfoTitle, dwInfoFlags y uTimeout son válidos. Tenga en cuenta que uTimeout solo es válido en Windows 2000 y Windows XP.

• Para mostrar la notificación de globo, especifique NIF_INFO y proporcione texto en szInfo.
• Para quitar una notificación de globo, especifique NIF_INFO y proporcione una cadena vacía a través de szInfo.
• Para agregar un icono de área de notificación sin mostrar una notificación, no establezca la marca NIF_INFO.

NIF_GUID (0x00000020)

0x00000020.

• Windows 7 y versiones posteriores: guidItem es válido.
• Windows Vista y versiones anteriores: Reservado.

NIF_REALTIME (0x00000040)

0x00000040. Windows Vista y versiones posteriores. Si la notificación de globo no se puede mostrar inmediatamente, deséchela. Use esta marca para las notificaciones que representan información en tiempo real que sería insignificante o engañosa si se muestra en un momento posterior. Por ejemplo, un mensaje que indica "Su teléfono está llamando". NIF_REALTIME solo es significativo cuando se combina con la marca NIF_INFO.

NIF_SHOWTIP (0x00000080)

0x00000080. Windows Vista y versiones posteriores. Use la información sobre herramientas estándar. Normalmente, cuando uVersion se establece en NOTIFYICON_VERSION_4, se suprime la información sobre herramientas estándar y se puede reemplazar por la interfaz de usuario emergente dibujada por la aplicación. Si la aplicación quiere mostrar la información sobre herramientas estándar con NOTIFYICON_VERSION_4, puede especificar NIF_SHOWTIP para indicar que se debe mostrar la información sobre herramientas estándar.

uCallbackMessage

Tipo: UINT

Identificador de mensaje definido por la aplicación. El sistema usa este identificador para enviar mensajes de notificación a la ventana identificada en hWnd. Estos mensajes de notificación se envían cuando se produce un evento del mouse o el puntero en el rectángulo delimitador del icono, cuando el icono está seleccionado o activado con el teclado, o cuando esas acciones se producen en la notificación de globo.

Cuando el miembro uVersion es 0 o NOTIFYICON_VERSION, el parámetro wParam del mensaje contiene el identificador del icono de la barra de tareas en el que se produjo el evento. Este identificador puede tener una longitud de 32 bits. El parámetro lParam contiene el mensaje del mouse o del teclado asociado al evento . Por ejemplo, cuando el puntero se mueve sobre un icono de barra de tareas, lParam se establece en WM_MOUSEMOVE.

Cuando el miembro uVersion es NOTIFYICON_VERSION_4, las aplicaciones siguen recibiendo eventos de notificación en forma de mensajes definidos por la aplicación a través del miembro uCallbackMessage , pero la interpretación de los parámetros lParam y wParam de ese mensaje se cambia de la siguiente manera:

• LOWORD(lParam) contiene eventos de notificación, como NIN_BALLOONSHOW, NIN_POPUPOPEN o WM_CONTEXTMENU.
• HIWORD(lParam) contiene el identificador del icono. Los identificadores de icono están restringidos a una longitud de 16 bits.
• GET_X_LPARAM(wParam) devuelve la coordenada de anclaje X para los eventos de notificación NIN_POPUPOPEN, NIN_SELECT, NIN_KEYSELECT y todos los mensajes del mouse entre WM_MOUSEFIRST y WM_MOUSELAST. Si el teclado genera alguno de esos mensajes, wParam se establece en la esquina superior izquierda del icono de destino. Para todos los demás mensajes, wParam no está definido.
• GET_Y_LPARAM(wParam) devuelve la coordenada de delimitador Y para los mensajes y eventos de notificación según se define para el delimitador X.

hIcon

Tipo: HICON

Identificador del icono que se va a agregar, modificar o eliminar. Windows XP y versiones posteriores admiten iconos de hasta 32 BPP.

Si solo se proporciona un icono de 16 x 16 píxeles, se escala a un tamaño mayor en un sistema establecido en un valor de ppp alto. Esto puede dar lugar a un resultado no atractivo. Se recomienda proporcionar un icono de 16 x 16 píxeles y un icono de 32 x 32 en el archivo de recursos. Use LoadIconMetric para asegurarse de que el icono correcto está cargado y escalado correctamente. Vea Comentarios para obtener un ejemplo de código.

szTip[64]

Tipo: TCHAR[64]

Cadena terminada en null que especifica el texto de una información sobre herramientas estándar. Puede tener un máximo de 64 caracteres, incluido el carácter nulo de terminación.

Para Windows 2000 y versiones posteriores, szTip puede tener un máximo de 128 caracteres, incluido el carácter nulo de terminación.

szTip[128]

Tipo: TCHAR[64]

Cadena terminada en null que especifica el texto de una información sobre herramientas estándar. Puede tener un máximo de 64 caracteres, incluido el carácter nulo de terminación.

Para Windows 2000 y versiones posteriores, szTip puede tener un máximo de 128 caracteres, incluido el carácter nulo de terminación.

dwState

Tipo: DWORD

Windows 2000 y versiones posteriores. Estado del icono. Uno o ambos de los siguientes valores:

NIS_HIDDEN (0x00000001)

0x00000001. El icono está oculto.

NIS_SHAREDICON (0x00000002)

0x00000002. El recurso icon se comparte entre varios iconos.

dwStateMask

Tipo: DWORD

Windows 2000 y versiones posteriores. Valor que especifica qué bits del miembro dwState se recuperan o modifican. Los valores posibles son los mismos que los de dwState. Por ejemplo, establecer este miembro en NIS_HIDDEN hace que solo se modifique el estado oculto del elemento mientras el bit de uso compartido de iconos se omite independientemente de su valor.

szInfo[256]

Tipo: TCHAR[256]

Windows 2000 y versiones posteriores. Cadena terminada en null que especifica el texto que se va a mostrar en una notificación de globo. Puede tener un máximo de 256 caracteres, incluido el carácter nulo de terminación, pero debe estar restringido a 200 caracteres en inglés para dar cabida a la localización. Para quitar la notificación de globo de la interfaz de usuario, elimine el icono (con NIM_DELETE) o establezca la marca de NIF_INFO en uFlags y establezca szInfo en una cadena vacía.

DUMMYUNIONNAME

DUMMYUNIONNAME.uTimeout

Tipo: UINT

Windows 2000 y versiones posteriores.

Unión con uVersion. Valor de tiempo de espera, en milisegundos, para la notificación. El sistema aplica los valores de tiempo de espera mínimo y máximo. Los valores especificados en uTimeout que son demasiado grandes se establecen en el valor máximo. Los valores que son demasiado pequeños tienen como valor mínimo. Los valores de tiempo de espera mínimo y máximo del sistema se establecen actualmente en 10 segundos y 30 segundos, respectivamente. Vea Comentarios para obtener más información sobre uTimeout.

DUMMYUNIONNAME.uVersion

Tipo: UINT

Windows 2000 y versiones posteriores. Unión con uTimeout (en desuso a partir de Windows Vista). Especifica la versión de la interfaz del icono de notificación de Shell que se debe usar. Para obtener más información sobre las diferencias en estas versiones, consulte Shell_NotifyIcon. Este miembro solo se emplea cuando se usa Shell_NotifyIcon para enviar un mensaje de NIM_SETVERSION .

szInfoTitle[64]

Tipo: TCHAR[64]

Windows 2000 y versiones posteriores. Cadena terminada en null que especifica un título para una notificación de globo. Este título aparece en una fuente más grande justo encima del texto. Puede tener un máximo de 64 caracteres, incluido el carácter nulo de terminación, pero debe restringirse a 48 caracteres en inglés para dar cabida a la localización.

dwInfoFlags

Tipo: DWORD

Windows 2000 y versiones posteriores. Marcas que se pueden establecer para modificar el comportamiento y la apariencia de una notificación de globo. El icono se coloca a la izquierda del título. Si el miembro szInfoTitle es de longitud cero, no se muestra el icono.

NIIF_NONE (0x00000000)

0x00000000. Sin icono.

NIIF_INFO (0x00000001)

0x00000001. Un icono de información.

NIIF_WARNING (0x00000002)

0x00000002. Un icono de advertencia.

NIIF_ERROR (0x00000003)

0x00000003. Un icono de error.

NIIF_USER (0x00000004)

0x00000004. Windows XP SP2 y versiones posteriores.

• Windows XP: use el icono identificado en hIcon como icono de título del globo de notificación.
• Windows Vista y versiones posteriores: use el icono identificado en hBalloonIcon como icono de título del globo de notificación.

NIIF_NOSOUND (0x00000010)

0x00000010. Windows XP y versiones posteriores. No reproduzca el sonido asociado. Solo se aplica a las notificaciones.

NIIF_LARGE_ICON (0x00000020)

0x00000020. Windows Vista y versiones posteriores. La versión grande del icono debe usarse como icono de notificación. Esto corresponde al icono con dimensiones SM_CXICON x SM_CYICON. Si no se establece esta marca, se usa el icono con dimensiones SM_CXSMICON x SM_CYSMICON.

• Esta marca se puede usar con todos los iconos de stock.
• Las aplicaciones que usan iconos personalizados más antiguos (NIIF_USER con hIcon) deben proporcionar una nueva versión de SM_CXICON x SM_CYICON en el icono de bandeja (hIcon). Estos iconos se reducen verticalmente cuando se muestran en la bandeja del sistema o en el área de control del sistema (SCA).
• Los nuevos iconos personalizados (NIIF_USER con hBalloonIcon) deben proporcionar una versión de SM_CXICON x SM_CYICON en el icono proporcionado (hBalloonIcon).

NIIF_RESPECT_QUIET_TIME (0x00000080)

0x00000080. Windows 7 y versiones posteriores. No muestre la notificación de globo si el usuario actual está en "tiempo tranquilo", que es la primera hora después de que un nuevo usuario inicie sesión en su cuenta por primera vez. Durante este tiempo, la mayoría de las notificaciones no se deben enviar ni mostrar. Esto permite que un usuario esté acostumbrado a un nuevo sistema informático sin esas distracciones. El tiempo de silencio también se produce para cada usuario después de una actualización del sistema operativo o una instalación limpia. No se pone en cola una notificación enviada con esta marca durante el tiempo de silencio; simplemente se descarta sin mostrar. La aplicación puede volver a enviar la notificación más adelante si sigue siendo válida en ese momento.

Dado que una aplicación no puede predecir cuándo podría encontrarse con un tiempo de silencio, se recomienda establecer siempre esta marca en todas las notificaciones adecuadas por cualquier aplicación que signifique respetar el tiempo de silencio.

Durante el tiempo de silencio, ciertas notificaciones deben seguir siendo enviadas porque el usuario las espera como comentarios en respuesta a una acción del usuario, por ejemplo, cuando conecta un dispositivo USB o imprime un documento.

Si el usuario actual no está en tiempo silencioso, esta marca no tiene ningún efecto.

NIIF_ICON_MASK (0x0000000F)

0x0000000F. Windows XP y versiones posteriores. Reservado.

guidItem

Tipo: GUID

Windows XP y versiones posteriores.

• Windows 7 y versiones posteriores: GUID registrado que identifica el icono. Este valor invalida uID y es el método recomendado para identificar el icono. La marca NIF_GUID debe establecerse en el miembro uFlags .
• Windows XP y Windows Vista: Reservado; debe establecerse en 0.

Si la aplicación está pensada para ejecutarse en Windows Vista y Windows 7, es imperativo comprobar la versión de Windows y especificar solo un guidItem distinto de cero si en Windows 7 o posterior.

Si identifica el icono de notificación con un GUID en una llamada a Shell_NotifyIcon, debe usar ese mismo GUID para identificar el icono en las llamadas de Shell_NotifyIcon posteriores que tratan con ese mismo icono.

Para generar un GUID para su uso en este miembro, use una herramienta de generación de GUID como Guidgen.exe.

hBalloonIcon

Tipo: HICON

Windows Vista y versiones posteriores. Identificador de un icono de notificación personalizado proporcionado por la aplicación que se debe usar independientemente del icono del área de notificación. Si este miembro no es NULL y la marca de NIIF_USER se establece en el miembro dwInfoFlags , este icono se usa como icono de notificación. Si este miembro es NULL, se lleva a cabo el comportamiento heredado.

Comentarios

Consulta Notificaciones en las Directrices de interacción de la experiencia del usuario de Windows para obtener más información sobre la interfaz de usuario de notificación y los procedimientos recomendados de contenido.

Si establece la marca NIF_INFO en el miembro uFlags , se usa la notificación de estilo globo. Para obtener más información sobre estas notificaciones, consulte Información sobre herramientas de globo.

No se puede mostrar más de una notificación de globo a la vez para la barra de tareas. Si una aplicación intenta mostrar una notificación cuando ya se muestra una, la nueva notificación se pone en cola y se muestra cuando desaparece la notificación anterior. En las versiones de Windows anteriores a Windows Vista, la nueva notificación no aparecería hasta que la notificación existente haya sido visible durante al menos el tiempo de espera mínimo del sistema, independientemente del valor uTimeout de la notificación original. Si el usuario no parece usar el equipo, el sistema no cuenta este tiempo para el tiempo de espera.

Varios miembros de esta estructura solo se admiten para Windows 2000 y versiones posteriores. Para habilitar estos miembros, incluya una de las siguientes líneas en el encabezado:

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

Tenga en cuenta que debe inicializar la estructura con su tamaño. Si usa el tamaño de la estructura definida actualmente, es posible que la aplicación no se ejecute con versiones anteriores de Shell32.dll, que esperan una estructura más pequeña. Puede ejecutar la aplicación en versiones anteriores de Shell32.dll definiendo el número de versión adecuado (consulte Shell y Versiones de controles comunes). Sin embargo, esto puede causar problemas si la aplicación también necesita ejecutarse en sistemas más recientes.

Puede mantener la compatibilidad de aplicaciones con todas las versiones de Shell32.dll mientras sigue usando los archivos de encabezado actuales estableciendo el tamaño de la estructura NOTIFYICONDATA de forma adecuada. Antes de inicializar la estructura, use DllGetVersion para determinar qué versión de Shell32.dll está instalada en el sistema e inicializar cbSize con uno de estos valores:

versión de Shell32.dll	cbSize
6.0.6 o posterior (Windows Vista y versiones posteriores)	sizeof(NOTIFYICONDATA)
6.0 (Windows XP)	NOTIFYICONDATA_V3_SIZE
5.0 (Windows 2000)	NOTIFYICONDATA_V2_SIZE
Versiones inferiores a la 5.0	NOTIFYICONDATA_V1_SIZE

 

El uso de este valor para cbSize permite a la aplicación usar NOTIFYICONDATA en un método compatible con versiones anteriores de Shell32.dll.

En el ejemplo de código siguiente se muestra la comprobación de versiones que puede habilitar una aplicación que usa el miembro guidItem para ejecutarse en Windows Vista y Windows 7. Proporciona una función booleana que devuelve TRUE si el sistema operativo es Windows 7. A menos que este miembro devuelva TRUE, el miembro guidItem debe establecerse en 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);
}

En el ejemplo de código siguiente se muestra el uso de LoadIconMetric para cargar un icono para su uso con valores altos de PPP.

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

Solución de problemas

Si usa el miembro guidItem para identificar el icono y ese icono no se ve o se produce un error en algunas llamadas a Shell_NotifyIcon , es probable que uno de los siguientes casos sea la causa:

1. La marca NIF_GUID no se estableció en todas las llamadas a Shell_NotifyIcon. Una vez que identifique el icono de notificación con un GUID en una llamada a Shell_NotifyIcon, debe usar ese mismo GUID para identificar el icono en las llamadas de Shell_NotifyIcon posteriores que tratan con ese mismo icono.
2. El archivo binario que contiene el icono se movió. La ruta de acceso del archivo binario se incluye en el registro del GUID del icono y no se puede cambiar. La configuración asociada al icono se conserva a través de una actualización solo si la ruta de acceso del archivo y el GUID no cambian. Si se debe cambiar la ruta de acceso, la aplicación debe quitar cualquier información GUID que se agregó cuando se registró el icono existente. Una vez quitada esa información, puede mover el archivo binario a una nueva ubicación y volver a registrarla con un nuevo GUID. Se perderá cualquier configuración asociada al registro guid original.

   Esto también ocurre en el caso de una instalación en paralelo. Cuando se trabaja con una instalación en paralelo, las nuevas versiones de la aplicación deben actualizar el GUID del archivo binario.

   Nota La única excepción a un archivo movido se produce cuando los archivos binarios originales y movidos son Authenticode firmados por la misma empresa. En ese caso, la configuración se conserva a través del movimiento.
    

Requisitos

Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Encabezado	shellapi.h

Consulte también

Notificaciones y el área de notificación