learn.microsoft.com Open in urlscan Pro
2600:141b:1c00:2487::3544  Public Scan

Form analysis
3 forms found in the DOM

Name: site-header-search-form-mobile — GET /en-us/search/

<form class="flex-grow-1" method="GET" role="search" id="ms--site-header-search-form-mobile" data-bi-name="site-header-search-form-mobile" name="site-header-search-form-mobile" aria-label="Search" action="/en-us/search/">
  <div class="autocomplete display-block" data-bi-name="autocomplete"><!---->
    <div class="field-body control ">
      <input role="combobox" maxlength="100" aria-autocomplete="list" autocapitalize="off" autocomplete="off" autocorrect="off" spellcheck="false" id="site-header-search-autocomplete-input-mobile"
        data-test-id="site-header-search-autocomplete-input-mobile" class="autocomplete-input input 
						
						width-full" type="search" name="terms" aria-expanded="false" aria-owns="ax-1-listbox" aria-controls="ax-1-listbox" aria-activedescendant="" aria-label="Search" aria-describedby="ms--site-header-search-autocomplete-input-mobile-description"
        placeholder="Search" data-bi-name="site-header-search-autocomplete-input-mobile" pattern=".*">
      <span aria-hidden="true" class="autocomplete-loader loader has-text-primary " hidden=""></span>
      <span hidden="" id="ms--site-header-search-autocomplete-input-mobile-description"> Suggestions will filter as you type </span>
    </div>
    <ul role="listbox" id="ax-1-listbox" data-test-id="site-header-search-autocomplete-input-mobile-listbox" class="autocomplete-suggestions is-vertically-scrollable padding-xxs " aria-label="Suggestions" hidden="">
    </ul>
    <!---->
  </div>
  <!-- mobile safari will not dispatch submit event unless there's a submit button that is not display:none -->
  <button type="submit" class="visually-hidden" tabindex="-1" aria-hidden="true"></button>
  <input name="category" hidden="" value="Reference">
</form>

Name: site-header-search-form — GET /en-us/search/

<form class="flex-grow-1" method="GET" role="search" id="ms--site-header-search-form" data-bi-name="site-header-search-form" name="site-header-search-form" aria-label="Search" action="/en-us/search/">
  <div class="autocomplete display-block" data-bi-name="autocomplete"><!---->
    <div class="field-body control ">
      <input role="combobox" maxlength="100" aria-autocomplete="list" autocapitalize="off" autocomplete="off" autocorrect="off" spellcheck="false" id="site-header-search-autocomplete-input" data-test-id="site-header-search-autocomplete-input" class="autocomplete-input input input-sm
						
						width-full" type="search" name="terms" aria-expanded="false" aria-owns="ax-0-listbox" aria-controls="ax-0-listbox" aria-activedescendant="" aria-label="Search" aria-describedby="ms--site-header-search-autocomplete-input-description"
        placeholder="Search" data-bi-name="site-header-search-autocomplete-input" pattern=".*">
      <span aria-hidden="true" class="autocomplete-loader loader has-text-primary " hidden=""></span>
      <span hidden="" id="ms--site-header-search-autocomplete-input-description"> Suggestions will filter as you type </span>
    </div>
    <ul role="listbox" id="ax-0-listbox" data-test-id="site-header-search-autocomplete-input-listbox" class="autocomplete-suggestions is-vertically-scrollable padding-xxs " aria-label="Suggestions" hidden="">
    </ul>
    <!---->
  </div>
  <!-- mobile safari will not dispatch submit event unless there's a submit button that is not display:none -->
  <button type="submit" class="visually-hidden" tabindex="-1" aria-hidden="true"></button>
  <input name="category" hidden="" value="Reference">
</form>

javascript:

