NOTIFYICONDATAA 結構 （shellapi.h）
包含系統需要在通知區域中顯示通知的資訊。 由 Shell_NotifyIcon使用。
語法
typedef struct _NOTIFYICONDATAA {
DWORD cbSize;
HWND hWnd;
UINT uID;
UINT uFlags;
UINT uCallbackMessage;
HICON hIcon;
#if ...
CHAR szTip[64];
#else
CHAR szTip[128];
#endif
DWORD dwState;
DWORD dwStateMask;
CHAR szInfo[256];
union {
UINT uTimeout;
UINT uVersion;
} DUMMYUNIONNAME;
CHAR szInfoTitle[64];
DWORD dwInfoFlags;
GUID guidItem;
HICON hBalloonIcon;
} NOTIFYICONDATAA, *PNOTIFYICONDATAA;
成員
cbSize
類型：DWORD
這個結構的大小，以位元組為單位。
hWnd
類型：HWND
視窗的句柄，可接收與通知區域中圖示相關聯的通知。
uID
類型：UINT
任務列圖示的應用程式定義識別碼。 殼層會使用 （hWnd 加上 uID） 或 guidItem 來識別叫用 Shell_NotifyIcon 時要運作的圖示。 您可以指派每個不同的 uID，讓多個與單一 hWnd 相關聯的圖示。 如果指定 guidItem，則會忽略 uID。
uFlags
類型：UINT
指出結構的其他成員包含有效數據的旗標，或將其他資訊提供給工具提示，以瞭解其顯示方式。 這個成員可以是下列值的組合：
NIF_MESSAGE （0x00000001）
0x00000001。 uCallbackMessage 成員有效。
NIF_ICON （0x00000002）
0x00000002。 hIcon 成員有效。
NIF_TIP （0x00000004）
0x00000004。 szTip 成員有效。
NIF_STATE （0x00000008）
0x00000008。 dwState 和 dwStateMask 成員有效。
NIF_INFO（0x00000010）
0x00000010。 顯示氣球通知。 szInfo、szInfoTitle、dwInfoFlags，以及 uTimeout 成員都是有效的。 請注意，uTimeout 僅適用於 Windows 2000 和 Windows XP。
- 若要顯示批注方塊通知，請指定NIF_INFO，並在 szInfo
中提供文字。 - 若要移除氣球通知，請指定NIF_INFO，並透過 szInfo 提供空字串。
- 若要新增通知區域圖示而不顯示通知，請勿設定NIF_INFO旗標。
NIF_GUID （0x00000020）
0x00000020。
- Windows 7 和更新版本：guidItem 有效。
- Windows Vista 和舊版：保留。
NIF_REALTIME （0x00000040）
0x00000040。 Windows Vista 和更新版本。 如果無法立即顯示氣球通知，請將其捨棄。 將此旗標用於代表即時資訊的通知，如果稍後顯示，則為毫無意義或誤導性的資訊。 例如，指出「您的電話正在響鈴」的訊息。只有在與 NIF_INFO 旗標結合時，NIF_REALTIME才有意義。
NIF_SHOWTIP （0x00000080）
0x00000080。 Windows Vista 和更新版本。 使用標準工具提示。 一般而言，uVersion 設定為NOTIFYICON_VERSION_4時，會隱藏標準工具提示，並可由應用程式繪製的快顯 UI 取代。 如果應用程式想要使用 NOTIFYICON_VERSION_4 顯示標準工具提示，則可以指定NIF_SHOWTIP來指出仍應顯示標準工具提示。
uCallbackMessage
類型：UINT
應用程式定義的訊息識別碼。 系統會使用此識別碼，將通知訊息傳送至 hWnd中所識別的視窗。 當滑鼠事件或暫留出現在圖示的周框、使用鍵盤選取或啟動圖示時，或當這些動作發生在氣球通知中時，就會傳送這些通知訊息。
當 uVersion 成員為 0 或 NOTIFYICON_VERSION時，訊息的 wParam 參數會包含發生事件之任務欄圖示的標識符。 此標識符長度可以是32位。 lParam 參數會保存與事件相關聯的滑鼠或鍵盤訊息。 例如，當指標移至工作列圖示上方時，lParam 設定為 WM_MOUSEMOVE。
當 uVersion 成員NOTIFYICON_VERSION_4時，應用程式會透過 uCallbackMessage 成員，繼續以應用程式定義訊息的形式接收通知事件，但 lParam 和 wParam 參數的解譯會如下所示：
- LOWORD（lParam） 包含通知事件，例如NIN_BALLOONSHOW、NIN_POPUPOPEN或WM_CONTEXTMENU。
- HIWORD（lParam） 包含圖示標識碼。 圖示標識碼限制為16位的長度。
- GET_X_LPARAM（wParam） 會傳回通知事件NIN_POPUPOPEN、NIN_SELECT、NIN_KEYSELECT以及WM_MOUSEFIRST與WM_MOUSELAST之間所有滑鼠訊息的 X 錨點座標。 如果鍵盤產生任何訊息，wParam 會設定為目標圖示的左上角。 對於所有其他訊息，未定義 wParam。
- GET_Y_LPARAM（wParam） 傳回通知事件和訊息的 Y 錨點座標，如 X 錨點所定義。
hIcon
類型：HICON
要加入、修改或刪除之圖示的句柄。 Windows XP 和更新版本支援最多 32 BPP 的圖示。
如果只提供 16x16 像素圖示，則會在系統中將它縮放為較大的大小，設定為高 DPI 值。 這可能會導致無吸引力的結果。 建議您在資源文件中同時提供 16x16 像素圖示和 32x32 圖示。 使用 LoadIconMetric，以確保正確載入並調整正確的圖示。 如需程式代碼範例，請參閱。
szTip[64]
類型：TCHAR[64]
以 Null 結束的字串，指定標準工具提示的文字。 最多可以有 64 個字元，包括終止的 Null 字元。
針對 Windows 2000 和更新版本，szTip 最多可以有 128 個字元，包括終止的 Null 字元。
szTip[128]
類型：TCHAR[64]
以 Null 結束的字串，指定標準工具提示的文字。 最多可以有 64 個字元，包括終止的 Null 字元。
針對 Windows 2000 和更新版本，szTip 最多可以有 128 個字元，包括終止的 Null 字元。
dwState
類型：DWORD
Windows 2000 及更新版本。 圖示的狀態。 下列其中一個或兩個值：
NIS_HIDDEN （0x00000001）
0x00000001。 圖示已隱藏。
NIS_SHAREDICON （0x00000002）
0x00000002。 圖示資源會在多個圖示之間共用。
dwStateMask
類型：DWORD
Windows 2000 及更新版本。 值，指定擷取或修改 dwState 成員的位。 可能的值與 dwState的值相同。 例如，將此成員設定為 NIS_HIDDEN 只會在忽略圖示共用位時修改專案的隱藏狀態，而不論其值為何。
szInfo[256]
類型：TCHAR[256]
Windows 2000 及更新版本。 以 Null 結束的字串，指定要在氣球通知中顯示的文字。 最多可以有 256 個字元，包括終止的 Null 字元，但應限制為英文 200 個字元以容納當地語系化。 若要從 UI 移除批註方塊通知，請刪除圖示（
DUMMYUNIONNAME
DUMMYUNIONNAME.uTimeout
類型：UINT
Windows 2000 及更新版本。
DUMMYUNIONNAME.uVersion
類型：UINT
Windows 2000 及更新版本。 與 uTimeout 的聯集（已取代為 Windows Vista）。 指定應該使用殼層通知圖示介面的版本。 如需這些版本差異的詳細資訊，請參閱 Shell_NotifyIcon。 只有在使用 Shell_NotifyIcon 傳送 NIM_SETVERSION 訊息時，才會使用這個成員。
szInfoTitle[64]
類型：TCHAR[64]
Windows 2000 及更新版本。 以 Null 結束的字串，指定氣球通知的標題。 此標題會顯示在文字正上方的較大字型中。 最多可以有 64 個字元，包括終止的 Null 字元，但應限制為英文 48 個字元以容納當地語系化。
dwInfoFlags
類型：DWORD
Windows 2000 及更新版本。 可設定為修改氣球通知行為和外觀的旗標。 圖示會放在標題的左邊。 如果 szInfoTitle 成員長度為零，則不會顯示圖示。
NIIF_NONE （0x00000000）
0x00000000。 沒有圖示。
NIIF_INFO （0x00000001）
0x00000001。 信息圖示。
NIIF_WARNING（0x00000002）
0x00000002。 警告圖示。
NIIF_ERROR （0x00000003）
0x00000003。 錯誤圖示。
NIIF_USER （0x00000004）
0x00000004。 Windows XP SP2 和更新版本。
- Windows XP：使用 hIcon 中識別的圖示作為通知氣球的標題圖示。
- Windows Vista 和更新版本：使用 hBalloonIcon 中識別的圖示作為通知氣球的標題圖示。
NIIF_NOSOUND （0x00000010）
0x00000010。 Windows XP 和更新版本。 請勿播放相關聯的音效。 僅適用於通知。
NIIF_LARGE_ICON（0x00000020）
0x00000020。 Windows Vista 和更新版本。 大型版本的圖示應該用來做為通知圖示。 這會對應至SM_CXICON x SM_CYICON維度的圖示。 如果未設定此旗標，則會使用維度SM_CXSMICON x SM_CYSMICON的圖示。
- 此旗標可與所有 股票圖示搭配使用，。
- 使用舊版自定義圖示的應用程式（NIIF_USER搭配 hIcon）必須在匣圖示中提供新的 SM_CXICON x SM_CYICON 版本（hIcon）。 這些圖示會在系統匣或系統控制區 （SCA） 中顯示時相應減少。
- 新的自定義圖示（NIIF_USER與 hBalloonIcon） 必須在提供的圖示中提供SM_CXICON x SM_CYICON 版本 （hBalloonIcon）。
NIIF_RESPECT_QUIET_TIME（0x00000080）
0x00000080。 Windows 7 和更新版本。 如果目前使用者處於「安靜時間」，則不要顯示氣球通知，這是新使用者第一次登入其帳戶后的第一小時。 在此期間，不應該傳送或顯示大部分的通知。 這可讓用戶習慣於新的計算機系統，而不會干擾這些干擾。 操作系統升級或全新安裝之後，每個使用者也會有無訊息時間。 在無訊息時間以這個旗標傳送的通知不會排入佇列;它只是解除了未洗牌。 如果應用程式當時仍然有效，則稍後可以重新傳送通知。
因為應用程式無法預測何時可能會遇到無訊息時間，因此我們建議任何表示接受無訊息時間的應用程式一律在所有適當的通知上設定此旗標。
在安靜時間，某些通知仍應傳送，因為用戶預期會以回應使用者動作的意見反應，例如，當他或她插入USB裝置或列印檔時。
如果目前的使用者不在無訊息時間，則此旗標不會有任何作用。
NIIF_ICON_MASK （0x0000000F）
0x0000000F。 Windows XP 和更新版本。 保留。
guidItem
類型：GUID
Windows XP 和更新版本。
- Windows 7 和更新版本：識別圖示的已註冊 GUID。 此值會覆寫 uID，而且是識別圖示的建議方法。 NIF_GUID旗標必須在 uFlags 成員中設定。
- Windows XP 和 Windows Vista：保留;必須設定為 0。
如果您在一次呼叫 Shell_NotifyIcon中使用 GUID 識別通知圖示，您必須使用該相同的 GUID 來識別處理該相同圖示的任何後續 Shell_NotifyIcon 呼叫中的圖示。
若要產生用於此成員的 GUID，請使用 GUID 產生工具，例如 Guidgen.exe。
hBalloonIcon
類型：HICON
Windows Vista 和更新版本。 應用程式所提供的自定義通知圖示句柄，應該與通知區域圖示無關。 如果這個成員不是 NULL，且NIIF_USER旗標是在 dwInfoFlags 成員中設定，則會使用此圖示作為通知圖示。 如果此成員 NULL，則會執行舊版行為。
言論
如需通知 UI 和內容最佳做法的詳細資訊，請參閱 Windows 用戶體驗互動指導方針中的「通知」。
如果您在 uFlags 成員中設定 NIF_INFO 旗標，則會使用氣球樣式通知。 如需這些通知的詳細資訊，請參閱 氣球工具提示。
任務欄一次只能顯示一個氣球通知。 如果應用程式嘗試在顯示通知時顯示通知，新的通知會排入佇列，並在較舊的通知消失時顯示。 在 Windows Vista 之前的 Windows 版本中，無論原始通知的 uTimeout 值為何，在至少系統最小逾時長度顯示現有通知之前，才會顯示新的通知。 如果使用者似乎未使用計算機，系統就不會將此時間計入逾時。
只有 Windows 2000 和更新版本才支援此結構的數個成員。 若要啟用這些成員，請在標頭中包含下列其中一行：
// Windows Vista and later:
#define NTDDI_VERSION NTDDI_WIN2K
#define NTDDI_VERSION NTDDI_WINXP
#define NTDDI_VERSION NTDDI_VISTA
// Windows XP and earlier:
#define _WIN32_IE 0x0500
請注意，您必須使用其大小來初始化 結構。 如果您使用目前定義的結構大小，則應用程式可能無法搭配舊版的 Shell32.dll執行，其預期結構較小。 您可以定義適當的版本號碼，針對舊版的 Shell32.dll 執行應用程式（請參閱 Shell 和 Common Controls 版本）。 不過，如果您的應用程式也需要在較新的系統上執行，這可能會造成問題。
您可以適當地設定 NOTIFYICONDATA 結構的大小，以維持與所有 Shell32.dll 版本的應用程式相容性，同時仍使用目前的頭檔案。 在初始化 結構之前，請使用 DllGetVersion 來判斷系統上已安裝哪個 Shell32.dll 版本，並使用下列其中一個值初始化 cbSize：
| Shell32.dll 版本 | cbSize |
|---|---|
| 6.0.6 或更高版本 （Windows Vista 和更新版本） | sizeof（NOTIFYICONDATA） |
| 6.0 （Windows XP） | NOTIFYICONDATA_V3_SIZE |
| 5.0 （Windows 2000） | NOTIFYICONDATA_V2_SIZE |
| 低於 5.0 的版本 | NOTIFYICONDATA_V1_SIZE |
針對 cbSize 使用這個值，可讓您的應用程式在與舊版 Shell32.dll 相容的方法中使用 NOTIFYICONDATA。
下列程式代碼範例顯示版本檢查，可讓使用 guidItem 成員的應用程式同時在 Windows Vista 和 Windows 7 上執行。 它會提供布爾函數，如果操作系統是 Windows 7，則會傳回 true true。 除非此成員傳回 TRUE
BOOL IsWin7OrLater()
{
// Initialize the OSVERSIONINFOEX structure.
OSVERSIONINFOEX osvi;
ZeroMemory(&osvi, sizeof(OSVERSIONINFOEX));
osvi.dwOSVersionInfoSize = sizeof(OSVERSIONINFOEX);
osvi.dwMajorVersion = 6;
osvi.dwMinorVersion = 1;
// Initialize the condition mask.
DWORDLONG dwlConditionMask = 0;
VER_SET_CONDITION(dwlConditionMask, VER_MAJORVERSION, VER_GREATER_EQUAL);
VER_SET_CONDITION(dwlConditionMask, VER_MINORVERSION, VER_GREATER_EQUAL);
// Perform the test.
return VerifyVersionInfo(&osvi,
VER_MAJORVERSION | VER_MINORVERSION,
dwlConditionMask);
}
下列程式代碼範例示範如何使用 LoadIconMetric 載入圖示，以搭配高 DPI 使用。
// Declare NOTIFYICONDATA details.
// Error handling is omitted here for brevity. Do not omit it in your code.
NOTIFYICONDATA nid = {};
nid.cbSize = sizeof(nid);
nid.hWnd = hWnd;
nid.uFlags = NIF_ICON | NIF_TIP | NIF_GUID;
// Note: This is an example GUID only and should not be used.
// Normally, you should use a GUID-generating tool to provide the value to
// assign to guidItem.
static const GUID myGUID =
{0x23977b55, 0x10e0, 0x4041, {0xb8, 0x62, 0xb1, 0x95, 0x41, 0x96, 0x36, 0x69}};
nid.guidItem = myGUID;
// This text will be shown as the icon's tooltip.
StringCchCopy(nid.szTip, ARRAYSIZE(nid.szTip), L"Test application");
// Load the icon for high DPI.
LoadIconMetric(hInst, MAKEINTRESOURCE(IDI_SMALL), LIM_SMALL, &(nid.hIcon));
// Show the notification.
Shell_NotifyIcon(NIM_ADD, &nid) ? S_OK : E_FAIL;
疑難解答
如果您使用 guidItem 成員來識別圖示，而且看不到該圖示或某些呼叫 Shell_NotifyIcon 失敗，下列其中一個情況可能是原因：- NIF_GUID 旗標未在每次呼叫 Shell_NotifyIcon中設定。 一旦您在一次呼叫 Shell_NotifyIcon時識別具有 GUID 的通知圖示，您必須使用該相同的 GUID 來識別處理該相同圖示的任何後續 Shell_NotifyIcon 呼叫中的圖示。
-
已移動包含圖示的二進位檔。 二進位檔的路徑包含在圖示 GUID 的註冊中，而且無法變更。 只有在檔案路徑和 GUID 未變更時，才會透過升級來保留與圖示相關聯的設定。 如果路徑必須變更，應用程式應該移除註冊現有圖示時新增的任何 GUID 資訊。 拿掉該資訊之後，您可以將二進位檔移至新位置，並使用新的 GUID 重新註冊。 與原始 GUID 註冊相關聯的任何設定都會遺失。
這也會在並存安裝的情況下發生。 處理並存安裝時，新版本的應用程式應該更新二進位檔的 GUID。
附註 當原始和移動的二進位檔 Authenticode由同一家公司簽署時，才會發生移動檔案的唯一例外狀況。 在此情況下，會透過移動保留設定。
注意
Shellapi.h 標頭會將 NOTIFYICONDATA 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱函式原型的
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | Windows XP [僅限傳統型應用程式] |
| 支援的最低伺服器 | Windows 2000 Server [僅限傳統型應用程式] |
| 標頭 | shellapi.h |