Funzione GetMessage (winuser.h)

Articolo
03/04/2024

Recupera un messaggio dalla coda di messaggi del thread chiamante. La funzione invia messaggi inviati in ingresso fino a quando non è disponibile un messaggio inviato per il recupero.

Le funzioni GetMessage come PeekMessage, tuttavia, bloccano getMessage fino a quando non viene pubblicato un messaggio prima della restituzione.

Sintassi

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

Parametri

[out] lpMsg

Tipo: LPMSG

Puntatore a una struttura MSG che riceve informazioni sui messaggi dalla coda dei messaggi del thread.

[in, optional] hWnd

Tipo: HWND

Handle della finestra di cui recuperare i messaggi. La finestra deve appartenere al thread corrente.

Se hWnd è NULL, GetMessage recupera i messaggi per qualsiasi finestra appartenente al thread corrente e tutti i messaggi nella coda dei messaggi del thread corrente il cui valore generato è NULL (vedere la struttura MSG ). Pertanto, se hWnd è NULL, vengono elaborati sia i messaggi della finestra che i messaggi di thread.

Se hWnd è -1, GetMessage recupera solo i messaggi nella coda dei messaggi del thread corrente il cui valore hwnd è NULL, ovvero i messaggi di thread inviati da PostMessage (quando il parametro hWnd è NULL) o PostThreadMessage.

[in] wMsgFilterMin

Tipo: UINT

Valore intero del valore del messaggio più basso da recuperare. Utilizzare WM_KEYFIRST (0x0100) per specificare il primo messaggio da tastiera o WM_MOUSEFIRST (0x0200) per specificare il primo messaggio del mouse.

Usare WM_INPUT qui e in wMsgFilterMax per specificare solo i messaggi WM_INPUT .

Se wMsgFilterMin e wMsgFilterMax sono entrambi zero, GetMessage restituisce tutti i messaggi disponibili, ovvero non viene eseguito alcun filtro di intervallo.

[in] wMsgFilterMax

Tipo: UINT

Valore intero del valore del messaggio più alto da recuperare. Utilizzare WM_KEYLAST per specificare l'ultimo messaggio della tastiera o WM_MOUSELAST per specificare l'ultimo messaggio del mouse.

Usare WM_INPUT qui e in wMsgFilterMin per specificare solo i messaggi WM_INPUT .

Se wMsgFilterMin e wMsgFilterMax sono entrambi zero, GetMessage restituisce tutti i messaggi disponibili, ovvero non viene eseguito alcun filtro di intervallo.

Valore restituito

Tipo: BOOL

Se la funzione recupera un messaggio diverso da WM_QUIT, il valore restituito è diverso da zero.

Se la funzione recupera il messaggio WM_QUIT , il valore restituito è zero.

Se si verifica un errore, il valore restituito è -1. Ad esempio, la funzione ha esito negativo se hWnd è un handle di finestra non valido o lpMsg è un puntatore non valido. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Poiché il valore restituito può essere diverso da zero, zero o -1, evitare codice simile al seguente:

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

La possibilità di un valore restituito -1 nel caso in cui hWnd sia un parametro non valido (ad esempio facendo riferimento a una finestra che è già stata eliminata definitivamente) significa che tale codice può causare errori irreversibili dell'applicazione. Usare invece codice simile al seguente:

BOOL bRet;

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

Commenti

Un'applicazione usa in genere il valore restituito per determinare se terminare il ciclo di messaggi principale e uscire dal programma.

La funzione GetMessage recupera i messaggi associati alla finestra identificata dal parametro hWnd o da uno dei relativi elementi figlio, come specificato dalla funzione IsChild e all'interno dell'intervallo di valori del messaggio specificati dai parametri wMsgFilterMin e wMsgFilterMax . Si noti che un'applicazione può usare solo la parola bassa nei parametri wMsgFilterMin e wMsgFilterMax ; la parola alta è riservata al sistema.

Si noti che GetMessage recupera sempre WM_QUIT messaggi, indipendentemente dai valori specificati per wMsgFilterMin e wMsgFilterMax.

Durante questa chiamata, il sistema recapita messaggi in sospeso, non accodati, ovvero messaggi inviati a finestre di proprietà del thread chiamante tramite la funzione SendMessage, SendMessageCallback, SendMessageTimeout o SendNotifyMessage. Viene quindi recuperato il primo messaggio in coda corrispondente al filtro specificato. Il sistema può anche elaborare eventi interni. Se non viene specificato alcun filtro, i messaggi vengono elaborati nell'ordine seguente:

Messaggi inviati
Messaggi inviati
Messaggi di input (hardware) ed eventi interni del sistema
Messaggi inviati (di nuovo)
messaggi WM_PAINT
WM_TIMER messaggi

Per recuperare i messaggi di input prima dei messaggi inviati, usare i parametri wMsgFilterMin e wMsgFilterMax .

GetMessage non rimuove WM_PAINT messaggi dalla coda. I messaggi rimangono nella coda fino a quando non vengono elaborati.

Se una finestra di primo livello smette di rispondere ai messaggi per più di diversi secondi, il sistema considera che la finestra non risponde e la sostituisce con una finestra fantasma con gli stessi attributi z, posizione, dimensioni e oggetti visivi. In questo modo l'utente può spostarlo, ridimensionarlo o persino chiudere l'applicazione. Tuttavia, queste sono le uniche azioni disponibili perché l'applicazione in realtà non risponde. Quando si usa la modalità debugger, il sistema non genera una finestra fantasma.

Virtualizzazione DPI

Questa API non partecipa alla virtualizzazione DPI. L'output è in modalità della finestra di destinazione del messaggio. Il thread chiamante non viene preso in considerazione.

Esempio

Per un esempio, vedere Creazione di un ciclo di messaggi.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winuser.h (include Windows.h)
Libreria	User32.lib
DLL	User32.dll
Set di API	ext-ms-win-ntuser-message-l1-1-0 (introdotto in Windows 8)