Funzione WSASendMsg (winsock2.h)

Articolo
07/16/2024

La funzione WSASendMsg invia dati e informazioni di controllo facoltative dai socket connessi e non connessi.

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

Sintassi

int WSAAPI WSASendMsg(
  [in]  SOCKET                             Handle,
  [in]  LPWSAMSG                           lpMsg,
  [in]  DWORD                              dwFlags,
  [out] LPDWORD                            lpNumberOfBytesSent,
  [in]  LPWSAOVERLAPPED                    lpOverlapped,
  [in]  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

Parametri

[in] Handle

Descrittore che identifica il socket.

[in] lpMsg

Struttura di WSAMSG che archivia la struttura posix.1g msghdr.

[in] dwFlags

Flag usati per modificare il comportamento del WSASendMsg chiamata di funzione. Per altre informazioni, vedere Uso di dwFlags nella sezione Osservazioni.

[out] lpNumberOfBytesSent

Puntatore al numero, in byte, inviato da questa chiamata se l'operazione di I/O viene completata immediatamente.

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

[in] lpOverlapped

Puntatore a una struttura di WSAOVERLAPPED. Ignorato per i socket non sovrapposti.

[in] lpCompletionRoutine

Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Puntatore alla routine di completamento chiamata al completamento dell'operazione di invio. Ignorato per i socket non sovrapposti.

Valore restituito

Restituisce zero quando si verifica l'esito positivo e immediato. Quando viene restituito zero, la routine di completamento specificata viene chiamata quando il thread chiamante si trova nello stato di avviso.

Valore restituito di SOCKET_ERRORe chiamata successiva a WSAGetLastError che restituisce WSA_IO_PENDING, indica che l'operazione sovrapposta è stata avviata correttamente; il completamento viene quindi indicato tramite altri mezzi, ad esempio tramite eventi o porte di completamento.

In caso di errore, restituisce SOCKET_ERROR e una chiamata successiva a WSAGetLastError restituisce un valore diverso da WSA_IO_PENDING. Nella tabella seguente sono elencati i codici di errore.

Codice di errore	Significato
WSAEACCES	L'indirizzo richiesto è un indirizzo di trasmissione, ma il flag appropriato non è stato impostato.
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 lpMsg, lpNumberOfBytesSent, lpOverlappedo lpCompletionRoutine parametro non è completamente contenuto in una parte valida dello spazio indirizzi utente. Questo errore viene restituito anche se un nome membro della struttura di WSAMSG a cui punta il parametro lpMsg era un puntatore NULL e il membro namelen della struttura WSAMS G non è impostato su zero. Questo errore viene restituito anche se un membro Control.buf della struttura WSAMSG a cui punta il parametro lpMsg è un puntatore NULL e il membro Control.len della struttura WSAMSG non è impostato su zero.
WSAEINPROGRESS	È in corso una chiamata di Windows Sockets 1.1 bloccante 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 a bindingoppure il socket non è stato creato con il flag sovrapposto.
WSAEMSGSIZE	Il socket è orientato ai messaggi e il messaggio è maggiore del massimo supportato dal trasporto sottostante.
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAENETRESET	Per un socket di datagrammi, questo errore indica che il tempo di esecuzione è scaduto.
WSAENETUNREACH	La rete non è raggiungibile.
WSAENOBUFS	Il provider Windows Sockets segnala un deadlock del buffer.
WSAENOTCONN	Il socket non è connesso.
WSAENOTSOCK	Il descrittore non è un socket.
WSAEOPNOTSUPP	L'operazione socket non è supportata. Questo errore viene restituito se il dwFlags membro della struttura WSAMSG di a cui punta il parametro lpMsg include eventuali flag di controllo non validi per WSASendMsg.
WSAESHUTDOWN	Il socket è stato arrestato; non è possibile chiamare la funzione di WSASendMsg su un socket dopo arresto è stata richiamata con come impostato su SD_SEND o SD_BOTH.
WSAETIMEDOUT	Timeout del socket. Questo errore viene restituito se il socket ha un timeout di attesa specificato usando l'opzione socket SO_SNDTIMEO e il timeout è stato superato.
WSAEWOULDBLOCK	Socket sovrapposti: sono presenti troppe richieste di I/O sovrapposte in sospeso. Socket non sovrapposti: il socket è contrassegnato come non bloccante e l'operazione di invio non può essere completata immediatamente.
WSANOTINITIALISED	Prima di usare questa funzione, è necessario eseguire una WSAStartup chiamata.
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 o a causa dell'esecuzione del comando SIO_FLUSH in WSAIoctl.

Osservazioni

La funzione WSASendMsg può essere usata al posto delle funzioni WSASend e WSASendTo. La funzione WSASendMsg può essere usata solo con datagrammi e socket non elaborati. Il descrittore socket nel parametro deve essere aperto con il tipo di socket impostato su SOCK_DGRAM o SOCK_RAW.

Il parametro dwFlags può contenere solo una combinazione dei flag di controllo seguenti: MSG_DONTROUTE, MSG_PARTIALe MSG_OOB. Il dwFlags membro della struttura WSAMSG di a cui punta il parametro lpMsg viene ignorato nell'input e non usato nell'output.

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

I socket sovrapposti vengono creati con un WSASocket chiamata di funzione con il flag WSA_FLAG_OVERLAPPED impostato. Per i socket sovrapposti, l'invio di informazioni usa operazioni di I/O sovrapposte, a meno che sia lpOverlapped che lpCompletionRoutine non siano NULL; quando lpOverlapped e lpCompletionRoutine vengono null, il socket viene considerato come socket non sovrapposto. Un'indicazione di completamento si verifica con socket sovrapposti; dopo che il buffer o i buffer sono stati utilizzati 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 non sovrapposti, i lpOverlapped e lpCompletionRoutine vengono ignorati e WSASendMsg adotta la stessa semantica di blocco della funzione send: i dati vengono copiati dal buffer o dai buffer nel buffer del trasporto. Se il socket non è bloccato e orientato al flusso e lo spazio nel buffer del trasporto non è sufficiente, WSASendMsg restituisce solo parte dei buffer dell'applicazione che sono stati utilizzati. Al contrario, questa situazione del buffer in un socket di blocco comporta WSASendMsg blocco fino a quando non viene utilizzato tutto il contenuto del buffer dell'applicazione.

Se questa funzione viene completata in modo sovrapposto, è responsabilità del provider di servizi Winsock acquisire questa struttura di WSABUF prima di tornare da questa chiamata. In questo modo, le applicazioni possono compilare matrici di WSABUF basate su stack a cui punta il membro lpBuffers della struttura WSAMSG a cui punta il parametro lpMsg .

Per i socket orientati ai messaggi, è necessario prestare attenzione a non superare le dimensioni massime del messaggio del provider sottostante, che può essere ottenuto ottenendo il valore dell'opzione socket SO_MAX_MSG_SIZE. Se i dati sono troppo lunghi per passare in modo atomico tramite il protocollo sottostante, viene restituito l'errore WSAEMSGSIZE e non vengono trasmessi dati.

In un socket IPv4 di tipo SOCK_DGRAM o SOCK_RAW, un'applicazione può specificare l'indirizzo di origine IP locale da usare per l'invio con la funzione WSASendMsg. Uno degli oggetti dati del controllo passati nella struttura di WSAMSG all' WSASendMsg può contenere una struttura in_pktinfo utilizzata per specificare l'indirizzo di origine IPv4 locale da usare per l'invio.

In un socket IPv6 di tipo SOCK_DGRAM o SOCK_RAW, un'applicazione può specificare l'indirizzo di origine IP locale da usare per l'invio con la funzione WSASendMsg. Uno degli oggetti dati del controllo passati nella struttura di WSAMSG alla funzione di WSASendMsg può contenere una struttura in6_pktinfo utilizzata per specificare l'indirizzo di origine IPv6 locale da usare per l'invio.

Per un socket a doppio stack quando si inviano datagrammi con la funzione WSASendMsg e un'applicazione vuole specificare un indirizzo di origine IP locale specifico da usare, il metodo per gestirlo dipende dall'indirizzo IP di destinazione. Quando si invia a un indirizzo di destinazione IPv4 o a un indirizzo di destinazione IPv4 mappato a IPv6, uno degli oggetti dati del controllo passati nella struttura WSAMSG a cui punta il parametro lpMsg deve contenere una struttura in_pktinfo contenente l'indirizzo di origine IPv4 locale da usare per l'invio. Quando si invia a un indirizzo di destinazione IPv6 che non è un indirizzo IPv4 mappato a IPv6, uno degli oggetti dati del controllo passati nella struttura WSAMSG punta al parametro lpMsg deve contenere una struttura in6_pktinfo contenente l'indirizzo di origine IPv6 locale da usare per l'invio.

Nota L'opzione socket SO_SNDTIMEO si applica solo ai socket bloccanti.

Nota Il completamento di un WSASendMsg di non indica che i dati sono stati recapitati correttamente.

Nota Quando si esegue una chiamata Winsock bloccante, ad esempio WSASendMsg con il parametro lpOverlapped impostato su NULL, Winsock potrebbe dover attendere il completamento di un evento di rete prima del completamento della chiamata. 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 comporterà un comportamento non definito e non deve mai essere tentata dai client Winsock.

dwFlags

Il dwFlags parametro di input può essere usato per influenzare il comportamento della chiamata della funzione oltre le opzioni specificate per il socket associato. Ovvero, la semantica di questa funzione è determinata dalle opzioni socket e dal parametro dwFlags . Quest'ultimo viene costruito usando l'operatore OR bit per bit con uno dei valori seguenti.

Valore	Significato
MSG_DONTROUTE	Specifica che i dati non devono essere soggetti al routing. Un provider di servizi Windows Sockets può scegliere di ignorare questo flag.
MSG_PARTIAL	Specifica che lpMsg->lpBuffers contiene solo un messaggio parziale. Si noti che il codice di errore WSAEOPNOTSUPP verrà restituito dai trasporti che non supportano le trasmissioni parziali dei messaggi.

I valori possibili per parametro dwFlags sono definiti nel file di intestazione Winsock2.h.

In output, il dwFlags membro della struttura di WSAMSG a cui punta il parametro lpMsg .

I/O socket sovrapposto

Se un'operazione sovrapposta viene completata immediatamente, WSASendMsg restituisce un valore zero e il parametro lpNumberOfBytesSent viene aggiornato con il numero di byte inviati. Se l'operazione sovrapposta viene avviata correttamente e verrà completata in un secondo momento, WSASendMsg restituisce SOCKET_ERROR e indica il codice di errore WSA_IO_PENDING. In questo caso, lpNumberOfBytesSent 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.

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

La funzione WSASendMsg tramite operazioni di I/O sovrapposte può essere chiamata dall'interno della routine di completamento di un precedente , WSARecv, WSARecvFrom, LPFN_WSARECVMSG(WSARecvMsg), WSASend, WSASendMsgo funzione WSASendTo. In questo modo, le trasmissioni di dati sensibili al tempo vengono eseguite interamente all'interno di un contesto preemptivo.

Il parametro lpOverlapped deve essere valido per la durata dell'operazione sovrapposta. Se più operazioni di I/O sono in sospeso contemporaneamente, ognuna deve fare riferimento a una struttura di 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 utilizzato dall'applicazione per passare le informazioni di contesto alla routine di completamento. Un chiamante che passa unNULLlpCompletionRoutine e successive chiama WSAGetOverlappedRes ult per la stessa richiesta di I/O sovrapposta potrebbe non impostare il parametro fWait per tale chiamata di WSAGetOverlappedResultResult per TRUE. In questo caso, l'utilizzo del parametro hEvent non è definito e il tentativo di attendere il parametro hEvent genera 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 si trova in uno stato di attesa avvisabile, ad esempio con WSAWaitForMultipleEvents chiamato con il parametro fAlertable impostato su TRUE.

I provider di trasporto consentono a un'applicazione di richiamare operazioni di invio e ricezione dall'interno del contesto della routine di completamento di I/O socket e garantire che, 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 preemptivo.

Il prototipo della routine di completamento è il seguente.


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

La funzione 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 indica il numero di byte inviati. Attualmente non sono definiti valori di flag e il parametro dwFlags sarà zero. La funzione CompletionRoutine non restituisce un valore.

La restituzione da questa funzione consente la chiamata di un'altra routine di completamento in sospeso per il socket. Tutte le routine di completamento in attesa vengono chiamate prima che l'attesa del thread avvisabile sia 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 inviati nello stesso ordine in cui sono specificati.

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.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 8.1, Windows Vista [app desktop \| App UWP]
server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
piattaforma di destinazione	Finestre
intestazione	winsock2.h (include Mswsock.h)
libreria	Ws2_32.lib
dll	Ws2_32.dll