Funzione WSARecvEx (mswsock.h)

Articolo
08/25/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 flag viene usato solo per restituire informazioni. Quando viene ricevuto un messaggio parziale durante l'uso del protocollo datagram, il bit di MSG_PARTIAL viene impostato nel parametro flags sulla restituzione dalla funzione.

Nota La funzione WSARecvEx è un'estensione specifica di Microsoft per la specifica 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 è completamente o parzialmente ricevuto per i socket di datagram.

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 di MSG_PARTIAL viene impostato nel parametro flag. Se è stato ricevuto un messaggio completo, MSG_PARTIAL non è impostato nei flag

In caso contrario, viene restituito un valore di SOCKET_ERROR e un codice di errore specifico può essere recuperato chiamando WSAGetLastError.

Importante Per un protocollo di trasporto orientato al flusso, MSG_PARTIAL non viene mai impostato sul ritorno 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 degli indirizzi utente.
WSAEINPROGRESS	Una chiamata windows Sockets 1.1 bloccata è in corso oppure il provider di servizi sta ancora elaborando una funzione di callback.
WSAEINTR	La chiamata (blocco) è stata annullata dalla chiamata WSACancelBlockingCall .
WSAEINVAL	Il socket non è stato associato a binding o è stato specificato un flag sconosciuto o MSG_OOB è stato specificato per un socket con SO_OOBINLINE abilitato o (solo per socket di flusso 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 dell'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 è unidirectional e supporta solo le operazioni di invio.
WSAESHUTDOWN	Il socket è stato arrestato; non è possibile usare WSARecvEx in un socket dopo l'arresto richiamato 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 eseguire 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 unico scopo specifico. Il parametro flag viene usato per indicare se viene ricevuto un messaggio parziale o completo quando viene usato un protocollo orientato ai messaggi.

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

Le funzioni WSARecvEx e recv si comportano in modo identico per i protocolli orientati al flusso.

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

Quando la dimensione del buffer dei dati dell'applicazione è inferiore alla dimensione del messaggio e il messaggio arriva in modo casuale in due parti.
Quando il messaggio è piuttosto grande e deve arrivare in diversi pezzi.

Il MSG_PARTIAL bit viene impostato nel valore a cui fa riferimento il parametro flags su restituito da WSARecvEx quando è stato ricevuto un messaggio parziale. Se è stato ricevuto un messaggio completo, MSG_PARTIAL non è impostato nel valore a cui punta il parametro flags .

La funzione recv è diversa dall'oggetto
Le funzioni WSARecvEx e WSARecv in cui la funzione recv riceve sempre un singolo messaggio per ogni chiamata per i protocolli di trasporto orientati ai messaggi. La funzione recv non include anche mezzi 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 è minore dei dati inviati, la maggior parte del messaggio che verrà copiata nel buffer dell'utente e restituisce con 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 di MSG_PARTIAL sia impostato nel parametro flag .

La funzione WSARecvEx fornisce allo sviluppatore un modo più efficace per verificare se un messaggio ricevuto è parziale o completo quando arriva un messaggio molto grande in modo incrementale. Ad esempio, se un'applicazione invia un messaggio 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 di ricezione bufferi tutti i dati nel messaggio, ma questo sarebbe molto 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 Tutti gli I/O avviati da un determinato thread vengono annullati quando il thread viene chiuso. Per i socket sovrapposti, le operazioni asincrone in sospeso possono non riuscire se il thread viene chiuso prima del completamento delle operazioni. Per altre informazioni, vedere la funzione ExitThread .

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	mswsock.h (includere Mswsock.h)
Libreria	Mswsock.lib
DLL	Mswsock.dll