Funzione PeekMessageA (winuser.h)

Invia messaggi non accodati in arrivo, controlla la coda di messaggi del thread per un messaggio inviato e recupera il messaggio (se presente).

Sintassi

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

Parametri

[out] lpMsg

Tipo: LPMSG

Puntatore a una struttura MSG che riceve informazioni sui messaggi.

[in, optional] hWnd

Tipo: HWND

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

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

Se hWnd è -1, PeekMessage 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 del primo messaggio nell'intervallo di messaggi da esaminare. Utilizzare WM_KEYFIRST (0x0100) per specificare il primo messaggio da tastiera o WM_MOUSEFIRST (0x0200) per specificare il primo messaggio del mouse.

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

[in] wMsgFilterMax

Tipo: UINT

Valore dell'ultimo messaggio nell'intervallo di messaggi da esaminare. Utilizzare WM_KEYLAST per specificare l'ultimo messaggio della tastiera o WM_MOUSELAST per specificare l'ultimo messaggio del mouse.

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

[in] wRemoveMsg

Tipo: UINT

Specifica la modalità di gestione dei messaggi. Questo parametro può essere uno o più dei valori seguenti.

Valore Significato
PM_NOREMOVE
0x0000
I messaggi non vengono rimossi dalla coda dopo l'elaborazione da PeekMessage.
PM_REMOVE
0x0001
I messaggi vengono rimossi dalla coda dopo l'elaborazione da PeekMessage.
PM_NOYIELD
0x0002
Impedisce al sistema di rilasciare qualsiasi thread in attesa che il chiamante vada inattivo (vedere WaitForInputIdle).

Combinare questo valore con PM_NOREMOVE o PM_REMOVE.

 

Per impostazione predefinita, vengono elaborati tutti i tipi di messaggio. Per specificare che è necessario elaborare solo un determinato messaggio, specificare uno o più dei valori seguenti.

Valore Significato
PM_QS_INPUT
(QS_INPUT << 16)
Elaborare i messaggi del mouse e della tastiera.
PM_QS_PAINT
(QS_PAINT << 16)
Elaborare i messaggi di disegno.
PM_QS_POSTMESSAGE
((QS_POSTMESSAGE | QS_HOTKEY | QS_TIMER) 16) <<
Elaborare tutti i messaggi inviati, inclusi timer e tasti di scelta rapida.
PM_QS_SENDMESSAGE
(QS_SENDMESSAGE << 16)
Elaborare tutti i messaggi inviati.

Valore restituito

Tipo: BOOL

Se è disponibile un messaggio, il valore restituito è diverso da zero.

Se non sono disponibili messaggi, il valore restituito è zero.

Commenti

PeekMessage 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 di 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 PeekMessage recupera sempre WM_QUIT messaggi, indipendentemente dai valori specificati per wMsgFilterMin e wMsgFilterMax.

Durante questa chiamata, il sistema invia messaggi in sospeso (DispatchMessage), non accodati, ovvero i messaggi inviati alle finestre di proprietà del thread chiamante usando 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 .

La funzione PeekMessage in genere non rimuove WM_PAINT messaggi dalla coda. WM_PAINT i messaggi rimangono nella coda fino a quando non vengono elaborati. Tuttavia, se un messaggio di WM_PAINT ha un'area di aggiornamento NULL , PeekMessage lo rimuove dalla coda.

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 di ordine 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 viene eseguito il debug di un'applicazione, 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 Analisi di una coda di messaggi.

Nota

L'intestazione winuser.h definisce PeekMessage come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

   
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)

Vedi anche

Informazioni concettuali

GetMessage

IsChild

Msg

Messaggi e code di messaggi

Altre risorse

Riferimento

WaitForInputIdle

WaitMessage