STRUCTURE NOTIFYICONDATAA (shellapi.h)

Contient des informations que le système doit afficher les notifications dans la zone de notification. Utilisé par Shell_NotifyIcon.

Syntaxe

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;

Membres

cbSize

Type : DWORD

Taille de cette structure, en octets.

hWnd

Type : HWND

Handle vers la fenêtre qui reçoit des notifications associées à une icône dans la zone de notification.

uID

Type : UINT

Identificateur défini par l’application de l’icône de la barre des tâches. L’interpréteur de commandes utilise (hWnd plus uID) ou guidItem pour identifier l’icône à utiliser lorsque Shell_NotifyIcon est appelée. Vous pouvez avoir plusieurs icônes associées à un seul hWnd en affectant chacun un uID différent. Si guidItem est spécifié, uID est ignoré.

uFlags

Type : UINT

Indicateurs qui indiquent quels membres de la structure contiennent des données valides ou fournissent des informations supplémentaires à l’info-bulle sur la façon dont il doit s’afficher. Ce membre peut être une combinaison des valeurs suivantes :

NIF_MESSAGE (0x00000001)

0x00000001. Le membre uCallbackMessage est valide.

NIF_ICON (0x00000002)

0x00000002. Le membre hIcon est valide.

NIF_TIP (0x00000004)

0x00000004. Le membre szTip est valide.

NIF_STATE (0x00000008)

0x00000008. Les membres dwState et dwStateMask sont valides.

NIF_INFO (0x00000010)

0x00000010. Affichez une notification de bulle. Les membres szInfo,szInfoTitle, dwInfoFlags et uTimeout sont valides. Notez que uTimeout est valide uniquement dans Windows 2000 et Windows XP.

  • Pour afficher la notification de bulle, spécifiez NIF_INFO et fournissez du texte dans szInfo.
  • Pour supprimer une notification de bulle, spécifiez NIF_INFO et fournissez une chaîne vide via szInfo.
  • Pour ajouter une icône de zone de notification sans afficher de notification, ne définissez pas l’indicateur NIF_INFO.

NIF_GUID (0x00000020)

0x00000020.

  • Windows 7 et versions ultérieures : GuidItem est valide.
  • Windows Vista et versions antérieures : réservé.

NIF_REALTIME (0x00000040)

0x00000040. Windows Vista et versions ultérieures. Si la notification de bulle ne peut pas être affichée immédiatement, ignorez-la. Utilisez cet indicateur pour les notifications qui représentent des informations en temps réel qui seraient sans signification ou trompeuses s’ils s’affichent ultérieurement. Par exemple, un message indiquant « Votre téléphone sonne ». NIF_REALTIME n’est explicite qu’en cas de combinaison avec l’indicateur NIF_INFO.

NIF_SHOWTIP (0x00000080)

0x00000080. Windows Vista et versions ultérieures. Utilisez l’info-bulle standard. Normalement, lorsque uVersion est défini sur NOTIFYICON_VERSION_4, l’info-bulle standard est supprimée et peut être remplacée par l’interface utilisateur contextuelle dessinée par l’application. Si l’application souhaite afficher l’info-bulle standard avec NOTIFYICON_VERSION_4, elle peut spécifier NIF_SHOWTIP pour indiquer que l’info-bulle standard doit toujours être affichée.

uCallbackMessage

Type : UINT

Identificateur de message défini par l’application. Le système utilise cet identificateur pour envoyer des messages de notification à la fenêtre identifiée dans hWnd. Ces messages de notification sont envoyés lorsqu’un événement de souris ou un pointage se produit dans le rectangle englobant de l’icône, lorsque l’icône est sélectionnée ou activée avec le clavier, ou lorsque ces actions se produisent dans la notification de bulle.

Lorsque le membre uVersion est soit 0 ou NOTIFYICON_VERSION, le paramètre wParam du message contient l’identificateur de l’icône de barre des tâches dans laquelle l’événement s’est produit. Cet identificateur peut être de 32 bits de longueur. Le paramètre lParam contient le message de souris ou de clavier associé à l’événement. Par exemple, lorsque le pointeur se déplace sur une icône de barre des tâches, lParam est défini sur WM_MOUSEMOVE.

