LPFN_WSARECVMSG funzione di callback (mswsock.h)

Articolo
08/25/2023

LPFN_WSARECVMSG è un tipo di puntatore alla funzione. Si implementa una funzione di callback WSARecvMsg corrispondente nell'app. Il sistema usa la funzione di callback per trasmettere i dati in memoria o i dati dei file tramite un socket connesso.

La funzione di callback WSARecvMsg riceve informazioni di controllo/dati ausiliari con un messaggio, da socket connessi e non connessi.

Nota

Questa funzione è un'estensione specifica di Microsoft per la specifica Windows Sockets.

Sintassi

LPFN_WSARECVMSG LpfnWsarecvmsg;

INT LpfnWsarecvmsg(
  SOCKET s,
  LPWSAMSG lpMsg,
  LPDWORD lpdwNumberOfBytesRecvd,
  LPWSAOVERLAPPED lpOverlapped,
  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
)
{...}

Parametri

s

Tipo: _In_ SOCKET

Descrittore che identifica il socket.

lpMsg

Tipo: _Inout_ LPWSAMSG

Puntatore a una struttura WSAMSG basata sulla specifica Posix.1g per la struttura msghdr.

lpdwNumberOfBytesRecvd

Tipo: _Out_opt_ LPDWORD

Puntatore a un DWORD contenente il numero di byte ricevuti da questa chiamata se l'operazione WSARecvMsg viene completata immediatamente.

Per evitare risultati potenzialmente errati, passare NULL per questo parametro se il parametro lpOverlapped non è NULL . Questo parametro può essere NULL solo se il parametro lpOverlapped non è NULL.

lpOverlapped

Tipo: _Inout_opt_ LPWSAOVERLAPPED

Puntatore a una struttura WSAOVERLAPPED . Ignorato per strutture non sovrapposte.

lpCompletionRoutine

Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Puntatore alla routine di completamento chiamata al completamento dell'operazione di ricezione. Ignorato per strutture non sovrapposte.

Valore restituito

Se non si verifica alcun errore e l'operazione di ricezione è stata completata immediatamente, WSARecvMsg restituisce zero. In questo caso, la routine di completamento sarà già stata pianificata per essere chiamata una volta che il thread chiamante si trova nello stato avvisabile. In caso contrario, viene restituito un valore di SOCKET_ERROR e un codice di errore specifico può essere recuperato chiamando WSAGetLastError. Il codice di errore WSA_IO_PENDING indica che l'operazione sovrapposta è stata avviata correttamente e che il completamento verrà indicato in un secondo momento.

Qualsiasi altro codice di errore indica che l'operazione non è stata avviata correttamente e non si verificherà alcuna indicazione di completamento se è stata richiesta un'operazione sovrapposta.

Codice di errore	Significato
WSAECONNRESET	Per un socket di datagrammi UDP, questo errore indica che un'operazione di invio precedente ha generato un messaggio ICMP "Port Unreachable".
WSAEFAULT	Il parametro lpBuffers, lpFlags, lpFrom, lpNumberOfBytesRecvd, lpFromlen, lpOverlapped o lpCompletionRoutine non è totalmente contenuto in una parte valida dello spazio indirizzi utente: il buffer lpFrom era troppo piccolo per ospitare l'indirizzo peer. Questo errore viene restituito anche se un membro del nome della struttura WSAMSG puntato al parametro lpMsg è un puntatore NULL e il membro namelen della struttura WSAMSG non è stato impostato su zero. Questo errore viene restituito anche se un membro Control.buf della struttura WSAMSG puntato al parametro lpMsg era un puntatore NULL e il membro Control.len della struttura WSAMSG non è stato impostato su zero.
WSAEINPROGRESS	Una chiamata windows Sockets 1.1 bloccata è in corso oppure il provider di servizi sta ancora elaborando una funzione di callback.
WSAEINTR	Una chiamata di Windows Socket 1.1 bloccata è stata annullata tramite WSACancelBlockingCall.
WSAEINVAL	Il socket non è stato associato (ad esempio con binding).
WSAEMSGSIZE	Il messaggio era troppo grande per adattarsi al buffer specificato e (solo per protocolli non affidabili) qualsiasi parte finale del messaggio che non è stata adattata al buffer è stata eliminata.
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAENETRESET	Per un socket di datagramma, questo errore indica che la durata (TTL) è scaduta.
WSAENOTCONN	Il socket non è connesso (solo socket orientati alla connessione).
WSAETIMEDOUT	Timeout del socket. Questo errore viene restituito se il socket ha un timeout di attesa specificato usando l'opzione socket SO_RCVTIMEO e il timeout è stato superato.
WSAEOPNOTSUPP	L'operazione socket non è supportata. Questo errore viene restituito se il membro dwFlags della struttura WSAMSG puntato al parametro lpMsg include il flag di controllo MSG_PEEK in un socket non datagram.
WSAEWOULDBLOCK	Windows NT: Socket sovrapposti: sono presenti troppe richieste di I/O in sospeso. Socket non sovrapposti: il socket viene contrassegnato come non sbloccante e l'operazione di ricezione non può essere completata immediatamente.
WSANOTINITIALISED	Prima di usare questa funzione, è necessario eseguire una chiamata WSAStartup riuscita.
WSA_IO_PENDING	Un'operazione sovrapposta è stata avviata correttamente e il completamento verrà indicato in un secondo momento.
WSA_OPERATION_ABORTED	L'operazione sovrapposta è stata annullata a causa della chiusura del socket.

