SHMessageBoxCheckA 関数 (shlwapi.h)

  • [アーティクル]

[SHMessageBoxCheck は、[要件] セクションで指定されたオペレーティング システムで使用できます。 以降のバージョンでは変更または使用できない場合があります。]

ユーザーがそれ以上の発生を抑制するオプションを提供するメッセージ ボックスを表示します。 ユーザーがメッセージ ボックスを抑制することを既に選択している場合、関数はダイアログ ボックスを表示せず、代わりに単に既定値を返します。

構文

int SHMessageBoxCheckA(
  [in, optional] HWND   hwnd,
  [in]           LPCSTR pszText,
  [in]           LPCSTR pszCaption,
                 UINT   uType,
                 int    iDefault,
  [in]           LPCSTR pszRegVal
);

パラメーター

[in, optional] hwnd

型: HWND

メッセージ ボックスの所有者へのウィンドウ ハンドル。 この値は NULL にすることができます。

[in] pszText

型: LPCTSTR

表示するメッセージを含む null で終わる文字列へのポインター。

[in] pszCaption

型: LPCTSTR

メッセージ ボックスのタイトルを含む null で終わる文字列へのポインター。 このパラメーターが NULL に設定されている場合、タイトルは Error! に設定されます。

uType

型: UINT

メッセージ ボックスの内容と動作を指定するフラグ。 この関数は、 MessageBox でサポートされているフラグのサブセットのみをサポートします。 以下に記載されていないフラグを使用する場合、関数の動作は未定義です。

表示するボタンは、次のフラグの 1 つだけを設定して指定する必要があります。

MB_OKCANCEL

[OK] ボタンと [キャンセル] ボタンを含むメッセージ ボックスを表示します。

MB_YESNO

[はい] ボタンと [いいえ] ボタンを含むメッセージ ボックスを表示します。

MB_OK

[OK] ボタンを含むメッセージ ボックスを表示します。

オプションのアイコンを表示するには、次のいずれかのフラグのみを設定します。

MB_ICONHAND

停止記号アイコンを表示します。

MB_ICONQUESTION

疑問符アイコンを表示します。

MB_ICONEXCLAMATION

感嘆符アイコンを表示します。

MB_ICONINFORMATION

小文字の "i" を円で囲んだアイコンを表示します。

iDefault

型: int

ユーザーがメッセージ ボックスを再び表示しないことを選択したときに関数が返す値。 ユーザーがメッセージ ボックスの非表示を選択していない場合は、メッセージ ボックスが表示され、関数は iDefault を無視します。

[in] pszRegVal

型: LPCTSTR

このメッセージに関連付ける一意の文字列値を含む null で終わる文字列へのポインター。 Microsoft で使用される値との競合を回避するには、この文字列に GUID を含める必要があります。 この文字列は、終端の null 文字を含め、長さがREGSTR_MAX_VALUE_LENGTH文字を超えてはなりません。

戻り値

型: int

ユーザーがメッセージ ボックスを抑制することを既に選択している場合、関数は iDefault に割り当てられた値をすぐに返します。

ユーザーが [OK]、[ キャンセル]、[ はい]、または [いいえ ] ボタンをクリックすると、この関数は IDOK、IDCANCEL、IDYES、または IDNO をそれぞれ返します。

ユーザーがキャプションの [X] ボタンをクリックしてメッセージ ボックスを閉じると、関数は IDCANCEL を返します。 この場合、MB_OKCANCEL フラグが設定されていない場合でも、この値が返されます。

エラーが発生した場合、戻り値は通常 –1 です。 ただし、特定のメモリ不足の条件下では、関数は iDefault を返す可能性があります。

解説

セキュリティの警告: 関数が –1 または iDefault を返す場合は、危険なアクションを実行しないでください。 メッセージ ボックスを表示しようとしたときにエラーが発生した場合、 SHMessageBoxCheck は -1 または場合によっては iDefault を返します。 このようなエラーは、メモリまたはリソースが不足していることが原因で発生する可能性があります。 これらの戻り値のいずれかを取得する場合は、ユーザーが必ずしもダイアログ ボックスを表示しなかったため、アクションに肯定的に同意しなかったことに注意する必要があります。

"このダイアログ ボックスを表示しない" と "この回答を記憶する" と混同しないでください。 SHMessageBoxCheck では、"この回答を記憶する" 機能は提供されません。 ユーザーがメッセージ ボックスを再度非表示にすることを選択した場合、関数はクリックしたボタンを保持しません。 その代わりに、 SHMessageBoxCheck の後続の呼び出しでは、 単に iDefault で指定された値が返されます。 例を次に示します。


int iResult = SHMessageBoxCheck(hwnd, 
                                TEXT("Do you want to exit without saving?"),
                                TEXT("Warning"), 
                                MB_YESNO, 
                                IDNO,
                                TEXT("{d9108ba3-9a61-4398-bfbc-b02102c77e8a}");

ユーザーが [今後] を選択した場合 は、この ダイアログ ボックスを表示せず、[ はい ] ボタンをクリックすると、 SHMessageBoxCheck は IDYES を返します。 ただし、次にこのコードを実行すると、ユーザーが最初に [はい] を選択した場合でも、SHMessageBoxCheck は IDYES を返しません。 代わりに、IDNO が返されます。これは iDefault で指定された値であるためです。

メッセージ ボックスに表示される既定のボタンは、 iDefault 値と一致する必要があります。 MB_DEFBUTTON2 フラグのサポートがないため、MB_OK または MB_OKCANCEL フラグを指定した場合は、 iDefault を IDOK に設定する必要があります。 MB_YESNO フラグを設定している場合は、 iDefault 値を IDYES に設定する必要があります。

SHMessageBoxCheck は、ユーザーが次のレジストリ キーの下で抑制するように選択したメッセージ ボックスを記録します。

HKEY_CURRENT_USER
   Software
      Microsoft
         Windows
            CurrentVersion
               Explorer
                  DontShowMeThisDialogAgain

注意

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

要件

   
サポートされている最小のクライアント Windows XP (デスクトップ アプリのみ)
サポートされている最小のサーバー Windows Server 2003 (デスクトップ アプリのみ)
対象プラットフォーム Windows
ヘッダー shlwapi.h
[DLL] Shlwapi.dll (バージョン 5.0 以降)