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

任務列圖示的應用程式定義識別碼。 Shell 會使用 (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) 會針對通知事件傳回 X 錨點座標NIN_POPUPOPEN、NIN_SELECT、NIN_KEYSELECT，以及WM_MOUSEFIRST與WM_MOUSELAST之間的所有滑鼠訊息。 如果鍵盤產生任何訊息， wParam 會設定為目標圖示的左上角。 若為所有其他訊息， 則未定義 wParam 。
• GET_Y_LPARAM (wParam) 會針對通知事件和 X 錨點定義的訊息傳回 Y 錨點座標。

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 移除批註通知，請刪除圖示 (搭配 NIM_DELETE) ，或在 uFlags 中設定NIF_INFO旗標，並將 szInfo 設定為空字串。

DUMMYUNIONNAME

DUMMYUNIONNAME.uTimeout

類型： UINT

Windows 2000 和更新版本。

注意 此成員在 Windows Vista 中已被取代。 通知顯示時間現在會根據系統協助工具設定。

 

與 uVersion 的聯集。 通知的逾時值，以毫秒為單位。 系統會強制執行最小和最大逾時值。 uTimeout 中指定的值太大，會設定為最大值。 太小的值預設為最小值。 系統最小和最大逾時值目前分別設定為10秒和30秒。 如需 uTimeout 的進一步討論，請參閱。

DUMMYUNIONNAME.uVersion

類型： UINT

Windows 2000 和更新版本。 與 uTimeout 的聯集 (從 Windows Vista) 起淘汰。 指定應該使用哪個版本的Shell通知圖示介面。 如需這些版本差異的詳細資訊，請參閱 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維度的圖示。

• 此旗標可以搭配所有 股票圖示使用。
• 搭配 hIcon (NIIF_USER) 使用較舊自定義圖示的應用程式必須在匣圖示 (hIcon) 中提供新的 SM_CXICON x SM_CYICON 版本。 這些圖示會在系統匣或系統控制區域 (SCA) 中顯示時相應減少。
• 使用 hBalloonIcon) (NIIF_USER 的新自定義圖示必須在提供的圖示中提供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。

如果您的應用程式是要同時在 Windows Vista 和 Windows 7 上執行，請務必檢查 Windows 版本，而且只有在 Windows 7 或更新版本上指定非零 guidItem 。

如果您在一次呼叫 Shell_NotifyIcon中以 GUID 識別通知圖示，則必須使用該相同的 GUID 來識別處理該相同圖示的任何後續 Shell_NotifyIcon 呼叫中的圖示。

若要產生要用於此成員的 GUID，請使用 GUID 產生工具，例如 Guidgen.exe。

hBalloonIcon

類型： HICON

Windows Vista 和更新版本。 應用程式所提供的自定義通知圖示句柄，該圖示應該與通知區域圖示無關。 如果此成員為非 NULL，且在 dwInfoFlags 成員中設定NIIF_USER旗標，則會使用此圖示作為通知圖示。 如果此成員為 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 執行應用程式 (，請參閱 殼層和通用控件版本) 。 不過，如果您的應用程式也需要在較新的系統上執行，這可能會造成問題。

您可以適當地設定 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， 否則 guidItem 成員必須設定為 0。

注意 此程式代碼專屬於 Windows 7 版本號碼。 預期未來的 Windows 和 Windows Server 版本將支援 guidItem 成員，而且此時必須更新此程式代碼，才能識別較新的版本號碼也有效。

 

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 的某些呼叫失敗，下列其中一個情況可能是原因：

1. NIF_GUID旗標未在每個呼叫 中設定Shell_NotifyIcon。 一旦您在呼叫 Shell_NotifyIcon 時，使用 GUID 識別通知圖示之後，您必須使用相同的 GUID 來識別處理該相同圖示的任何後續 Shell_NotifyIcon 呼叫中的圖示。
2. 包含圖示的二進位檔已移動。 二進位檔的路徑包含在圖示 GUID 的註冊中，而且無法變更。 只有在檔案路徑和 GUID 未變更時，才會透過升級來保留與圖示相關聯的設定。 如果路徑必須變更，應用程式應該移除註冊現有圖示時新增的任何 GUID 資訊。 拿掉該資訊之後，您可以將二進位檔移至新的位置，並使用新的 GUID 重新註冊該檔案。 與原始 GUID 註冊相關聯的任何設定都會遺失。

   這也會在並存安裝的情況下發生。 處理並存安裝時，新版本的應用程式應該更新二進位檔的 GUID。

   注意 當原始和移動的二進位檔都是由同一家公司簽署 Authenticode 時，才會發生移動檔案的唯一例外狀況。 在此情況下，會透過移動來保留設定。
    

注意

Shellapi.h 標頭會將 NOTIFYICONDATA 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
標頭	shellapi.h

另請參閱

通知和通知區域