<form action="javascript:" role="search" aria-label="Search" class="margin-bottom-xxs"><label class="visually-hidden" for="ax-2">Search</label>
  <div class="autocomplete display-block" data-bi-name="autocomplete"><!---->
    <div class="field-body control has-icons-left">
      <input role="combobox" maxlength="100" aria-autocomplete="list" autocapitalize="off" autocomplete="off" autocorrect="off" spellcheck="false" id="ax-2" data-test-id="ax-2" class="autocomplete-input input input-sm
						control has-icons-left
						width-full" type="text" aria-expanded="false" aria-owns="ax-3-listbox" aria-controls="ax-3-listbox" aria-activedescendant="" aria-describedby="ms--ax-2-description" placeholder="Filter by title" pattern=".*">
      <span aria-hidden="true" class="icon is-small is-left">
        <span class="has-text-primary docon docon-filter-settings"></span>
      </span>
      <span aria-hidden="true" class="autocomplete-loader loader has-text-primary " hidden=""></span>
      <span hidden="" id="ms--ax-2-description"> Suggestions will filter as you type </span>
    </div>
    <ul role="listbox" id="ax-3-listbox" data-test-id="ax-2-listbox" class="autocomplete-suggestions is-vertically-scrollable padding-xxs " aria-label="Suggestions" hidden="">
    </ul>
    <!---->
  </div>
</form>

Text Content

Skip to main content



MICROSOFT IGNITE

Nov 19–22, 2024

Join us this November to explore AI innovations, level up your skillset, and
expand your network.

Register now
Dismiss alert

This browser is no longer supported.

Upgrade to Microsoft Edge to take advantage of the latest features, security
updates, and technical support.

Download Microsoft Edge More info about Internet Explorer and Microsoft Edge

Learn
Suggestions will filter as you type
Sign in


 * Profile
 * Settings

Sign out

Learn
   
 * Discover
      
    * Documentation
      
      In-depth articles on Microsoft developer tools and technologies
   
      
    * Training
      
      Personalized learning paths and courses
   
      
    * Credentials
      
      Globally recognized, industry-endorsed credentials
   
      
    * Q&A
      
      Technical questions and answers moderated by Microsoft
   
      
    * Code Samples
      
      Code sample library for Microsoft developer tools and technologies
   
      
    * Assessments
      
      Interactive, curated guidance and recommendations
   
      
    * Shows
      
      Thousands of hours of original programming from Microsoft experts
   
      
   
   Microsoft Learn for Organizations
   
   Boost your team's technical skills
   
   Access curated resources to upskill your team and close skills gaps.

   
 * Product documentation
      
    * ASP.NET
      
    * Azure
      
    * Dynamics 365
      
    * Microsoft 365
      
    * Microsoft Copilot
      
    * Microsoft Edge
      
    * Microsoft Entra
      
    * Microsoft Graph
      
    * Microsoft Intune
      
    * Microsoft Purview
      
    * Microsoft Teams
      
    * .NET
      
    * Power Apps
      
    * Power BI
      
    * Power Platform
      
    * PowerShell
      
    * SQL
      
    * Sysinternals
      
    * Visual Studio
      
    * Windows
      
    * Windows Server
      
   
   View all products
   
   Microsoft Learn for Organizations
   
   Boost your team's technical skills
   
   Access curated resources to upskill your team and close skills gaps.

   
 * Development languages
      
    * C++
      
    * C#
      
    * DAX
      
    * Java
      
    * OData
      
    * OpenAPI
      
    * Power Query M
      
    * VBA
      
   
   Microsoft Learn for Organizations
   
   Boost your team's technical skills
   
   Access curated resources to upskill your team and close skills gaps.

   
 * Topics
      
    * Artificial intelligence
      
    * Compliance
      
    * DevOps
      
    * Platform engineering
      
    * Security
      
   
   Microsoft Learn for Organizations
   
   Boost your team's technical skills
   
   Access curated resources to upskill your team and close skills gaps.

   

Suggestions will filter as you type
Sign in


 * Profile
 * Settings

