Funzione SendMessageTimeoutA (winuser.h)

Articolo
08/07/2024

Invia il messaggio specificato a una o più finestre.

Sintassi

LRESULT SendMessageTimeoutA(
  [in]            HWND       hWnd,
  [in]            UINT       Msg,
  [in]            WPARAM     wParam,
  [in]            LPARAM     lParam,
  [in]            UINT       fuFlags,
  [in]            UINT       uTimeout,
  [out, optional] PDWORD_PTR lpdwResult
);

Parametri

[in] hWnd

Tipo: HWND

Handle per la finestra la cui routine della finestra riceverà il messaggio.

Se questo parametro è HWND_BROADCAST ((HWND)0xffff), il messaggio viene inviato a tutte le finestre di primo livello del sistema, incluse le finestre disabilitate o invisibili non generate. La funzione non restituisce fino a quando non si è verificato il timeout di ogni finestra. Pertanto, il tempo di attesa totale può essere fino al valore di uTimeout moltiplicato per il numero di finestre di primo livello.

[in] Msg

Tipo: UINT

Messaggio da inviare.

Per gli elenchi dei messaggi forniti dal sistema, vedere System-Defined Messaggi.

[in] wParam

Tipo: WPARAM

Eventuali informazioni aggiuntive specifiche del messaggio.

[in] lParam

Tipo: LPARAM

Eventuali informazioni aggiuntive specifiche del messaggio.

[in] fuFlags

Tipo: UINT

Comportamento di questa funzione. Questo parametro può essere uno o più dei valori seguenti.

Valore	Significato
SMTO_ABORTIFHUNG 0x0002	La funzione restituisce senza attendere la scadenza del periodo di timeout se il thread ricevente sembra non rispondere o "blocca".
SMTO_BLOCK 0x0001	Impedisce al thread chiamante di elaborare qualsiasi altra richiesta fino a quando la funzione non viene restituita.
SMTO_NORMAL 0x0000	Il thread chiamante non viene impedito di elaborare altre richieste durante l'attesa della restituzione della funzione.
SMTO_NOTIMEOUTIFNOTHUNG 0x0008	La funzione non applica il periodo di timeout a condizione che il thread ricevente stia elaborando i messaggi.
SMTO_ERRORONEXIT 0x0020	La funzione deve restituire 0 se la finestra di ricezione viene eliminata definitivamente o se il thread proprietario muore durante l'elaborazione del messaggio.

[in] uTimeout

Tipo: UINT

Durata del periodo di timeout, espresso in millisecondi. Se il messaggio è un messaggio di trasmissione, ogni finestra può usare il periodo di timeout completo. Ad esempio, se si specifica un periodo di timeout di cinque secondi e sono presenti tre finestre di primo livello che non riescono a elaborare il messaggio, è possibile che si verifichi un ritardo di 15 secondi.

[out, optional] lpdwResult

Tipo: PDWORD_PTR

Risultato dell'elaborazione del messaggio. Il valore di questo parametro dipende dal messaggio specificato.

Valore restituito

Tipo: LRESULT

Se la funzione ha esito positivo, il valore restituito è diverso da zero. SendMessageTimeout non fornisce informazioni sul timeout delle singole finestre se viene usato HWND_BROADCAST.

Se la funzione ha esito negativo o si verifica il timeout, il valore restituito è 0. Si noti che la funzione non chiama sempre SetLastError in caso di errore. Se il motivo dell'errore è importante, chiamare SetLastError(ERROR_SUCCESS) prima di chiamare SendMessageTimeout. Se la funzione restituisce 0 e GetLastError restituisce ERROR_SUCCESS, considerarla come errore generico.

Osservazioni

La funzione chiama la routine della finestra per la finestra specificata e, se la finestra specificata appartiene a un thread diverso, non restituisce finché la routine della finestra non ha elaborato il messaggio o il periodo di timeout specificato è trascorso. Se la finestra che riceve il messaggio appartiene alla stessa coda del thread corrente, viene chiamata direttamente la routine della finestra. Il valore di timeout viene ignorato.

Questa funzione considera che un thread non risponde se non ha chiamato GetMessage o una funzione simile entro cinque secondi.

Il sistema esegue solo il marshalling per i messaggi di sistema (quelli compresi nell'intervallo da 0 a (WM_USER-1)). Per inviare altri messaggi (quelli >= WM_USER) a un altro processo, è necessario eseguire il marshalling personalizzato.

Nota

L'intestazione winuser.h definisce SendMessageTimeout 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 di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 2000 Professional [solo app desktop]
server minimo supportato	Windows 2000 Server [solo app desktop]
piattaforma di destinazione	Finestre
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)