NOTIFYICONDATAA 構造体 (shellapi.h)

[アーティクル]
03/08/2023

システムが通知領域に通知を表示するために必要な情報を格納します。 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 を割り当てることで、1 つの 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_REALTIMEは、NIF_INFO フラグと組み合わせる場合にのみ意味があります。

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) にはアイコン ID が含まれています。アイコン ID は、16 ビットの長さに制限されます。
GET_X_LPARAM(wParam) は、通知イベントNIN_POPUPOPEN、NIN_SELECT、NIN_KEYSELECT、およびWM_MOUSEFIRSTとWM_MOUSELASTの間のすべてのマウスメッセージの X アンカー座標を返します。これらのメッセージのいずれかがキーボードによって生成された場合、 wParam はターゲットアイコンの左上隅に設定されます。その他のすべてのメッセージの 場合、wParam は未定義です。
GET_Y_LPARAM(wParam) は、X アンカーに対して定義されている通知イベントとメッセージの Y アンカー座標を返します。

hIcon

種類: HICON

追加、変更、または削除するアイコンへのハンドル。 Windows XP 以降では、最大 32 BPP のアイコンがサポートされています。

16 x 16 ピクセルのアイコンのみが指定されている場合は、システムの大きなサイズにスケーリングされ、高 dpi 値に設定されます。これにより、魅力的でない結果が発生する可能性があります。リソースファイルには、16 x 16 ピクセルのアイコンと 32 x 32 アイコンの両方を指定することをお勧めします。 LoadIconMetric を使用して、正しいアイコンが適切に読み込まれ、スケーリングされていることを確認します。コード例については、「解説」を参照してください。

szTip[64]

種類: TCHAR[64]

標準のツールヒントのテキストを指定する null で終わる文字列。終端の null 文字を含め、最大 64 文字を指定できます。

Windows 2000 以降の場合、 szTip には、終端の null 文字を含め、最大 128 文字を指定できます。

szTip[128]

種類: TCHAR[64]

標準のツールヒントのテキストを指定する null で終わる文字列。終端の null 文字を含め、最大 64 文字を指定できます。

Windows 2000 以降の場合、 szTip には、終端の null 文字を含め、最大 128 文字を指定できます。

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 で終わる文字列。終端の null 文字を含め、最大 256 文字を使用できますが、ローカライズに対応するには、英語では 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_NotifyIcon」を参照してください。このメンバーは、Shell_NotifyIconを使用して NIM_SETVERSIONメッセージを 送信する場合にのみ使用されます。

szInfoTitle[64]

種類: TCHAR[64]

Windows 2000 以降。バルーン通知のタイトルを指定する null で終わる文字列。このタイトルは、テキストのすぐ上に大きなフォントで表示されます。終端の null 文字を含め、最大 64 文字を使用できますが、ローカライズに対応するには、英語では 48 文字に制限する必要があります。

dwInfoFlags

型: DWORD

Windows 2000 以降。バルーン通知の動作と外観を変更するために設定できるフラグ。アイコンはタイトルの左側に配置されます。 szInfoTitle メンバーの長さが 0 の場合、アイコンは表示されません。

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 以降。アイコンの大きなバージョンは、通知アイコンとして使用する必要があります。これは、x SM_CYICON SM_CXICONディメンションを持つアイコンに対応します。このフラグが設定されていない場合は、x SM_CYSMICON SM_CXSMICONディメンションを持つアイコンが使用されます。

このフラグは、すべてのストックアイコンと共に使用できます。
以前のカスタマイズされたアイコン ( hIcon でNIIF_USER) を使用するアプリケーションでは、トレイアイコン (hIcon) に新しいSM_CXICON x SM_CYICON バージョンを提供する必要があります。これらのアイコンは、システムトレイまたはシステムコントロールエリア (SCA) に表示されるときにスケールダウンされます。
新しいカスタマイズされたアイコン ( hBalloonIcon でNIIF_USER) は、指定されたアイコン (hBalloonIcon) にSM_CXICON x SM_CYICON バージョンを指定する必要があります。

NIIF_RESPECT_QUIET_TIME (0x00000080)

0x00000080。 Windows 7 以降。現在のユーザーが "静かな時間" にある場合は、バルーン通知を表示しないでください。これは、新しいユーザーが自分のアカウントに初めてログインしてから最初の 1 時間後です。この期間中は、ほとんどの通知を送信したり表示したりしないでください。これにより、ユーザーは、これらの気を散らすことなく、新しいコンピューターシステムに慣れできるようになります。オペレーティングシステムのアップグレードまたはクリーンのインストール後も、各ユーザーに対して静かな時間が発生します。このフラグを使用して通知が送信されたが、通知はキューに登録されません。それは単に無視され、表示されません。アプリケーションは、その時点でも有効な場合は、後で通知を再送信できます。

