Funzione WSARecvEx (winsock.h)

Articolo
08/27/2023

La funzione WSARecvEx riceve i dati da un socket connesso o da un socket senza connessione associato. La funzione WSARecvEx è simile alla funzione recv , ad eccezione del fatto che il parametro flags viene usato solo per restituire informazioni. Quando viene ricevuto un messaggio parziale durante l'uso del protocollo datagram, il bit MSG_PARTIAL viene impostato nel parametro flags al momento della restituzione dalla funzione.

Nota La funzione WSARecvEx è un'estensione specifica di Microsoft per la specifica Di Windows Sockets.

Sintassi

int WSARecvEx(
  [in]      SOCKET s,
  [out]     char   *buf,
  [in]      int    len,
  [in, out] int    *flags
);

Parametri

[in] s

Descrittore che identifica un socket connesso.

[out] buf

Puntatore al buffer per ricevere i dati in ingresso.

[in] len

Lunghezza, in byte, del buffer a cui punta il parametro buf .

[in, out] flags

Indicatore che specifica se il messaggio viene ricevuto completamente o parzialmente per i socket di datagrammi.

Valore restituito

Se non si verifica alcun errore, WSARecvEx restituisce il numero di byte ricevuti. Se la connessione è stata chiusa, restituisce zero. Inoltre, se è stato ricevuto un messaggio parziale, il bit MSG_PARTIAL viene impostato nel parametro flags . Se è stato ricevuto un messaggio completo, MSG_PARTIAL non è impostato nei flag

In caso contrario, viene restituito un valore di SOCKET_ERROR e è possibile recuperare un codice di errore specifico chiamando WSAGetLastError.

Importante Per un protocollo di trasporto orientato ai flussi, MSG_PARTIAL non viene mai impostato in caso di restituzione da WSARecvEx. Questa funzione si comporta in modo identico alla funzione recv per i protocolli di trasporto di flusso.

Codice di errore	Significato
WSAECONNABORTED	Circuito virtuale terminato a causa di un timeout o di un altro errore. L'applicazione deve chiudere il socket che non è più utilizzabile.
WSAECONNRESET	Circuito virtuale reimpostato dal lato remoto durante l'esecuzione di una chiusura definitiva o anomala. L'applicazione deve chiudere il socket che non è più utilizzabile. Nel socket di un datagramma UPD questo errore indica che una precedente operazione di invio ha generato un messaggio ICMP di porta irraggiungibile.
WSAEFAULT	Il parametro buf non è completamente contenuto in una parte valida dello spazio indirizzi utente.
WSAEINPROGRESS	È in corso una chiamata di Windows Sockets 1.1 bloccante oppure il provider di servizi sta ancora elaborando una funzione di callback.
WSAEINTR	La chiamata (bloccante) è stata annullata dalla chiamata WSACancelBlockingCall .
WSAEINVAL	Il socket non è stato associato con binding o è stato specificato un flag sconosciuto oppure MSG_OOB è stato specificato per un socket con SO_OOBINLINE abilitato o (solo per socket di flusso di byte) len era zero o negativo.
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAENETRESET	Per un socket orientato alla connessione, questo errore indica che la connessione è stata interrotta a causa di un'attività keep-alive che ha rilevato un errore durante l'operazione in corso. Per un socket di datagramma, questo errore indica che la durata (TTL) è scaduta.
WSAENOTCONN	Il socket non è connesso.
WSAENOTSOCK	Il descrittore non è un socket.
WSAEOPNOTSUPP	MSG_OOB è stato specificato, ma il socket non è in stile di flusso, ad esempio il tipo SOCK_STREAM, i dati OOB non sono supportati nel dominio di comunicazione associato a questo socket o il socket è unidirezionale e supporta solo le operazioni di invio.
WSAESHUTDOWN	Il socket è stato arrestato; non è possibile usare WSARecvEx in un socket dopo che è stato richiamato l'arresto con come impostare su SD_RECEIVE o SD_BOTH.
WSAETIMEDOUT	Connessione eliminata a causa di un errore di rete o un errore di risposta del sistema peer.
WSAEWOULDBLOCK	Il socket è contrassegnato come non bloccante e l'operazione di ricezione blocca.
WSANOTINITIALISED	Prima di usare questa funzione, è necessario che venga eseguita una chiamata WSAStartup riuscita.