Lorsque le membre uVersion est NOTIFYICON_VERSION_4, les applications continuent de recevoir des événements de notification sous la forme de messages définis par l’application via le membre uCallbackMessage, mais l’interprétation des paramètres lParam et wParam de ce message est modifiée comme suit :

  • LOWORD(lParam) contient des événements de notification, tels que NIN_BALLOONSHOW, NIN_POPUPOPEN ou WM_CONTEXTMENU.
  • HIWORD(lParam) contient l’ID d’icône. Les ID d’icône sont limités à une longueur de 16 bits.
  • GET_X_LPARAM(wParam) retourne la coordonnée d’ancrage X pour les événements de notification NIN_POPUPOPEN, NIN_SELECT, NIN_KEYSELECT et tous les messages de souris entre WM_MOUSEFIRST et WM_MOUSELAST. Si l’un de ces messages est généré par le clavier, wParam est défini sur le coin supérieur gauche de l’icône cible. Pour tous les autres messages, wParam n’est pas défini.
  • GET_Y_LPARAM(wParam) retourne la coordonnée d’ancre Y pour les événements de notification et les messages définis pour l’ancre X.

hIcon

Type : HICON

Handle à ajouter, modifier ou supprimer l’icône. Windows XP et versions ultérieures prennent en charge les icônes allant jusqu’à 32 BPP.

Si seule une icône de 16 x 16 pixels est fournie, elle est mise à l’échelle vers une plus grande taille dans un système défini sur une valeur d’pi élevée. Cela peut entraîner un résultat inattractive. Il est recommandé de fournir à la fois une icône de 16 x 16 pixels et une icône 32x32 dans votre fichier de ressources. Utilisez LoadIconMetric pour vous assurer que l’icône correcte est chargée et mise à l’échelle de manière appropriée. Consultez remarques pour un exemple de code.

szTip[64]

Type : TCHAR[64]

Chaîne terminée par null qui spécifie le texte d’une info-bulle standard. Il peut avoir un maximum de 64 caractères, y compris le caractère null de fin.

Pour Windows 2000 et versions ultérieures, szTip peut avoir un maximum de 128 caractères, y compris le caractère null de fin.

szTip[128]

Type : TCHAR[64]

Chaîne terminée par null qui spécifie le texte d’une info-bulle standard. Il peut avoir un maximum de 64 caractères, y compris le caractère null de fin.

Pour Windows 2000 et versions ultérieures, szTip peut avoir un maximum de 128 caractères, y compris le caractère null de fin.

dwState

Type : DWORD

Windows 2000 et versions ultérieures. État de l’icône. Une ou les deux valeurs suivantes :

NIS_HIDDEN (0x00000001)

0x00000001. L’icône est masquée.

NIS_SHAREDICON (0x00000002)

0x00000002. La ressource d’icône est partagée entre plusieurs icônes.

dwStateMask

Type : DWORD

Windows 2000 et versions ultérieures. Valeur qui spécifie les bits du membre dwState récupérés ou modifiés. Les valeurs possibles sont identiques à celles de dwState. Par exemple, la définition de ce membre sur NIS_HIDDEN entraîne uniquement la modification de l’état masqué de l’élément pendant que le bit de partage d’icônes est ignoré, quelle que soit sa valeur.

szInfo[256]

Type : TCHAR[256]

Windows 2000 et versions ultérieures. Chaîne terminée par null qui spécifie le texte à afficher dans une notification de bulle. Il peut comporter au maximum 256 caractères, y compris le caractère null de fin, mais doit être limité à 200 caractères en anglais pour prendre en charge la localisation. Pour supprimer la notification de bulle de l’interface utilisateur, supprimez l’icône (avec NIM_DELETE) ou définissez l’indicateur NIF_INFO dans uFlags et définissez szInfo sur une chaîne vide.

DUMMYUNIONNAME