Sign out
Windows App Development
   
 * Explore
     
   * Desktop app types
     
   * Windows App SDK
     
   * Windows UI Library
     
   * MSIX
     
   
 * Development
     
   * Get started
     
   * Design
     
   * Develop
     
   * Deploy
     
   * Samples
     
   
 * Platforms
     
   * Desktop apps
       
     * WinUI 3
       
     * Win32
       
     * WPF
       
     * Windows Forms
       
     * UWP
       
     
   * Web
     
   * Windows IoT
     
   * Mixed Reality
     
   * Games
     
   
 * Troubleshooting
   
 * Resources
     
   * Downloads
     
   * Windows Dev Center
     
   * Windows developer support
     
   * Windows Insider Program
     
   * What's new for Windows 11
     
   * Microsoft Store
     
   * Windows training
     
   * Windows on Q&A
     
   * Windows Developer on Twitter
     
   
 * More
     
   * Explore
       
     * Desktop app types
       
     * Windows App SDK
       
     * Windows UI Library
       
     * MSIX
       
     
   * Development
       
     * Get started
       
     * Design
       
     * Develop
       
     * Deploy
       
     * Samples
       
     
   * Platforms
       
     * Desktop apps
         
       * WinUI 3
         
       * Win32
         
       * WPF
         
       * Windows Forms
         
       * UWP
         
       
     * Web
       
     * Windows IoT
       
     * Mixed Reality
       
     * Games
       
     
   * Troubleshooting
     
   * Resources
       
     * Downloads
       
     * Windows Dev Center
       
     * Windows developer support
       
     * Windows Insider Program
       
     * What's new for Windows 11
       
     * Microsoft Store
       
     * Windows training
       
     * Windows on Q&A
       
     * Windows Developer on Twitter
       
     
   

Dashboard
Table of contents Exit focus mode

Search
Suggestions will filter as you type
 * The Windows Shell
 * Appmgmt.h
 * Appnotify.h
 * Combaseapi.h
 * Commctrl.h
 * Cpl.h
 * Credentialprovider.h
 * Dimm.h
 * Dskquota.h
 * Exdisp.h
 * Imagetranscode.h
 * Inputpanelconfiguration.h
 * Intsafe.h
 * Intshcut.h
 * Iphlpapi.h
 * Mobsync.h
 * Ntquery.h
 * Objectarray.h
 * Oleidl.h
 * Pathcch.h
 * Profinfo.h
 * Propidl.h
 * Propkeydef.h
 * Propsys.h
 * Reconcil.h
 * Scrnsave.h
 * Shappmgr.h
 * Shdeprecated.h
 * Shellapi.h
   * Overview
   * APPBARDATA structure
   * AssocCreateForClasses function
   * ASSOCIATIONELEMENT structure
   * CommandLineToArgvW function
   * DoEnvironmentSubstA function
   * DoEnvironmentSubstW function
   * DragAcceptFiles function
   * DragFinish function
   * DragQueryFileA function
   * DragQueryFileW function
   * DragQueryPoint function
   * DuplicateIcon function
   * ExtractAssociatedIconA function
   * ExtractAssociatedIconExA function
   * ExtractAssociatedIconExW function
   * ExtractAssociatedIconW function
   * ExtractIconA function
   * ExtractIconExA function
   * ExtractIconExW function
   * ExtractIconW function
   * FindExecutableA function
   * FindExecutableW function
   * InitNetworkAddressControl function
   * NC_ADDRESS structure
   * NetAddr_DisplayErrorTip macro
   * NetAddr_GetAddress macro
   * NetAddr_GetAllowType macro
   * NetAddr_SetAllowType macro
   * NOTIFYICONDATAA structure
   * NOTIFYICONDATAW structure
   * NOTIFYICONIDENTIFIER structure
   * OPEN_PRINTER_PROPS_INFOA structure
   * OPEN_PRINTER_PROPS_INFOW structure
   * QUERY_USER_NOTIFICATION_STATE enumeration
   * SHAppBarMessage function
   * SHCreateProcessAsUserW function
   * SHCREATEPROCESSINFOW structure
   * Shell_NotifyIconA function
   * Shell_NotifyIconGetRect function
   * Shell_NotifyIconW function
   * ShellAboutA function
   * ShellAboutW function
   * ShellExecuteA function
   * ShellExecuteExA function
   * ShellExecuteExW function
   * SHELLEXECUTEINFOA structure
   * SHELLEXECUTEINFOW structure
   * ShellExecuteW function
   * ShellMessageBoxA function
   * ShellMessageBoxW function
   * SHEmptyRecycleBinA function
   * SHEmptyRecycleBinW function
   * SHEnumerateUnreadMailAccountsA function
   * SHEnumerateUnreadMailAccountsW function
   * SHEvaluateSystemCommandTemplate function
   * SHFILEINFOA structure
   * SHFILEINFOW structure
   * SHFileOperationA function
   * SHFileOperationW function
   * SHFILEOPSTRUCTA structure
   * SHFILEOPSTRUCTW structure
   * SHFreeNameMappings function
   * SHGetDiskFreeSpaceExA function
   * SHGetDiskFreeSpaceExW function
   * SHGetDriveMedia function
   * SHGetFileInfoA function
   * SHGetFileInfoW function
   * SHGetImageList function
   * SHGetLocalizedName function
   * SHGetNewLinkInfoA function
   * SHGetNewLinkInfoW function
   * SHGetStockIconInfo function
   * SHGetUnreadMailCountA function
   * SHGetUnreadMailCountW function
   * SHInvokePrinterCommandA function
   * SHInvokePrinterCommandW function
   * SHIsFileAvailableOffline function
   * SHLoadNonloadedIconOverlayIdentifiers function
   * SHNAMEMAPPINGA structure
   * SHNAMEMAPPINGW structure
   * SHQUERYRBINFO structure
   * SHQueryRecycleBinA function
   * SHQueryRecycleBinW function
   * SHQueryUserNotificationState function
   * SHRemoveLocalizedName function
   * SHSetLocalizedName function
   * SHSetUnreadMailCountA function
   * SHSetUnreadMailCountW function
   * SHSTOCKICONID enumeration
   * SHSTOCKICONINFO structure
   * SHTestTokenMembership function
 * Shellscalingapi.h
 * Shidfact.h
 * Shimgdata.h
 * Shldisp.h
 * Shlobj.h
 * Shlobj_core.h
 * Shlwapi.h
 * Shobjidl.h
 * Shobjidl_core.h
 * Shtypes.h
 * Storageprovider.h
 * Syncmgr.h
 * Thumbcache.h
 * Thumbnailstreamcache.h
 * Tlogstg.h
 * Urlmon.h
 * Userenv.h
 * Winnt.h
 * Winuser.h