アプリケーションでは、いつ静かな時間が発生する可能性があるかを予測できないため、このフラグは、静かな時間を優先することを意味する任意のアプリケーションによって、すべての適切な通知に常に設定することをお勧めします。

一定の通知は、ユーザーが 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 以降の場合は 0 以外の guidItem のみを指定することが不可欠です。

Shell_NotifyIconへの 1 回の呼び出しで GUID を持つ通知アイコンを識別する場合は、その同じ GUID を使用して、その同じアイコンを処理する後続のShell_NotifyIcon呼び出しのアイコンを識別する必要があります。

このメンバーで使用する GUID を生成するには、Guidgen.exe などの GUID 生成ツールを使用します。

hBalloonIcon

種類: HICON

Windows Vista 以降。通知領域アイコンとは別に使用する必要があるアプリケーションによって提供されるカスタマイズされた通知アイコンのハンドル。このメンバーが NULL 以外で、 dwInfoFlags メンバーでNIIF_USER フラグが設定されている場合、このアイコンは通知アイコンとして使用されます。このメンバーが NULL の場合、レガシ動作が実行されます。

注釈

通知 UI とコンテンツのベストプラクティスの詳細については、「Windows ユーザーエクスペリエンス操作ガイドライン」の「通知」を参照してください。

uFlags メンバーで NIF_INFO フラグを設定すると、バルーンスタイルの通知が使用されます。これらの通知の詳細については、「バルーンヒント」を参照してください。

タスクバーに対して一度に 1 つ以上のバルーン通知を表示することはできません。アプリケーションが既に表示されているときに通知を表示しようとすると、新しい通知はキューに登録され、古い通知が消えたときに表示されます。 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の呼び出しが失敗した場合は、次のいずれかの原因が考えられます。

NIF_GUID フラグは、 Shell_NotifyIconの呼び出しごとに設定されませんでした。 Shell_NotifyIconへの 1 回の呼び出しで GUID を持つ通知アイコンを識別したら、その同じ GUID を使用して、その同じアイコンを処理する後続のShell_NotifyIcon呼び出しでアイコンを識別する必要があります。
アイコンを含むバイナリファイルが移動されました。バイナリファイルのパスはアイコンの GUID の登録に含まれており、変更できません。アイコンに関連付けられている設定は、ファイルパスと GUID が変更されていない場合にのみ、アップグレードによって保持されます。パスを変更する必要がある場合、アプリケーションは、既存のアイコンが登録されたときに追加されたすべての GUID 情報を削除する必要があります。その情報が削除されたら、バイナリファイルを新しい場所に移動し、新しい GUID で再登録できます。元の GUID 登録に関連付けられている設定はすべて失われます。
これは、サイドバイサイドインストールの場合にも発生します。サイドバイサイドインストールを処理する場合、アプリケーションの新しいバージョンでは、バイナリファイルの GUID を更新する必要があります。

メモ移動されたファイルに対する唯一の例外は、元のバイナリファイルと移動されたバイナリファイルの両方が同じ会社によって Authenticode 署名されている場合に発生します。その場合、設定は移動によって保持されます。

注意

shellapi.h ヘッダーは NOTIFYICONDATA を別名として定義し、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイルエラーまたはランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows XP (デスクトップアプリのみ)
サポートされている最小のサーバー	Windows 2000 Server [デスクトップアプリのみ]
Header	shellapi.h

こちらもご覧ください

通知と通知領域

NOTIFYICONDATAA 構造体 (shellapi.h)

構文

メンバー

NIF_MESSAGE (0x00000001)

NIF_ICON (0x00000002)

NIF_TIP (0x00000004)

NIF_STATE (0x00000008)

NIF_INFO (0x00000010)

NIF_GUID (0x00000020)

NIF_REALTIME (0x00000040)

NIF_SHOWTIP (0x00000080)

NIS_HIDDEN (0x00000001)

NIS_SHAREDICON (0x00000002)

NIIF_NONE (0x00000000)

NIIF_INFO (0x00000001)

NIIF_WARNING (0x00000002)

NIIF_ERROR (0x00000003)

NIIF_USER (0x00000004)

NIIF_NOSOUND (0x00000010)

NIIF_LARGE_ICON (0x00000020)

NIIF_RESPECT_QUIET_TIME (0x00000080)

NIIF_ICON_MASK (0x0000000F)

注釈

トラブルシューティング

要件

こちらもご覧ください

フィードバック

フィードバック

その他のリソース