DUMMYUNIONNAME.uTimeout

Type : UINT

Windows 2000 et versions ultérieures.

Note Ce membre est déconseillé à partir de Windows Vista. Les heures d’affichage des notifications sont désormais basées sur les paramètres d’accessibilité du système.
 
Union avec uVersion. Valeur de délai d’expiration, en millisecondes, pour la notification. Le système applique les valeurs minimales et maximales de délai d’expiration. Les valeurs spécifiées dans uTimeout trop volumineuses sont définies sur la valeur maximale. Valeurs trop petites par défaut pour la valeur minimale. Les valeurs minimales et maximales du système sont actuellement définies à 10 secondes et 30 secondes, respectivement. Pour plus d’informations sur uTimeout, consultez les remarques pour plus d’informations.

DUMMYUNIONNAME.uVersion

Type : UINT

Windows 2000 et versions ultérieures. Union avec uTimeout (déconseillé à partir de Windows Vista). Spécifie la version de l’interface d’icône de notification Shell à utiliser. Pour plus d’informations sur les différences dans ces versions, consultez Shell_NotifyIcon. Ce membre est utilisé uniquement lors de l’utilisation de Shell_NotifyIcon pour envoyer un message NIM_SETVERSION .

szInfoTitle[64]

Type : TCHAR[64]

Windows 2000 et versions ultérieures. Chaîne terminée par null qui spécifie un titre pour une notification de bulle. Ce titre apparaît dans une police plus grande immédiatement au-dessus du texte. Il peut avoir un maximum de 64 caractères, y compris le caractère null de fin, mais doit être limité à 48 caractères en anglais pour prendre en charge la localisation.

dwInfoFlags

Type : DWORD

Windows 2000 et versions ultérieures. Indicateurs qui peuvent être définis pour modifier le comportement et l’apparence d’une notification de bulle. L’icône est placée à gauche du titre. Si le membre szInfoTitle est de longueur nulle, l’icône n’est pas affichée.

NIIF_NONE (0x00000000)

0x00000000. Pas d'icône.

NIIF_INFO (0x00000001)

0x00000001. Icône d'information.

NIIF_WARNING (0x00000002)

0x00000002. Icône d'avertissement.

NIIF_ERROR (0x00000003)

0x00000003. Icône d’erreur.

NIIF_USER (0x00000004)

0x00000004. Windows XP SP2 et versions ultérieures.

  • Windows XP : Utilisez l’icône identifiée dans hIcon comme icône de titre de la bulle de notification.
  • Windows Vista et versions ultérieures : Utilisez l’icône identifiée dans hBalloonIcon comme icône de titre de la bulle de notification.

NIIF_NOSOUND (0x00000010)

0x00000010. Windows XP et versions ultérieures. Ne pas lire le son associé. S’applique uniquement aux notifications.

NIIF_LARGE_ICON (0x00000020)

0x00000020. Windows Vista et versions ultérieures. La version volumineuse de l’icône doit être utilisée comme icône de notification. Cela correspond à l’icône avec des dimensions SM_CXICON x SM_CYICON. Si cet indicateur n’est pas défini, l’icône avec des dimensions SM_CXSMICON x SM_CYSMICON est utilisée.

  • Cet indicateur peut être utilisé avec toutes les icônes stock.
  • Les applications qui utilisent des icônes personnalisées antérieures (NIIF_USER avec hIcon) doivent fournir une nouvelle version SM_CXICON x SM_CYICON dans l’icône de barre d’état (hIcon). Ces icônes sont mises à l’échelle lorsqu’elles sont affichées dans la zone de contrôle système ou la zone de contrôle système (SCA).
  • Les nouvelles icônes personnalisées (NIIF_USER avec hBalloonIcon) doivent fournir une version SM_CXICON x SM_CYICON dans l’icône fournie (hBalloonIcon).

NIIF_RESPECT_QUIET_TIME (0x00000080)

