GetMessage 関数 (winuser.h)

呼び出し元のスレッドのメッセージ キューからメッセージを取得します。 この関数は、ポストされたメッセージを取得できるようになるまで、受信送信メッセージをディスパッチします。

GetMessage とは異なり、PeekMessage 関数は、返される前にメッセージが投稿されるのを待つことはありません。

構文

BOOL GetMessage(
  [out]          LPMSG lpMsg,
  [in, optional] HWND  hWnd,
  [in]           UINT  wMsgFilterMin,
  [in]           UINT  wMsgFilterMax
);

パラメーター

[out] lpMsg

型: LPMSG

スレッドのメッセージ キューからメッセージ情報を受信する MSG 構造体へのポインター。

[in, optional] hWnd

型: HWND

メッセージを取得するウィンドウへのハンドル。 ウィンドウは現在のスレッドに属している必要があります。

hWndNULL の場合、GetMessage は、現在のスレッドに属するすべてのウィンドウのメッセージと、hwnd 値が NULL である現在のスレッドのメッセージ キュー上のすべてのメッセージを取得します (MSG 構造体を参照)。 したがって、hWnd が NULL の場合、ウィンドウ メッセージとスレッド メッセージの両方が処理されます。

hWnd が -1 の場合、GetMessage は現在のスレッドのメッセージ キュー上のメッセージのみを取得します。そのメッセージの hwnd 値は NULL です。つまり、PostMessage によってポストされたスレッド メッセージ (hWnd パラメーターが NULL の場合) または PostThreadMessage です。

[in] wMsgFilterMin

型: UINT

取得するメッセージの最小値の整数値。 WM_KEYFIRST (0x0100) を使用して、最初のキーボード メッセージを指定するかWM_MOUSEFIRST (0x0200) を使用して最初のマウス メッセージを指定します。

ここでは wMsgFilterMaxWM_INPUT使用して、WM_INPUT メッセージのみを指定します。

wMsgFilterMinwMsgFilterMax の両方が 0 の場合、GetMessage は使用可能なすべてのメッセージを返します (つまり、範囲フィルター処理は実行されません)。

[in] wMsgFilterMax

型: UINT

取得するメッセージの最大値の整数値。 最後のキーボード メッセージを指定するには WM_KEYLAST を使用するか、最後のマウス メッセージを指定するWM_MOUSELASTを使用します。

ここでは wMsgFilterMinWM_INPUT使用して、WM_INPUT メッセージのみを指定します。

wMsgFilterMinwMsgFilterMax の両方が 0 の場合、GetMessage は使用可能なすべてのメッセージを返します (つまり、範囲フィルター処理は実行されません)。

戻り値

型: BOOL

関数がWM_QUIT以外のメッセージを取得する場合、戻り値は 0 以外です。

関数が WM_QUIT メッセージを取得した場合、戻り値は 0 になります。

エラーが発生した場合、戻り値は -1 です。 たとえば、 hWnd が無効なウィンドウ ハンドルであるか、 lpMsg が無効なポインターである場合、関数は失敗します。 詳細なエラー情報を得るには、GetLastError を呼び出します。

戻り値には 0 以外、0、または -1 を指定できるため、次のようなコードは使用しないでください。

while (GetMessage( lpMsg, hWnd, 0, 0)) ...

hWnd が無効なパラメーターである場合に -1 戻り値が返される可能性 (既に破棄されているウィンドウを参照するなど) は、そのようなコードが致命的なアプリケーション エラーにつながる可能性があることを意味します。 代わりに、次のようなコードを使用します。

BOOL bRet;

while( (bRet = GetMessage( &msg, hWnd, 0, 0 )) != 0)
{ 
    if (bRet == -1)
    {
        // handle the error and possibly exit
    }
    else
    {
        TranslateMessage(&msg); 
        DispatchMessage(&msg); 
    }
}

注釈

通常、アプリケーションは戻り値を使用して、メイン・メッセージ・ループを終了してプログラムを終了するかどうかを判別します。

GetMessage 関数は、IsChild 関数で指定された、および wMsgFilterMin パラメーターと wMsgFilterMax パラメーターによって指定されたメッセージ値の範囲内で、hWnd パラメーターまたはその子のいずれかによって識別されるウィンドウに関連付けられているメッセージを取得します。 アプリケーションでは、wMsgFilterMin パラメーターと wMsgFilterMax パラメーター内のロー ワードのみを使用できることに注意してください。高い単語はシステム用に予約されています。

GetMessage は、wMsgFilterMin と wMsgFilterMax に指定した値に関係なく、常にWM_QUITメッセージを取得します。

この呼び出し中に、システムは保留中のキューに入れないメッセージ、つまり SendMessage、SendMessageCallbackSendMessageTimeout、または SendNotifyMessage 関数を使用して、呼び出し元スレッドが所有するウィンドウに送信されたメッセージを配信します。 その後、指定したフィルターに一致するキューに登録された最初のメッセージが取得されます。 システムは内部イベントを処理することもできます。 フィルターを指定しない場合、メッセージは次の順序で処理されます。

ポストされたメッセージの前に入力メッセージを取得するには、wMsgFilterMin パラメーターと wMsgFilterMax パラメーターを使用します。

GetMessage では、 キューからWM_PAINT メッセージは削除されません。 メッセージは処理されるまでキューに残ります。

最上位のウィンドウが数秒間以上メッセージへの応答を停止した場合、システムはウィンドウが応答していないと見なし、同じ z オーダー、場所、サイズ、およびビジュアル属性を持つゴースト ウィンドウに置き換えます。 これにより、ユーザーはそれを移動したり、サイズを変更したり、アプリケーションを閉じたりすることができます。 ただし、アプリケーションが実際に応答していないために使用できるアクションはこれらのみです。 デバッガー モードの場合、システムはゴースト ウィンドウを生成しません。

DPI 仮想化

この API は、DPI 仮想化には参加しません。 出力は、メッセージが対象としているウィンドウのモードです。 呼び出し元のスレッドは考慮されません。

例については、「 メッセージ ループの作成」を参照してください。

要件

   
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー winuser.h (Windows.h を含む)
Library User32.lib
[DLL] User32.dll
API セット ext-ms-win-ntuser-message-l1-1-0 (Windows 8 で導入)

こちらもご覧ください

概念

IsChild

Msg

メッセージとメッセージ キュー

PeekMessage

PostMessage

PostThreadMessage

リファレンス

WaitMessage