Commenti

La funzione WSARecvEx che fa parte dell'implementazione Microsoft di Windows Sockets 2 è simile alla funzione recv più comune, ad eccezione del fatto che il parametro flags viene usato per un singolo scopo specifico. Il parametro flags viene usato per indicare se viene ricevuto un messaggio parziale o completo quando viene utilizzato un protocollo orientato ai messaggi.

Il valore a cui punta il parametro flags viene ignorato all'input. Non è quindi possibile passare flag alla funzione WSARecvEx per modificarne il comportamento. Il valore a cui punta il parametro flags viene impostato nell'output. Ciò è diverso dalle funzioni recv e WSARecv in cui il valore a cui punta il parametro flags nell'input può modificare il comportamento della funzione.

Le funzioni WSARecvEx e recv si comportano in modo identico per i protocolli orientati ai flussi.

Il parametro flags supporta due situazioni comuni in cui verrà ricevuto un messaggio parziale:

Quando le dimensioni del buffer dei dati dell'applicazione sono inferiori alle dimensioni del messaggio e il messaggio arriva in modo casuale in due parti.
Quando il messaggio è piuttosto grande e deve arrivare in diversi pezzi.

Il bit MSG_PARTIAL viene impostato nel valore a cui punta il parametro flags al momento della restituzione da WSARecvEx quando viene ricevuto un messaggio parziale. Se è stato ricevuto un messaggio completo, MSG_PARTIAL non viene impostato nel valore a cui punta il parametro flags .

La funzione recv è diversa dalla
WSARecvEx e WSARecv funzionano in quanto la funzione recv riceve sempre un singolo messaggio per ogni chiamata per i protocolli di trasporto orientati ai messaggi. La funzione recv non dispone inoltre di un mezzo per indicare all'applicazione che i dati ricevuti sono solo un messaggio parziale. Un'applicazione deve compilare il proprio protocollo per verificare se un messaggio è parziale o completo controllando il codice di errore WSAEMSGSIZE dopo ogni chiamata a recv. Quando il buffer dell'applicazione è inferiore ai dati inviati, gran parte del messaggio che verrà copiato nel buffer dell'utente e restituisce il codice di errore WSAEMSGSIZE. Una chiamata successiva a recv otterrà la parte successiva del messaggio.

Le applicazioni scritte per i protocolli di trasporto orientati ai messaggi devono essere codificate per questa possibilità se il ridimensionamento dei messaggi non è garantito dal protocollo di trasferimento dei dati dell'applicazione. Un'applicazione può usare recv e gestire il protocollo stesso. In alternativa, un'applicazione può usare WSARecvEx e verificare che il bit MSG_PARTIAL sia impostato nel parametro flags .

La funzione WSARecvEx fornisce allo sviluppatore un modo più efficace per verificare se un messaggio ricevuto è parziale o completo quando un messaggio di grandi dimensioni arriva in modo incrementale. Ad esempio, se un'applicazione invia un messaggio a un megabyte, il protocollo di trasporto deve suddividere il messaggio per inviarlo tramite la rete fisica. È teoricamente possibile che il protocollo di trasporto sul lato ricevente memorizzasse nel buffer tutti i dati nel messaggio, ma questo sarebbe piuttosto costoso in termini di risorse. È invece possibile usare WSARecvEx , riducendo al minimo il sovraccarico ed eliminando la necessità di un protocollo basato su applicazioni.

Nota Tutte le operazioni di I/O avviate da un determinato thread vengono annullate quando il thread viene chiuso. Per i socket sovrapposti, le operazioni asincrone in sospeso possono avere esito negativo se il thread viene chiuso prima del completamento delle operazioni. Per altre informazioni, vedere la funzione ExitThread .

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winsock.h (include Mswsock.h)
Libreria	Mswsock.lib
DLL	Mswsock.dll