Commenti

La funzione WSARecvMsg può essere usata al posto delle funzioni WSARecv e WSARecvFrom per ricevere informazioni di controllo e dati facoltativi da socket connessi e non connessi. La funzione WSARecvMsg può essere usata solo con datagrammi e socket non elaborati. Il descrittore socket nel parametro s deve essere aperto con il tipo di socket impostato su SOCK_DGRAM o SOCK_RAW.

Nota Il puntatore della funzione per la funzione WSARecvMsg deve essere ottenuto in fase di esecuzione eseguendo una chiamata alla funzione WSAIoctl con il codice opcode SIO_GET_EXTENSION_FUNCTION_POINTER specificato. Il buffer di input passato alla funzione WSAIoctl deve contenere WSAID_WSARECVMSG, un identificatore univoco globale (GUID) il cui valore identifica la funzione di estensione WSARecvMsg . In caso di esito positivo, l'output restituito dalla funzione WSAIoctl contiene un puntatore alla funzione WSARecvMsg . Il GUID WSAID_WSARECVMSG è definito nel file di intestazione Mswsock.h .

Il membro dwFlags della struttura WSAMSG a cui punta il parametro lpMsg può contenere solo il flag di controllo MSG_PEEK sull'input.

I socket sovrapposti vengono creati con una chiamata di funzione WSASocket con il flag WSA_FLAG_OVERLAPPED impostato. Per i socket sovrapposti, la ricezione di informazioni usa operazioni di I/O sovrapposte, a meno che i parametri lpOverlapped e lpCompletionRoutine siano NULL. Il socket viene considerato come socket non sovrapposto quando i parametri lpOverlapped e lpCompletionRoutine sono NULL.

Un'indicazione di completamento si verifica con socket sovrapposti. Dopo aver utilizzato il buffer o i buffer dal trasporto, viene attivata una routine di completamento o viene impostato un oggetto evento. Se l'operazione non viene completata immediatamente, lo stato di completamento finale viene recuperato tramite la routine di completamento o chiamando la funzione WSAGetOverlappedResult .

