Funzione di callback LPWSPSENDTO (ws2spi.h)
La funzione LPWSPSendTo invia dati a una destinazione specifica usando l'I/O sovrapposta.
Sintassi
LPWSPSENDTO Lpwspsendto;
int Lpwspsendto(
[in] SOCKET s,
[in] LPWSABUF lpBuffers,
[in] DWORD dwBufferCount,
[out] LPDWORD lpNumberOfBytesSent,
[in] DWORD dwFlags,
[in] const sockaddr *lpTo,
[in] int iTolen,
[in] LPWSAOVERLAPPED lpOverlapped,
[in] LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine,
[in] LPWSATHREADID lpThreadId,
[out] LPINT lpErrno
)
{...}
Parametri
[in] s
Descrittore che identifica un socket.
[in] lpBuffers
Puntatore a una matrice di strutture WSABUF . Ogni struttura WSABUF contiene un puntatore a un buffer e la lunghezza del buffer, in byte. Per un'applicazione Winsock, una volta chiamata la funzione LPWSPSendTo , il sistema possiede questi buffer e l'applicazione potrebbe non accedervi. I buffer di dati a cui si fa riferimento in ogni struttura WSABUF sono di proprietà del sistema e l'applicazione potrebbe non accedervi per la durata della chiamata.
[in] dwBufferCount
Numero di strutture WSABUF nella matrice lpBuffers .
[out] lpNumberOfBytesSent
Puntatore al numero di byte inviati da questa chiamata.
[in] dwFlags
Set di flag che specifica il modo in cui viene effettuata la chiamata.
[in] lpTo
Puntatore facoltativo all'indirizzo del socket di destinazione nella struttura sockaddr .
[in] iTolen
Dimensioni, in byte, dell'indirizzo a cui punta il parametro lpTo .
[in] lpOverlapped
Puntatore a una struttura WSAOverlapped (ignorata per socket non sovrapposti).
[in] lpCompletionRoutine
Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
Puntatore alla routine di completamento chiamata quando l'operazione di invio è stata completata (ignorata per socket non sovrapposti).
[in] lpThreadId
Puntatore a una struttura WSATHREADID da usare dal provider in una chiamata successiva a WPUQueueApc. Il provider deve archiviare la struttura WSATHREADID a cui fa riferimento (non lo stesso puntatore) fino a quando la funzione WPUQueueApc restituisce.
[out] lpErrno
Puntatore al codice di errore.
Valore restituito
Se non si verifica alcun errore e l'operazione di ricezione è stata completata immediatamente, LPWSPSendTo restituisce zero. Si noti che in questo caso la routine di completamento, se specificata, sarà già stata accodata. In caso contrario, viene restituito un valore di SOCKET_ERROR e un codice di errore specifico è disponibile in lpErrno. 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 non è stata avviata alcuna operazione sovrapposta e non si verificherà alcuna indicazione di completamento.
| Codice di errore | Significato |
|---|---|
| Il sottosistema di rete non è riuscito. | |
| L'indirizzo richiesto è un indirizzo di trasmissione, ma il flag appropriato non è stato impostato. | |
| (Blocco) chiamata annullata tramite LPWSPCancelBlockingCall. | |
| Il blocco della chiamata a Windows Sockets è in corso oppure il provider di servizi sta ancora elaborando una funzione di callback. | |
| I parametri lpBuffers o lpTo non fanno parte dello spazio degli indirizzi utente oppure il parametro lpTo è troppo piccolo. | |
| La connessione è stata interrotta a causa dell'attività keep-alive che rileva un errore durante l'operazione in corso. | |
| Il provider Windows Sockets segnala un deadlock del buffer. | |
| Il socket non è connesso (solo socket orientati alla connessione). | |
| Il descrittore non è un socket. | |
| 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, MSG_PARTIAL non è supportato o il socket è unidirectional e supporta solo le operazioni di ricezione. | |
| Il socket è stato arrestato; non è possibile usare LPWSPSendTo in un socket dopo che LPWSPShutdown è stato richiamato con come impostare su SD_SEND o SD_BOTH. | |
| Windows NT: 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. | |
| Socket è orientato al messaggio e il messaggio è maggiore del massimo supportato dal trasporto sottostante. | |
| Il socket non è stato associato a LPWSPBind oppure il socket non viene creato con il flag sovrapposto. | |
| Il circuito virtuale è stato terminato a causa di un timeout o di un altro errore. | |
| Il circuito virtuale è stato reimpostato dal lato remoto. | |
| L'indirizzo remoto non è un indirizzo valido, ad esempio ADDR_ANY. | |
| Impossibile utilizzare gli indirizzi della famiglia specificata con questo socket. | |
| L'indirizzo di destinazione è obbligatorio. | |
| Impossibile raggiungere la rete da questo host in questo momento. | |
| L'operazione sovrapposta è stata annullata a causa della chiusura del socket o dell'esecuzione del comando SIO_FLUSH in LPWSPIoctl. |
Commenti
La funzione LPWSPSendTo viene in genere usata in un socket senza connessione specificata da s per inviare un datagramma contenuto in uno o più buffer a un socket peer specifico identificato dal parametro lpTo . Anche se il socket senza connessione è stato precedentemente connesso a un indirizzo specifico con la funzione LPWSPConnect , lpTo sostituisce l'indirizzo di destinazione solo per quel particolare datagram. In un socket orientato alla connessione i parametri lpTo e iToLen vengono ignorati; in questo caso la funzione LPWSPSendTo equivale a LPWSPSend.
Per i socket sovrapposti (creati usando LPWSPSocket con flag WSA_FLAG_OVERLAPPED) si verificherà l'uso di I/O sovrapposti, a meno che sia lpOverlapped che lpCompletionRoutine siano NULL nel qual caso il socket viene considerato come socket non sovrapposto. Si verificherà un'indicazione di completamento (chiamata della routine di completamento o dell'impostazione di un oggetto evento) quando i buffer forniti sono stati utilizzati dal trasporto. Se l'operazione non viene completata immediatamente, lo stato di completamento finale viene recuperato tramite la routine di completamento o LPWSPGetOverlappedResult.
Per i socket non sovrapposti, i parametri lpOverlapped, lpCompletionRoutine e lpThreadId vengono ignorati e LPWSPSendTo adotta la semantica sincrona regolare. I dati vengono copiati dal buffer fornito nel buffer del trasporto. Se il socket non è bloccato e orientato al flusso e non è disponibile spazio sufficiente nel buffer del trasporto, LPWSPSendTo restituirà solo parte dei buffer del client Windows Sockets SPI che sono stati utilizzati. Data la stessa situazione del buffer e un socket di blocco, LPWSPSendTo bloccherà fino a quando non sono stati usati tutti i contenuti del buffer del client Windows Sockets SPI.
La matrice di strutture WSABUF a cui punta il parametro lpBuffers è temporanea. Se questa operazione viene completata in modo sovrapposto, è responsabilità del provider di servizi acquisire queste strutture WSABUF prima di restituire dalla chiamata. Ciò consente alle applicazioni di creare matrici WSABUF basate su stack.
Per i socket orientati ai messaggi, è necessario prestare attenzione a non superare le dimensioni massime del messaggio del trasporto 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, viene restituito l'errore WSAEMSGSIZE e non vengono trasmessi dati.
Si noti che il completamento riuscito di un LPWSPSendTo non indica che i dati sono stati recapitati correttamente.
Il parametro iFlags può essere usato per influenzare il comportamento della chiamata alla funzione oltre le opzioni specificate per il socket associato. Vale a dire, 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_OOB | Invia dati OOB (socket in stile flusso, ad esempio SOCK_STREAM solo). |
| MSG_PARTIAL | Specifica che lpBuffers contiene solo un messaggio parziale. Si noti che il codice di errore WSAEOPNOTSUPP verrà restituito dai trasporti che non supportano le trasmissioni di messaggi parziali. |
Se un'operazione sovrapposta viene completata immediatamente, LPWSPSendTo restituisce un valore pari a 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, LPWSPSendTo restituisce SOCKET_ERROR e indica il codice di errore WSA_IO_PENDING. In questo caso, lpNumberOfBytesSent non viene aggiornato. Quando l'operazione sovrapposta completa la quantità di dati trasferiti viene indicato tramite il parametro cbTransferred nella routine di completamento (se specificato) o tramite il parametro lpcbTransfer in LPWSPGetOverlappedResult.
I provider devono consentire la chiamata di questa funzione dall'interno della routine di completamento di una funzione LPWSPRecv precedente, LPWSPRecvFrom, LPWSPSend o LPWSPSendTo . Tuttavia, per un determinato socket, non è possibile annidare le routine di completamento di I/O. 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 contemporaneamente in sospeso, ognuna deve fare riferimento a una struttura sovrapposta separata. La struttura WSAOverlapped è definita nella propria pagina di riferimento.
Se il parametro lpCompletionRoutine è Null, il provider di servizi segnala il membro hEvent di lpOverlapped quando l'operazione sovrapposta viene completata se contiene un handle di oggetto evento valido. I client SPI di Windows Sockets possono usare LPWSPGetOverlappedResult per attendere o eseguire il polling nell'oggetto evento.
Se lpCompletionRoutine non è null, il membro hEvent viene ignorato e può essere usato dal client SPI di Windows Sockets per passare le informazioni di contesto alla routine di completamento. Un client che passa una richiesta di I/O non null non nulle successivamente 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 membro hEvent non è definito e il tentativo di attendere il membro hEvent produce risultati imprevedibili.
È responsabilità del provider di servizi organizzare la chiamata della routine di completamento del client specificato al termine dell'operazione sovrapposta. Poiché la routine di completamento deve essere eseguita nel contesto dello stesso thread che ha avviato l'operazione sovrapposta, non può essere richiamata direttamente dal provider di servizi. Il Ws2_32.dll offre un meccanismo di chiamata asincrona (APC) per facilitare la chiamata alle routine di completamento.
Un provider di servizi prevede l'esecuzione di una funzione nel thread appropriato chiamando WPUQueueApc. Questa funzione può essere chiamata da qualsiasi contesto di processo e thread, anche un contesto diverso dal thread e dal processo usato per avviare l'operazione sovrapposta.
La funzione WPUQueueApc accetta come parametri di input un puntatore a una struttura WSATHREADID (fornita al provider tramite il parametro di input lpThreadId ), un puntatore a una funzione APC da richiamare e un valore di contesto che viene successivamente passato alla funzione APC. Poiché solo un singolo valore di contesto è disponibile, la funzione APC stessa non può essere la routine di completamento specificata dal client. Il provider di servizi deve invece fornire un puntatore alla propria funzione APC, che usa il valore di contesto fornito per accedere alle informazioni di risultato necessarie per l'operazione sovrapposta e quindi richiama la routine di completamento specificata dal client.
Il prototipo per la routine di completamento fornita dal client è il seguente.
void CALLBACK
CompletionRoutine(
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
Il completamentoRoutine è un segnaposto per un nome di funzione fornito dal client. dwError specifica lo stato di completamento dell'operazione sovrapposta, come indicato da lpOverlapped. cbTransferred specifica il numero di byte inviati. Non sono attualmente definiti valori flag e il valore dwFlags sarà zero. Questa funzione non restituisce un valore.
Le routine di completamento possono essere chiamate in qualsiasi ordine, anche se non necessariamente nello stesso ordine in cui vengono completate le operazioni sovrapposte. Tuttavia, il provider di servizi garantisce al client che i buffer pubblicati vengono inviati nello stesso ordine specificato.
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 .
Requisiti
| Client minimo supportato | Windows 2000 Professional [solo app desktop] |
| Server minimo supportato | Windows 2000 Server [solo app desktop] |
| Intestazione | ws2spi.h |