Download PDF
    
 1. Learn
    
    
 2. Windows
    
    
 3. Apps
    
    
 4. Win32
    
    
 5. API
    
    
 6. The Windows Shell
    
    
 7. Shellapi.h
    
    
    

    
 1. Learn
    
    
 2. Windows
    
    
 3. Apps
    
    
 4. Win32
    
    
 5. API
    
    
 6. The Windows Shell
    
    
 7. Shellapi.h
    
    
    

Read in English Save
 * Add to Collections
 * Add to Plan

Table of contents Read in English Add to Collections Add to Plan Edit


--------------------------------------------------------------------------------

SHARE VIA

Facebook x.com LinkedIn Email

--------------------------------------------------------------------------------

Print
Table of contents


NOTIFYICONDATAW STRUCTURE (SHELLAPI.H)

 * Article
 * 03/10/2023

Feedback


IN THIS ARTICLE

    
 1. Syntax
    
 2. Members
    
 3. Remarks
    
 4. Requirements
    
 5. See also
    

Contains information that the system needs to display notifications in the
notification area. Used by Shell_NotifyIcon.


SYNTAX

C++ Copy


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;



MEMBERS

cbSize

Type: DWORD

The size of this structure, in bytes.

hWnd

Type: HWND

A handle to the window that receives notifications associated with an icon in
the notification area.

uID

Type: UINT

The application-defined identifier of the taskbar icon. The Shell uses either
(hWnd plus uID) or guidItem to identify which icon to operate on when
Shell_NotifyIcon is invoked. You can have multiple icons associated with a
single hWnd by assigning each a different uID. If guidItem is specified, uID is
ignored.

