ホーム › UI.Shell › IUserNotification2

IUserNotification2

COM

📘 Microsoft Learn (日本語) · English

IID215913cc-57eb-4fab-ab5a-e5fa7bea2a6c継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

通知情報を設定し、その通知をタスクバーの通知領域に関連付けて表示されるバルーンとしてユーザーに表示するためのメソッドを公開します。(IUserNotification2)

解説(Remarks)

実装するタイミング

このインターフェイスの実装は、Windows で CLSID_UserNotification として提供されています。

メソッド 5

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT SetBalloonInfo(LPWSTR pszTitle, LPWSTR pszText, DWORD dwInfoFlags)

バルーン通知に表示する情報を設定します。(IUserNotification2.SetBalloonInfo)

pszTitle

LPWSTR

通知のタイトルを指定する Unicode 文字列へのポインター。

pszText

LPWSTR

バルーンの本文に表示するテキストを指定する Unicode 文字列へのポインター。

dwInfoFlags

DWORD

通知バルーンに表示するアイコンを示す、次の値のうち 1 つ以上。

NIIF_NONE (0x00000000)

0x00000000。アイコンを表示しません。

NIIF_INFO (0x00000001)

0x00000001。情報アイコンを表示します。

NIIF_WARNING (0x00000002)

0x00000002。警告アイコンを表示します。

NIIF_ERROR (0x00000003)

0x00000003。エラーアイコンを表示します。

NIIF_USER (0x00000004)

0x00000004。Windows XP SP2 以降。通知バルーンに hIcon で指定されたアイコンを使用します。

NIIF_NOSOUND (0x00000010)

0x00000010。Windows XP 以降。関連付けられたサウンドを再生しません。この値はバルーン通知にのみ適用され、標準のユーザー通知には適用されません。

NIIF_LARGE_ICON (0x00000010)

0x00000010。Windows Vista 以降。通知バルーンのアイコンとして大きいバージョンのアイコンを使用します。これは SM_CXICON x SM_CYICON の寸法を持つアイコンに対応します。このフラグが設定されていない場合は、XM_CXSMICON x SM_CYSMICON の寸法を持つアイコンが使用されます。

このフラグはすべてのストックアイコンで使用できます。
古いカスタマイズ済みアイコン(hIcon を伴う NIIF_USER)を使用するアプリケーションは、NOTIFYICONDATA 構造体の hIcon メンバーで指定したトレイアイコンに、新しい SM_CXICON x SM_CYICON バージョンを提供する必要があります。これらのアイコンは、通知領域に表示される際に縮小されます。
新しいカスタマイズ済みアイコン(hBalloonIcon を伴う NIIF_USER)は、指定するアイコン(hBalloonIcon)に SM_CXICON x SM_CYICON バージョンを提供する必要があります。

NIIF_RESPECT_QUIET_TIME (0x00000080)

0x00000080。Windows 7 以降。現在のユーザーが「クワイエットタイム」(新しいユーザーが初めて自分のアカウントにログインしてから最初の 1 時間)にある場合は、通知バルーンを表示しません。この時間帯には、ほとんどの通知を送信したり表示したりすべきではありません。これにより、ユーザーはそうした煩わしさなしに新しいコンピューターシステムに慣れることができます。クワイエットタイムは、オペレーティングシステムのアップグレードやクリーンインストールの後にも、各ユーザーに対して発生します。クワイエットタイム中にこのフラグ付きで送信された通知はキューに入れられず、単に表示されないまま破棄されます。アプリケーションは、その通知がその時点でまだ有効であれば、後で再送できます。

アプリケーションはクワイエットタイムに遭遇する時期を予測できないため、クワイエットタイムを尊重しようとするアプリケーションでは、適切なすべての通知に対して常にこのフラグを設定することを推奨します。

現在のユーザーがクワイエットタイム中でない場合、このフラグは効果を持ちません。

NIIF_ICON_MASK (0x0000000F)

0x0000000F。Windows XP(Shell32.dll バージョン 6.0)以降。予約されています。

戻り値

型: HRESULT

このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 4 HRESULT SetBalloonRetry(DWORD dwShowTime, DWORD dwInterval, DWORD cRetryCount)

最初の試行が失敗した場合に、ユーザー情報の表示を再試行する条件を指定します。(IUserNotification2.SetBalloonRetry)

dwShowTime	DWORD	in	ユーザー情報を表示する時間(ミリ秒単位)。
dwInterval	DWORD	in	ユーザー情報の表示を試行する間隔(ミリ秒単位)。
cRetryCount	DWORD	in	システムがユーザー情報の表示を試行する回数。

戻り値

型: HRESULT

このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 5 HRESULT SetIconInfo(HICON hIcon, LPWSTR pszToolTip)

特定のユーザー情報に関連付ける通知領域アイコンを設定します。(IUserNotification2.SetIconInfo)

hIcon	HICON	in	アイコンへのハンドル。
pszToolTip	LPWSTR	in	指定したアイコンに対して表示するツールチップテキストを格納した文字列へのポインター。この値は NULL にできますが、推奨されません。

戻り値

型: HRESULT

このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 6 HRESULT Show(IQueryContinue* pqc, DWORD dwContinuePollInterval, IUserNotificationCallback* pSink)

ユーザー情報をバルーン形式のツールチップで表示します。

pqc	IQueryContinue*	in	通知の表示を続行できるか、それとも停止すべきか(たとえばユーザーが通知を閉じた場合など)を判断するために使用する IQueryContinue インターフェイスポインター。この値は NULL にできます。
dwContinuePollInterval	DWORD	in	ユーザー情報を表示する時間(ミリ秒単位)。
pSink	IUserNotificationCallback*	in	通知領域アイコン上および通知自体の中でのマウスクリックやホバーアクションを処理するために使用する IUserNotificationCallback インターフェイスへのポインター。この値は NULL にできます。

戻り値

型: HRESULT

このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 7 HRESULT PlaySound(LPWSTR pszSoundName)

通知に合わせてサウンドを再生します。(IUserNotification2.PlaySound)

pszSoundName

LPWSTR

再生するサウンドファイルのエイリアスを指定する、null 終端の Unicode 文字列へのポインター。

戻り値

型: HRESULT

このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

pszSoundName が指す文字列には、レジストリまたは Win.ini ファイル内で見つかるシステムイベントのエイリアス(たとえば "SystemExit")が含まれます。

指定したサウンドは非同期に再生され、メソッドはサウンドの開始後ただちに戻ります。非同期の波形サウンドを停止するには、pszSoundName を NULL に設定して IUserNotification2::PlaySound を呼び出します。

指定したサウンドイベントは、すでに再生中の別のサウンドイベントに道を譲ります。サウンドの再生に必要なリソースがビジー状態のためにサウンドを再生できない場合、メソッドは要求されたサウンドを再生せずにただちに S_FALSE を返します。

指定したサウンドが見つからない場合、IUserNotification2::PlaySound はシステムの既定のサウンドを使用します。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

#define global IID_IUserNotification2 "{215913CC-57EB-4FAB-AB5A-E5FA7BEA2A6C}"
#usecom global IUserNotification2 IID_IUserNotification2 "{0010890E-8789-413C-ADBC-48F5B511B3AF}"
#comfunc global IUserNotification2_SetBalloonInfo   3 wstr,wstr,int
#comfunc global IUserNotification2_SetBalloonRetry  4 int,int,int
#comfunc global IUserNotification2_SetIconInfo      5 sptr,wstr
#comfunc global IUserNotification2_Show             6 sptr,int,sptr
#comfunc global IUserNotification2_PlaySound        7 wstr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。