0x00000080. Windows 7 et versions ultérieures. N’affichez pas la notification de bulle si l’utilisateur actuel est en « temps silencieux », qui est la première heure après qu’un nouvel utilisateur se connecte à son compte pour la première fois. Pendant ce temps, la plupart des notifications ne doivent pas être envoyées ou affichées. Cela permet à un utilisateur de devenir habitué à un nouveau système informatique sans ces distractions. Le temps silencieux se produit également pour chaque utilisateur après une mise à niveau ou une installation propre du système d’exploitation. Une notification envoyée avec cet indicateur pendant le temps silencieux n’est pas mise en file d’attente ; elle est simplement ignorée. L’application peut renvoyer la notification ultérieurement s’il est toujours valide à ce moment-là.

Étant donné qu’une application ne peut pas prédire quand elle peut rencontrer un temps silencieux, nous recommandons que cet indicateur soit toujours défini sur toutes les notifications appropriées par n’importe quelle application qui signifie respecter le temps silencieux.

Pendant le temps silencieux, certaines notifications doivent toujours être envoyées, car elles sont attendues par l’utilisateur comme commentaires en réponse à une action utilisateur, par exemple lorsqu’elle se connecte à un appareil USB ou imprime un document.

Si l’utilisateur actuel n’est pas en temps silencieux, cet indicateur n’a aucun effet.

NIIF_ICON_MASK (0x0000000F)

0x0000000F. Windows XP et versions ultérieures. Réservé.

guidItem

Type : GUID

Windows XP et versions ultérieures.

  • Windows 7 et versions ultérieures : GUID inscrit qui identifie l’icône. Cette valeur remplace uID et est la méthode recommandée d’identification de l’icône. L’indicateur NIF_GUID doit être défini dans le membre uFlags .
  • Windows XP et Windows Vista : réservé ; doit être défini sur 0.
Si votre application est destinée à s’exécuter sur Windows Vista et Windows 7, il est impératif de vérifier la version de Windows et de spécifier uniquement un guidItem non-zéro si sur Windows 7 ou version ultérieure.

Si vous identifiez l’icône de notification avec un GUID dans un appel à Shell_NotifyIcon, vous devez utiliser ce même GUID pour identifier l’icône dans les appels de Shell_NotifyIcon suivants qui traitent cette même icône.

Pour générer un GUID à utiliser dans ce membre, utilisez un outil de génération de GUID tel que Guidgen.exe.

hBalloonIcon

Type : HICON

Windows Vista et versions ultérieures. Handle d’une icône de notification personnalisée fournie par l’application qui doit être utilisée indépendamment de l’icône de zone de notification. Si ce membre n’est pas NULL et que l’indicateur NIIF_USER est défini dans le membre dwInfoFlags , cette icône est utilisée comme icône de notification. Si ce membre est NULL, le comportement hérité est effectué.

Notes

Consultez « Notifications » dans les instructions d’interaction de l’expérience utilisateur Windows pour plus d’informations sur l’interface utilisateur de notification et les meilleures pratiques de contenu.

Si vous définissez l’indicateur NIF_INFO dans le membre uFlags , la notification de style bulle est utilisée. Pour plus d’informations sur ces notifications, consultez info-bulles.

Vous ne pouvez afficher plus d’une notification de bulle à la fois pour la barre des tâches. Si une application tente d’afficher une notification lorsqu’une notification est déjà affichée, la nouvelle notification est mise en file d’attente et affichée lorsque l’ancienne notification est supprimée. Dans les versions de Windows avant Windows Vista, la nouvelle notification n’apparaît pas tant que la notification existante n’est pas visible pour au moins la durée minimale du délai d’expiration du système, quelle que soit la valeur uTimeout de la notification d’origine. Si l’utilisateur ne semble pas utiliser l’ordinateur, le système ne compte pas cette fois vers le délai d’expiration.

Plusieurs membres de cette structure ne sont pris en charge que pour Windows 2000 et versions ultérieures. Pour activer ces membres, incluez l’une des lignes suivantes dans votre en-tête :

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