uFlags

Type: UINT

Flags that either indicate which of the other members of the structure contain
valid data or provide additional information to the tooltip as to how it should
display. This member can be a combination of the following values:

NIF_MESSAGE (0X00000001)

0x00000001. The uCallbackMessage member is valid.

NIF_ICON (0X00000002)

0x00000002. The hIcon member is valid.

NIF_TIP (0X00000004)

0x00000004. The szTip member is valid.

NIF_STATE (0X00000008)

0x00000008. The dwState and dwStateMask members are valid.

NIF_INFO (0X00000010)

0x00000010. Display a balloon notification. The szInfo, szInfoTitle,
dwInfoFlags, and uTimeout members are valid. Note that uTimeout is valid only in
Windows 2000 and Windows XP.

 * To display the balloon notification, specify NIF_INFO and provide text in
   szInfo.
 * To remove a balloon notification, specify NIF_INFO and provide an empty
   string through szInfo.
 * To add a notification area icon without displaying a notification, do not set
   the NIF_INFO flag.

NIF_GUID (0X00000020)

0x00000020.

 * Windows 7 and later: The guidItem is valid.
 * Windows Vista and earlier: Reserved.

NIF_REALTIME (0X00000040)

0x00000040. Windows Vista and later. If the balloon notification cannot be
displayed immediately, discard it. Use this flag for notifications that
represent real-time information which would be meaningless or misleading if
displayed at a later time. For example, a message that states "Your telephone is
ringing." NIF_REALTIME is meaningful only when combined with the NIF_INFO flag.

NIF_SHOWTIP (0X00000080)

0x00000080. Windows Vista and later. Use the standard tooltip. Normally, when
uVersion is set to NOTIFYICON_VERSION_4, the standard tooltip is suppressed and
can be replaced by the application-drawn, pop-up UI. If the application wants to
show the standard tooltip with NOTIFYICON_VERSION_4, it can specify NIF_SHOWTIP
to indicate the standard tooltip should still be shown.

uCallbackMessage

Type: UINT

An application-defined message identifier. The system uses this identifier to
send notification messages to the window identified in hWnd. These notification
messages are sent when a mouse event or hover occurs in the bounding rectangle
of the icon, when the icon is selected or activated with the keyboard, or when
those actions occur in the balloon notification.

When the uVersion member is either 0 or NOTIFYICON_VERSION, the wParam parameter
of the message contains the identifier of the taskbar icon in which the event
occurred. This identifier can be 32 bits in length. The lParam parameter holds
the mouse or keyboard message associated with the event. For example, when the
pointer moves over a taskbar icon, lParam is set to WM_MOUSEMOVE.

When the uVersion member is NOTIFYICON_VERSION_4, applications continue to
receive notification events in the form of application-defined messages through
the uCallbackMessage member, but the interpretation of the lParam and wParam
parameters of that message is changed as follows:

 * LOWORD(lParam) contains notification events, such as NIN_BALLOONSHOW,
   NIN_POPUPOPEN, or WM_CONTEXTMENU.
 * HIWORD(lParam) contains the icon ID. Icon IDs are restricted to a length of
   16 bits.
 * GET_X_LPARAM(wParam) returns the X anchor coordinate for notification events
   NIN_POPUPOPEN, NIN_SELECT, NIN_KEYSELECT, and all mouse messages between
   WM_MOUSEFIRST and WM_MOUSELAST. If any of those messages are generated by the
   keyboard, wParam is set to the upper-left corner of the target icon. For all
   other messages, wParam is undefined.
 * GET_Y_LPARAM(wParam) returns the Y anchor coordinate for notification events
   and messages as defined for the X anchor.

hIcon

Type: HICON

A handle to the icon to be added, modified, or deleted. Windows XP and later
support icons of up to 32 BPP.

If only a 16x16 pixel icon is provided, it is scaled to a larger size in a
system set to a high dpi value. This can lead to an unattractive result. It is
recommended that you provide both a 16x16 pixel icon and a 32x32 icon in your
resource file. Use LoadIconMetric to ensure that the correct icon is loaded and
scaled appropriately. See Remarks for a code example.