Per i socket sovrapposti, WSARecvMsg viene usato per pubblicare uno o più buffer in cui i dati in ingresso verranno inseriti quando diventano disponibili, dopo il quale si verifica l'indicazione di completamento specificata dall'applicazione (chiamata della routine di completamento o dell'impostazione di un oggetto evento). Se l'operazione non viene completata immediatamente, lo stato di completamento finale viene recuperato tramite la routine di completamento o la funzione WSAGetOverlappedResult .

Per i socket non sovrapposti, la semantica di blocco è identica a quella della funzione recv standard e i parametri lpOverlapped e lpCompletionRoutine vengono ignorati. Tutti i dati già ricevuti e memorizzati nel buffer dal trasporto verranno copiati nei buffer utente specificati. Nel caso di un socket di blocco senza dati attualmente ricevuti e memorizzati nel buffer dal trasporto, la chiamata bloccherà fino alla ricezione dei dati. Windows Sockets 2 non definisce alcun meccanismo di timeout di blocco standard per questa funzione. Per i protocolli che agiscono come protocolli di byte-stream, lo stack tenta di restituire il maggior numero possibile di dati soggetti allo spazio del buffer disponibile e alla quantità di dati ricevuti disponibili. Tuttavia, la ricezione di un singolo byte è sufficiente per sbloccare il chiamante. Non vi è alcuna garanzia che verrà restituito più di un singolo byte. Per i protocolli che fungono da messaggio orientato al messaggio, è necessario sbloccare il chiamante.

Nota L'opzione socket SO_RCVTIMEO si applica solo ai socket di blocco.

I buffer vengono compilati nell'ordine in cui vengono visualizzati nella matrice puntati dal membro lpBuffers della struttura WSAMSG a cui punta il parametro lpMsg e i buffer vengono compressi in modo che non vengano creati fori.

Se questa funzione viene completata in modo sovrapposto, è responsabilità del provider di servizi Winsock acquisire questa struttura WSABUF prima di restituire dalla chiamata. Ciò consente alle applicazioni di creare matrici WSABUF basate sullo stack puntate dal membro lpBuffers della struttura WSAMSG a cui punta il parametro lpMsg .

Per i socket orientati ai messaggi (un tipo di socket di SOCK_DGRAM o SOCK_RAW), un messaggio in ingresso viene inserito nei buffer fino alle dimensioni totali dei buffer e l'indicazione di completamento si verifica per i socket sovrapposti. Se il messaggio è maggiore dei buffer, i buffer vengono riempiti con la prima parte del messaggio e i dati in eccesso vengono persi e WSARecvMsg genera l'errore WSAEMSGSIZE.

Quando l'opzione socket IP_PKTINFO è abilitata in un socket IPv4 di tipo SOCK_DGRAM o SOCK_RAW, la funzione WSARecvMsg restituisce informazioni sui pacchetti nella struttura WSAMSG a cui punta il parametro lpMsg . Uno degli oggetti dati del controllo nella struttura WSAMSG restituita conterrà una struttura in_pktinfo utilizzata per archiviare le informazioni sull'indirizzo del pacchetto ricevuto.

Per i datagrammi ricevuti su IPv4, il membro Control della struttura WSAMSG ricevuta conterrà una struttura WSABUF che contiene una struttura WSACMSGHDR . Il membro cmsg_level di questa struttura WSACMSGHDR conterrà IPPROTO_IP, il membro cmsg_type di questa struttura conterrà IP_PKTINFO e il membro cmsg_data conterrà una struttura in_pktinfo utilizzata per archiviare le informazioni sull'indirizzo del pacchetto IPv4 ricevuto. L'indirizzo IPv4 nella struttura in_pktinfo è l'indirizzo IPv4 da cui è stato ricevuto il pacchetto.

Quando l'opzione socket IPV6_PKTINFO è abilitata in un socket IPv6 di tipo SOCK_DGRAM o SOCK_RAW, la funzione WSARecvMsg restituisce informazioni sui pacchetti nella struttura WSAMSG a cui punta il parametro lpMsg . Uno degli oggetti dati del controllo nella struttura WSAMSG restituita conterrà una struttura in6_pktinfo utilizzata per archiviare le informazioni sull'indirizzo del pacchetto ricevuto.

Per i datagrammi ricevuti su IPv6, il membro Control della struttura WSAMSG ricevuta conterrà una struttura WSABUF che contiene una struttura WSACMSGHDR . Il membro cmsg_level di questa struttura WSACMSGHDR conterrà IPPROTO_IPV6, il membro cmsg_type di questa struttura conterrà IPV6_PKTINFO e il membro cmsg_data conterrà una struttura in6_pktinfo utilizzata per archiviare le informazioni sull'indirizzo del pacchetto IPv6 ricevuto. L'indirizzo IPv6 nella struttura in6_pktinfo è l'indirizzo IPv6 da cui è stato ricevuto il pacchetto.

Per un socket di datagrammi dual stack, se un'applicazione richiede che la funzione WSARecvMsg restituisca informazioni sui pacchetti in una struttura WSAMSG per i datagrammi ricevuti su IPv4, IP_PKTINFO'opzione socket deve essere impostata su true nel socket. Se solo l'opzione IPV6_PKTINFO è impostata su true nel socket, le informazioni sui pacchetti verranno fornite per i datagrammi ricevuti su IPv6, ma potrebbero non essere fornite per i datagrammi ricevuti su IPv4.

Si noti che il file di intestazione Ws2ipdef.h viene automaticamente incluso in Ws2tcpip.h e non deve mai essere usato direttamente.

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 ExitThread.

Windows Phone 8: questa funzione è supportata per le app dello Store di Windows Phone in Windows Phone 8 e versioni successive.

Windows 8.1 e Windows Server 2012 R2: questa funzione è supportata per le app di Windows Store in Windows 8.1, Windows Server 2012 R2 e versioni successive.

dwFlags

In input, il membro dwFlags della struttura WSAMSG a cui punta il parametro lpMsg può essere usato per influenzare il comportamento della chiamata di funzione oltre le opzioni socket specificate per il socket associato. Ovvero, la semantica di questa funzione è determinata dalle opzioni del socket e dal membro dwFlags della struttura WSAMSG . L'unico valore di input possibile per il membro dwFlags della struttura WSAMSG a cui punta il parametro lpMsg è MSG_PEEK.

Valore	Significato
MSG_PEEK	Anteprima rapida ai dati in ingresso. I dati vengono copiati nel buffer, ma non vengono rimossi dalla coda di input. Questo flag è valido solo per i socket non sovrapposti.

I valori possibili per il membro dwFlags nell'input vengono definiti nel file di intestazione Winsock2.h .

Nell'output, il membro dwFlags della struttura WSAMSG a cui punta il parametro lpMsg può restituire una combinazione di uno dei valori seguenti.

Valore	Significato
MSG_BCAST	Il datagramma è stato ricevuto come trasmissione a livello di collegamento o con un indirizzo IP di destinazione che è un indirizzo broadcast.
MSG_CTRUNC	I dati di controllo (ausiliari) sono stati troncati. Sono stati presenti più dati di controllo rispetto alla sala allocata dal processo.
MSG_MCAST	Il datagram è stato ricevuto con un indirizzo IP di destinazione che è un indirizzo multicast.
MSG_TRUNC	Il datagramma è stato troncato. Sono stati presenti più dati rispetto alla sala allocata dal processo.

In Microsoft Windows Software Development Kit (Windows SDK) (SDK) rilasciato per Windows Vista e versioni successive, l'organizzazione dei file di intestazione è stata modificata e i possibili valori per il membro dwFlags nell'output sono definiti nel file di intestazione Ws2def.h che viene automaticamente incluso dal file di intestazione Winsock2.h.

Nelle versioni di Platform Software Development Kit (SDK) per Windows Server 2003 e versioni precedenti, i valori possibili per il membro dwFlags nell'output sono definiti nel file di intestazione Mswsock.h .

Nota Quando si esegue una chiamata Winsock bloccante, ad esempio WSARecvMsg con il parametro lpOverlapped impostato su NULL, Winsock potrebbe dover attendere il completamento di un evento di rete prima che la chiamata possa essere completata. Winsock esegue un'attesa avvisabile in questa situazione, che può essere interrotta da una chiamata di procedura asincrona pianificata nello stesso thread. L'esecuzione di un'altra chiamata Winsock bloccante all'interno di un APC che ha interrotto una chiamata winsock in corso sullo stesso thread causerà un comportamento non definito e non deve mai essere tentata dai client Winsock.

I/O del socket sovrapposto

Se un'operazione sovrapposta viene completata immediatamente, WSARecvMsg restituisce un valore zero e il parametro lpNumberOfBytesRecvd viene aggiornato con il numero di byte ricevuti e vengono aggiornati anche i bit di flag indicati dal parametro lpFlags . Se l'operazione sovrapposta viene avviata correttamente e verrà completata in un secondo momento, WSARecvMsg restituisce SOCKET_ERROR e indica il codice di errore WSA_IO_PENDING. In questo caso , lpNumberOfBytesRecvd non viene aggiornato. Al termine dell'operazione sovrapposta, la quantità di dati trasferiti viene indicata tramite il parametro cbTransferred nella routine di completamento (se specificato) o tramite il parametro lpcbTransfer in WSAGetOverlappedResult. I valori flag vengono ottenuti esaminando il parametro lpdwFlags di WSAGetOverlappedResult.

La funzione WSARecvMsg che usa operazioni di I/O sovrapposte può essere chiamata dall'interno della routine di completamento di una funzione WSARecv, WSARecvFrom, WSARecvMsg, WSASend, WSASendMsg o WSASendTo . Per un determinato socket, le routine di completamento di I/O non verranno annidate. In questo modo le trasmissioni di dati sensibili al tempo vengono eseguite interamente all'interno di un contesto preemptive.

Il parametro lpOverlapped deve essere valido per la durata dell'operazione sovrapposta. Se più operazioni di I/O sono in attesa simultaneamente, ognuna deve fare riferimento a una struttura WSAOVERLAPPED separata.

Se il parametro lpCompletionRoutine è NULL, il parametro hEvent di lpOverlapped viene segnalato quando l'operazione sovrapposta viene completata se contiene un handle di oggetto evento valido. Un'applicazione può usare WSAWaitForMultipleEvents o WSAGetOverlappedResult per attendere o eseguire il polling sull'oggetto evento.

Se lpCompletionRoutine non è NULL, il parametro hEvent viene ignorato e può essere usato dall'applicazione per passare le informazioni di contesto alla routine di completamento. Un chiamante che passa una richiesta di I/O non NULLlpCompletionRoutine e successive chiama WSAGetOverlappedResult per la stessa richiesta di I/O sovrapposta potrebbe non impostare il parametro fWait per tale chiamata di WSAGetOverlappedResult su TRUE. In questo caso l'utilizzo del parametro hEvent non è definito e il tentativo di attendere il parametro hEvent produrrebbe risultati imprevedibili.

La routine di completamento segue le stesse regole previste per le routine di completamento di I/O dei file di Windows. La routine di completamento non verrà richiamata finché il thread non è in uno stato di attesa di avviso, ad esempio quando viene richiamata la funzione WSAWaitForMultipleEvents con il parametro fAlertable impostato su TRUE .

Il prototipo della routine di completamento è il seguente:


void CALLBACK CompletionRoutine(
  IN DWORD dwError, 
  IN DWORD cbTransferred, 
  IN LPWSAOVERLAPPED lpOverlapped, 
  IN DWORD dwFlags
);

CompletionRoutine è un segnaposto per un nome di funzione definito dall'applicazione o definito dalla libreria. Il parametro dwError specifica lo stato di completamento per l'operazione sovrapposta, come indicato dal parametro lpOverlapped . Il parametro cbTransferred specifica il numero di byte ricevuti. Il parametro dwFlags contiene informazioni restituite anche nel membro dwFlags della struttura WSAMSG a cui punta il parametro lpMsg se l'operazione di ricezione è stata completata immediatamente. La funzione CompletionRoutine non restituisce un valore.

La restituzione da questa funzione consente la chiamata di un'altra routine di completamento in sospeso per questo socket. Quando si usa WSAWaitForMultipleEvents, tutte le routine di completamento in attesa vengono chiamate prima che l'attesa del thread di avviso venga soddisfatta con un codice restituito di WSA_IO_COMPLETION. Le routine di completamento possono essere chiamate in qualsiasi ordine, non necessariamente nello stesso ordine in cui vengono completate le operazioni sovrapposte. Tuttavia, è garantito che i buffer inviati vengano compilati nello stesso ordine in cui sono specificati.

Se si usano porte di completamento di I/O, tenere presente che l'ordine delle chiamate effettuate a WSARecvMsg è anche l'ordine in cui vengono popolati i buffer. La funzione WSARecvMsg non deve essere chiamata contemporaneamente sullo stesso socket da thread diversi, perché può comportare un ordine di buffer imprevedibile.