Notez que vous devez initialiser la structure avec sa taille. Si vous utilisez la taille de la structure actuellement définie, l’application peut ne pas s’exécuter avec les versions antérieures de Shell32.dll, ce qui attend une structure plus petite. Vous pouvez exécuter votre application sur des versions antérieures de Shell32.dll en définissant le numéro de version approprié (voir Versions de shell et de contrôles courants). Toutefois, cela peut entraîner des problèmes si votre application doit également s’exécuter sur des systèmes plus récents.

Vous pouvez maintenir la compatibilité des applications avec toutes les versions Shell32.dll tout en utilisant les fichiers d’en-tête actuels en définissant la taille de la structure NOTIFYICONDATA de manière appropriée. Avant d’initialiser la structure, utilisez DllGetVersion pour déterminer quelle version Shell32.dll est installée sur le système et initialiser cbSize avec l’une de ces valeurs :

version Shell32.dll cbSize
6.0.6 ou version ultérieure (Windows Vista et versions ultérieures) sizeof(NOTIFYICONDATA)
6.0 (Windows XP) NOTIFYICONDATA_V3_SIZE
5.0 (Windows 2000) NOTIFYICONDATA_V2_SIZE
Versions inférieures à 5.0 NOTIFYICONDATA_V1_SIZE
 

L’utilisation de cette valeur pour cbSize permet à votre application d’utiliser NOTIFYICONDATA dans une méthode compatible avec les versions antérieures de Shell32.dll.

L’exemple de code suivant montre la vérification de version qui peut activer une application qui utilise le membre guidItem pour s’exécuter sur Windows Vista et Windows 7. Il fournit une fonction booléenne qui retourne TRUE si le système d’exploitation est Windows 7. Sauf si ce membre retourne TRUE, le membre guidItem doit être défini sur 0.

Note Ce code est spécifique au numéro de version de Windows 7. Il est attendu que les versions futures de Windows et Windows Server prennent également en charge le membre guidItem , et à ce moment-là, ce code doit être mis à jour pour identifier les numéros de version ultérieurs aussi valides.
 
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);
}

L’exemple de code suivant montre l’utilisation de LoadIconMetric pour charger une icône à utiliser avec un DPI élevé.

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

Dépannage

Si vous utilisez le membre guidItem pour identifier l’icône et que cette icône n’est pas vue ou que certaines appels à Shell_NotifyIcon échouent, l’un des cas suivants est la cause probable :
  1. L’indicateur NIF_GUID n’a pas été défini dans chaque appel à Shell_NotifyIcon. Une fois que vous avez identifié l’icône de notification avec un GUID dans un appel à Shell_NotifyIcon, vous devez utiliser ce même GUID pour identifier l’icône dans les appels de Shell_NotifyIcon suivants qui traitent cette même icône.
  2. Fichier binaire qui contient l’icône a été déplacé. Le chemin d’accès du fichier binaire est inclus dans l’inscription du GUID de l’icône et ne peut pas être modifié. Les paramètres associés à l’icône sont conservés par le biais d’une mise à niveau uniquement si le chemin du fichier et le GUID ne sont pas modifiés. Si le chemin d’accès doit être modifié, l’application doit supprimer toutes les informations GUID ajoutées lors de l’inscription de l’icône existante. Une fois ces informations supprimées, vous pouvez déplacer le fichier binaire vers un nouvel emplacement et le réinscrire avec un nouveau GUID. Tous les paramètres associés à l’inscription guid d’origine seront perdus.

    Cela se produit également dans le cas d’une installation côte à côte. Lorsque vous traitez d’une installation côte à côte, les nouvelles versions de l’application doivent mettre à jour le GUID du fichier binaire.

    Note La seule exception à un fichier déplacé se produit lorsque les fichiers binaires d’origine et déplacés sont signés par la même société. Dans ce cas, les paramètres sont conservés via le déplacement.
     

Notes

L’en-tête shellapi.h définit NOTIFYICONDATA comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

   
Client minimal pris en charge Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge Windows 2000 Server [applications de bureau uniquement]
En-tête shellapi.h

Voir aussi

Notifications et zone de notification