szTip[64]

Type: TCHAR[64]

A null-terminated string that specifies the text for a standard tooltip. It can
have a maximum of 64 characters, including the terminating null character.

For Windows 2000 and later, szTip can have a maximum of 128 characters,
including the terminating null character.

szTip[128]

Type: TCHAR[64]

A null-terminated string that specifies the text for a standard tooltip. It can
have a maximum of 64 characters, including the terminating null character.

For Windows 2000 and later, szTip can have a maximum of 128 characters,
including the terminating null character.

dwState

Type: DWORD

Windows 2000 and later. The state of the icon. One or both of the following
values:

NIS_HIDDEN (0X00000001)

0x00000001. The icon is hidden.

NIS_SHAREDICON (0X00000002)

0x00000002. The icon resource is shared between multiple icons.

dwStateMask

Type: DWORD

Windows 2000 and later. A value that specifies which bits of the dwState member
are retrieved or modified. The possible values are the same as those for
dwState. For example, setting this member to NIS_HIDDEN causes only the item's
hidden state to be modified while the icon sharing bit is ignored regardless of
its value.

szInfo[256]

Type: TCHAR[256]

Windows 2000 and later. A null-terminated string that specifies the text to
display in a balloon notification. It can have a maximum of 256 characters,
including the terminating null character, but should be restricted to 200
characters in English to accommodate localization. To remove the balloon
notification from the UI, either delete the icon (with NIM_DELETE) or set the
NIF_INFO flag in uFlags and set szInfo to an empty string.

DUMMYUNIONNAME

DUMMYUNIONNAME.uTimeout

Type: UINT

Windows 2000 and later.

Note  This member is deprecated as of Windows Vista. Notification display times
are now based on system accessibility settings.
 
Union with uVersion. The timeout value, in milliseconds, for notification. The
system enforces minimum and maximum timeout values. Values specified in uTimeout
that are too large are set to the maximum value. Values that are too small
default to the minimum value. The system minimum and maximum timeout values are
currently set at 10 seconds and 30 seconds, respectively. See Remarks for
further discussion of uTimeout.

DUMMYUNIONNAME.uVersion

Type: UINT

Windows 2000 and later. Union with uTimeout (deprecated as of Windows Vista).
Specifies which version of the Shell notification icon interface should be used.
For more information on the differences in these versions, see Shell_NotifyIcon.
This member is employed only when using Shell_NotifyIcon to send an
NIM_SETVERSION message.

szInfoTitle[64]

Type: TCHAR[64]

Windows 2000 and later. A null-terminated string that specifies a title for a
balloon notification. This title appears in a larger font immediately above the
text. It can have a maximum of 64 characters, including the terminating null
character, but should be restricted to 48 characters in English to accommodate
localization.

dwInfoFlags

Type: DWORD

Windows 2000 and later. Flags that can be set to modify the behavior and
appearance of a balloon notification. The icon is placed to the left of the
title. If the szInfoTitle member is zero-length, the icon is not shown.

NIIF_NONE (0X00000000)

0x00000000. No icon.

NIIF_INFO (0X00000001)

0x00000001. An information icon.

NIIF_WARNING (0X00000002)

0x00000002. A warning icon.

NIIF_ERROR (0X00000003)

0x00000003. An error icon.

NIIF_USER (0X00000004)

0x00000004. Windows XP SP2 and later.

 * Windows XP: Use the icon identified in hIcon as the notification balloon's
   title icon.
 * Windows Vista and later: Use the icon identified in hBalloonIcon as the
   notification balloon's title icon.

NIIF_NOSOUND (0X00000010)

0x00000010. Windows XP and later. Do not play the associated sound. Applies only
to notifications.

NIIF_LARGE_ICON (0X00000020)

