ホーム › UI.Shell › IUserNotification

IUserNotification

COM

📘 Microsoft Learn (日本語) · English

IIDba9711ba-5893-4787-a7e1-41277151550b継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

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

解説(Remarks)

実装するタイミング

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

メソッド 5

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

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

バルーン通知に表示する情報を設定します。(IUserNotification.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 のアイコンが使用されます。

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

最初の試行が失敗したときにユーザー情報の表示を試みる条件を指定します。(IUserNotification.SetBalloonRetry)

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

戻り値

型: HRESULT

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

vtbl 5 HRESULT SetIconInfo(HICON hIcon, LPWSTR pszToolTip)

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

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

戻り値

型: HRESULT

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

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

通知を表示します。

pqc	IQueryContinue*	in	通知の表示を継続できるか、または停止すべきか(たとえばユーザーが通知を閉じた場合など)を判断するために使用する IQueryContinue インターフェイスポインター。この値は NULL にすることができます。
dwContinuePollInterval	DWORD	in	ユーザー情報を表示する時間の長さ(ミリ秒単位)。

戻り値

型: HRESULT

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

解説(Remarks)

このメソッドは、pSink=NULL を指定して Show を呼び出すことと同等です。

vtbl 7 HRESULT PlaySound(LPWSTR pszSoundName)

通知に連動してサウンドを再生します。(IUserNotification.PlaySound)

pszSoundName

LPWSTR

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

戻り値

型: HRESULT

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

解説(Remarks)

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

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

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

指定したサウンドが見つからない場合、IUserNotification::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_IUserNotification "{BA9711BA-5893-4787-A7E1-41277151550B}"
#usecom global IUserNotification IID_IUserNotification "{0010890E-8789-413C-ADBC-48F5B511B3AF}"
#comfunc global IUserNotification_SetBalloonInfo   3 wstr,wstr,int
#comfunc global IUserNotification_SetBalloonRetry  4 int,int,int
#comfunc global IUserNotification_SetIconInfo      5 sptr,wstr
#comfunc global IUserNotification_Show             6 sptr,int
#comfunc global IUserNotification_PlaySound        7 wstr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。