Funzione WSASendMsg (winsock2.h)

La funzione WSASendMsg invia dati e informazioni di controllo facoltative dai 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 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.

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.

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.

dwFlags

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