0x00000020. Windows Vista and later. The large version of the icon should be
used as the notification icon. This corresponds to the icon with dimensions
SM_CXICON x SM_CYICON. If this flag is not set, the icon with dimensions
SM_CXSMICON x SM_CYSMICON is used.

 * This flag can be used with all stock icons.
 * Applications that use older customized icons (NIIF_USER with hIcon) must
   provide a new SM_CXICON x SM_CYICON version in the tray icon (hIcon). These
   icons are scaled down when they are displayed in the System Tray or System
   Control Area (SCA).
 * New customized icons (NIIF_USER with hBalloonIcon) must supply an SM_CXICON x
   SM_CYICON version in the supplied icon (hBalloonIcon).

NIIF_RESPECT_QUIET_TIME (0X00000080)

0x00000080. Windows 7 and later. Do not display the balloon notification if the
current user is in "quiet time", which is the first hour after a new user logs
into his or her account for the first time. During this time, most notifications
should not be sent or shown. This lets a user become accustomed to a new
computer system without those distractions. Quiet time also occurs for each user
after an operating system upgrade or clean installation. A notification sent
with this flag during quiet time is not queued; it is simply dismissed unshown.
The application can resend the notification later if it is still valid at that
time.

Because an application cannot predict when it might encounter quiet time, we
recommended that this flag always be set on all appropriate notifications by any
application that means to honor quiet time.

During quiet time, certain notifications should still be sent because they are
expected by the user as feedback in response to a user action, for instance when
he or she plugs in a USB device or prints a document.

If the current user is not in quiet time, this flag has no effect.

NIIF_ICON_MASK (0X0000000F)

0x0000000F. Windows XP and later. Reserved.

guidItem

Type: GUID

Windows XP and later.

 * Windows 7 and later: A registered GUID that identifies the icon. This value
   overrides uID and is the recommended method of identifying the icon. The
   NIF_GUID flag must be set in the uFlags member.
 * Windows XP and Windows Vista: Reserved; must be set to 0.

If your application is intended to run on both Windows Vista and Windows 7, it
is imperative that you check the version of Windows and only specify a nonzero
guidItem if on Windows 7 or later.

If you identify the notification icon with a GUID in one call to
Shell_NotifyIcon, you must use that same GUID to identify the icon in any
subsequent Shell_NotifyIcon calls that deal with that same icon.

To generate a GUID for use in this member, use a GUID-generating tool such as
Guidgen.exe.

hBalloonIcon

Type: HICON

Windows Vista and later. The handle of a customized notification icon provided
by the application that should be used independently of the notification area
icon. If this member is non-NULL and the NIIF_USER flag is set in the
dwInfoFlags member, this icon is used as the notification icon. If this member
is NULL, the legacy behavior is carried out.


REMARKS

See Notifications in the Windows User Experience Interaction Guidelines for more
information on notification UI and content best practices.

If you set the NIF_INFO flag in the uFlags member, the balloon-style
notification is used. For more discussion of these notifications, see Balloon
tooltips.

No more than one balloon notification at a time can be displayed for the
taskbar. If an application attempts to display a notification when one is
already being displayed, the new notification is queued and displayed when the
older notification goes away. In versions of Windows before Windows Vista, the
new notification would not appear until the existing notification has been
visible for at least the system minimum timeout length, regardless of the
original notification's uTimeout value. If the user does not appear to be using
the computer, the system does not count this time toward the timeout.

Several members of this structure are only supported for Windows 2000 and later.
To enable these members, include one of the following lines in your header:

C++ Copy


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



Note that you must initialize the structure with its size. If you use the size
of the currently defined structure, the application might not run with earlier
versions of Shell32.dll, which expect a smaller structure. You can run your
application against earlier versions of Shell32.dll by defining the appropriate
version number (see Shell and Common Controls Versions). However, this might
cause problems if your application also needs to run on more recent systems.

You can maintain application compatibility with all Shell32.dll versions while
still using the current header files by setting the size of the NOTIFYICONDATA
structure appropriately. Before you initialize the structure, use DllGetVersion
to determine which Shell32.dll version is installed on the system and initialize
cbSize with one of these values:

Expand table

