Funzione WSASendMsg (winsock2.h)
La funzione WSASendMsg invia informazioni di controllo e dati facoltativi da socket connessi e non connessi.
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 WSAMSG che archivia la struttura posix.1g msghdr .
[in] dwFlags
I flag usati per modificare il comportamento della chiamata di funzione WSASendMsg . 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 non è NULL.
[in] lpOverlapped
Puntatore a una struttura WSAOVERLAPPED . Ignorato per 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 socket non sovrapposti.
Valore restituito
Restituisce zero quando si verifica il completamento positivo e immediato. Quando viene restituito zero, la routine di completamento specificata viene chiamata quando il thread chiamante si trova nello stato avvisabile.
Valore restituito di SOCKET_ERROR e 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 |
|---|---|
| L'indirizzo richiesto è un indirizzo di trasmissione, ma il flag appropriato non è stato impostato. | |
| Per un socket di datagrammi UDP, questo errore indica che un'operazione di invio precedente ha generato un messaggio ICMP "Port Unreachable". | |
| Il parametro lpMsg, lpNumberOfBytesSent, lpOverlapped o lpCompletionRoutine non è totalmente contenuto in una parte valida dello spazio indirizzi utente. 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. | |
| Una chiamata windows Sockets 1.1 bloccata è in corso oppure il provider di servizi sta ancora elaborando una funzione di callback. | |
| Una chiamata di Windows Socket 1.1 bloccata è stata annullata tramite WSACancelBlockingCall. | |
| Il socket non è stato associato all'associazione oppure il socket non è stato creato con il flag sovrapposto. | |
| Il socket è orientato al messaggio e il messaggio è maggiore del massimo supportato dal trasporto sottostante. | |
| Il sottosistema di rete non è riuscito. | |
| Per un socket di datagramma, questo errore indica che la durata (TTL) è scaduta. | |
| La rete non è raggiungibile. | |
| Il provider Windows Sockets segnala un deadlock del buffer. | |
| Il socket non è connesso. | |
| Il descrittore non è un socket. | |
| L'operazione socket non è supportata. Questo errore viene restituito se il membro dwFlags della struttura WSAMSG puntato al parametro lpMsg include eventuali flag di controllo non validi per WSASendMsg. | |
| Il socket è stato arrestato; non è possibile chiamare la funzione WSASendMsg in un socket dopo l'arresto richiamato con come impostare su SD_SEND o SD_BOTH. | |
| 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. | |
| Socket sovrapposti: sono presenti troppe richieste di I/O in sospeso. Socket non sovrapposti: il socket è contrassegnato come non bloccante e l'operazione di invio non può essere completata immediatamente. | |
| Prima di usare questa funzione, è necessario eseguire una chiamata WSAStartup riuscita. | |
| Un'operazione sovrapposta è stata avviata correttamente e il completamento verrà indicato in un secondo momento. | |
| L'operazione sovrapposta è stata annullata a causa della chiusura del socket o a causa dell'esecuzione del comando SIO_FLUSH in WSAIoctl. |
Commenti
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 s 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_PARTIAL e MSG_OOB. Il membro dwFlags della struttura WSAMSG a cui punta il parametro lpMsg viene ignorato nell'input e non usato nell'output.
I socket sovrapposti vengono creati con una chiamata di funzione WSASocket 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 siano NULL; quando lpOverlapped e lpCompletionRoutine sono NULL, il socket viene considerato come socket non sovrapposto. Un'indicazione di completamento si verifica con socket sovrapposti; una volta 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 parametri lpOverlapped e lpCompletionRoutine vengono ignorati e WSASendMsg adotta la stessa semantica di blocco della funzione di invio : i dati vengono copiati dal buffer o dai buffer nel buffer del trasporto. Se il socket non è bloccato e orientato al flusso e non è disponibile spazio nel buffer del trasporto, WSASendMsg restituisce con solo parte dei buffer dell'applicazione che sono stati utilizzati. Al contrario, questa situazione di buffer in un socket di blocco comporta il blocco di WSASendMsg fino a quando non è stato 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 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, è 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 atomicamente attraverso il protocollo sottostante, l'errore WSAEMSGSIZE viene restituito 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 di controllo passati nella struttura WSAMSG alla funzione 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 di controllo passati nella struttura WSAMSG alla funzione WSASendMsg può contenere una struttura in6_pktinfo utilizzata per specificare l'indirizzo di origine IPv6 locale da usare per l'invio.
Per un socket dual stack durante l'invio di datagrammi con la funzione WSASendMsg e un'applicazione vuole specificare un indirizzo di origine IP locale specifico da usare, il metodo da gestire dipende dall'indirizzo IP di destinazione. Quando si invia a un indirizzo di destinazione IPv4 o a un indirizzo di destinazione IPv4 mappato a IPv4, uno degli oggetti dati di 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 APv6, uno degli oggetti dati del controllo passati nella struttura WSAMSG a cui punta il parametro lpMsg deve contenere una struttura in6_pktinfo contenente l'indirizzo di origine IPv6 locale da usare per l'invio.
Dwflags
Il parametro di input dwFlags può essere usato per influenzare il comportamento della chiamata di funzione oltre le opzioni specificate per il socket associato. Ovvero, la semantica di questa funzione è determinata dalle opzioni del 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. |
Nell'output, il membro dwFlags della struttura WSAMSG a cui punta il parametro lpMsg non viene usato.
I/O del 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.La funzione WSASendMsg che usa operazioni di I/O sovrapposte può essere chiamata dalla routine di completamento di una funzione precedente, WSARecv, WSARecvFrom, LPFN_WSARECVMSG (WSARecvMsg),WSASend, WSASendMsg o WSASendTo . 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 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 I/O del 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 preemptive.
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 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 inviati nello stesso ordine in cui vengono 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.
Requisiti
| 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 | Windows |
| Intestazione | winsock2.h (include Mswsock.h) |
| Libreria | Ws2_32.lib |
| DLL | Ws2_32.dll |
Vedi anche
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per