Shell32.dll Version cbSize 6.0.6 or higher (Windows Vista and later)
sizeof(NOTIFYICONDATA) 6.0 (Windows XP) NOTIFYICONDATA_V3_SIZE 5.0
(Windows 2000) NOTIFYICONDATA_V2_SIZE Versions lower than 5.0
NOTIFYICONDATA_V1_SIZE

 

Using this value for cbSize allows your application to use NOTIFYICONDATA in a
method compatible with earlier Shell32.dll versions.

The following code example shows version checking that can enable an application
that uses the guidItem member to run on both Windows Vista and Windows 7. It
provides a Boolean function that returns TRUE if the operating system is
Windows 7. Unless this member returns TRUE, the guidItem member must be set to
0.

Note  This code is specific to the Windows 7 version number. It is expected that
future versions of Windows and Windows Server will support the guidItem member,
and at that time this code must be updated to identify later version numbers as
valid as well.
 
C++ Copy


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



The following code example shows the use of LoadIconMetric to load an icon for
use with high DPI.

C++ Copy


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




TROUBLESHOOTING

If you are using the guidItem member to identify the icon, and that icon is not
seen or some calls to Shell_NotifyIcon fail, one of the following cases is the
likely cause:
 1. The NIF_GUID flag was not set in every call to Shell_NotifyIcon. Once you
    identify the notification icon with a GUID in one call to Shell_NotifyIcon,
    you must use that same GUID to identify the icon in any subsequent
    Shell_NotifyIcon calls that deal with that same icon.
 2. The binary file that contains the icon was moved. The path of the binary
    file is included in the registration of the icon's GUID and cannot be
    changed. Settings associated with the icon are preserved through an upgrade
    only if the file path and GUID are unchanged. If the path must be changed,
    the application should remove any GUID information that was added when the
    existing icon was registered. Once that information is removed, you can move
    the binary file to a new location and reregister it with a new GUID. Any
    settings associated with the original GUID registration will be lost.
    
    This also occurs in the case of a side-by-side installation. When dealing
    with a side-by-side installation, new versions of the application should
    update the GUID of the binary file.
    
    Note  The only exception to a moved file occurs when both the original and
    moved binary files are Authenticode-signed by the same company. In that
    case, settings are preserved through the move.
     

Note

The shellapi.h header defines NOTIFYICONDATA as an alias which automatically
selects the ANSI or Unicode version of this function based on the definition of
the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias
with code that not encoding-neutral can lead to mismatches that result in
compilation or runtime errors. For more information, see Conventions for
Function Prototypes.


REQUIREMENTS

Expand table

Requirement Value Minimum supported client Windows XP [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only] Header
shellapi.h


SEE ALSO

Notifications and the Notification Area





--------------------------------------------------------------------------------


FEEDBACK

Was this page helpful?

Yes No
Provide product feedback |
Get help at Microsoft Q&A

--------------------------------------------------------------------------------


ADDITIONAL RESOURCES




--------------------------------------------------------------------------------

Events

Nov 19, 1 PM - Nov 21, 1 PM

Gain the competitive edge you need with powerful AI and Cloud solutions by
attending Microsoft Ignite online.

Register now

English (United States)
California Consumer Privacy Act (CCPA) Opt-Out Icon Your Privacy Choices
Theme
 * Light
 * Dark
 * High contrast

 * 
 * Previous Versions
 * Blog
 * Contribute
 * Privacy
 * Terms of Use
 * Trademarks
 * © Microsoft 2024


ADDITIONAL RESOURCES

--------------------------------------------------------------------------------

Events

Nov 19, 1 PM - Nov 21, 1 PM

Gain the competitive edge you need with powerful AI and Cloud solutions by
attending Microsoft Ignite online.

Register now




IN THIS ARTICLE



English (United States)
California Consumer Privacy Act (CCPA) Opt-Out Icon Your Privacy Choices
Theme
 * Light
 * Dark
 * High contrast

 * 
 * Previous Versions
 * Blog
 * Contribute
 * Privacy
 * Terms of Use
 * Trademarks
 * © Microsoft 2024