Funzione di callback LPWSPSEND (ws2spi.h)
La funzione LPWSPSend invia dati su un socket connesso.
Sintassi
LPWSPSEND Lpwspsend;
int Lpwspsend(
[in] SOCKET s,
[in] LPWSABUF lpBuffers,
[in] DWORD dwBufferCount,
[out] LPDWORD lpNumberOfBytesSent,
[in] DWORD dwFlags,
[in] LPWSAOVERLAPPED lpOverlapped,
[in] LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine,
[in] LPWSATHREADID lpThreadId,
[out] LPINT lpErrno
)
{...}
Parametri
[in] s
Descrittore che identifica un socket connesso.
[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 LPWSPSend , il sistema è proprietario di 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 tutta 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] lpOverlapped
Puntatore a una struttura WSAOverlapped (ignorata per i 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 i 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 si fa riferimento (non il puntatore allo stesso) fino a quando non viene restituita la funzione WPUQueueApc .
[out] lpErrno
Puntatore al codice di errore.
Valore restituito
Se non si verifica alcun errore e l'operazione di invio è stata completata immediatamente, LPWSPSend 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 in lpErrno è disponibile un codice di errore specifico. 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 che non si verificherà alcuna indicazione di completamento.
| Codice di errore | Significato |
|---|---|
| Il sottosistema di rete non è riuscito. | |
| L'indirizzo richiesto è un indirizzo broadcast, ma il flag appropriato non è stato impostato. | |
| Il blocco della chiamata a Windows Sockets è in corso oppure il provider di servizi sta ancora elaborando una funzione di callback. | |
| Il parametro lpBuffers non è totalmente contenuto in una parte valida dello spazio indirizzi utente. | |
| La connessione è stata interrotta a causa della reimpostazione dell'host remoto. | |
| La connessione è stata interrotta a causa dell'attività keep-alive che rileva un errore durante l'operazione in corso. | |
| Socket non connesso. | |
| Il descrittore non è un socket. | |
| MSG_OOB è stato specificato, ma il socket non è in stile 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 è unidirezionale e supporta solo le operazioni di ricezione. | |
| Il socket è stato arrestato; non è possibile eseguire LPWSPSend su 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 sovrapposte in sospeso. Socket non sovrapposti: il socket è contrassegnato come non bloccante e l'operazione di invio non può essere completata immediatamente. | |
| Socket è orientato ai messaggi 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'operazione sovrapposta è stata annullata a causa della chiusura del socket o dell'esecuzione del comando SIO_FLUSH in LPWSPIoctl. |
Commenti
La funzione LPWSPSend viene usata per scrivere dati in uscita da uno o più buffer in un socket orientato alla connessione specificato da s. Può essere usato anche nei socket senza connessione che hanno un indirizzo peer predefinito stabilito tramite la funzione LPWSPConnect .
Per i socket sovrapposti (creati con LPWSPSocket con flag WSA_FLAG_OVERLAPPED), questo si verifica usando operazioni di I/O sovrapposte, a meno che sia lpOverlapped che lpCompletionRoutine siano Null nel qual caso il socket viene considerato come un 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 LPWSPSend adotta la normale semantica sincrona. I dati vengono copiati dai buffer forniti nel buffer del trasporto. Se il socket non è orientato a blocchi e flusso e non è disponibile spazio sufficiente nel buffer del trasporto, LPWSPSend restituirà solo parte dei buffer forniti che sono stati utilizzati. Data la stessa situazione del buffer e un socket di blocco, LPWSPSend bloccherà fino a quando non saranno stati utilizzati tutti i contenuti del buffer forniti.
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 da questa chiamata. Ciò consente alle applicazioni di compilare matrici WSABUF basate su stack.
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 tramite il protocollo sottostante, viene restituito l'errore WSAEMSGSIZE e non vengono trasmessi dati.
Si noti che il completamento corretto di un LPWSPSend non indica che i dati sono stati recapitati correttamente.
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_OOB | Invia dati OOB (socket in stile flusso, ad esempio solo SOCK_STREAM). |
| MSG_PARTIAL | Specifica che lpBuffers contiene solo un messaggio parziale. Si noti che il codice di errore WSAEOPNOTSUPP verrà restituito per i messaggi che non supportano le trasmissioni parziali dei messaggi. |
Se un'operazione sovrapposta viene completata immediatamente, LPWSPSend 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, LPWSPSend 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 indicata 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, LPWSPRecvFrom, LPWSPSend o LPWSPSendTo precedente. Tuttavia, per un determinato socket, le routine di completamento di I/O non possono essere 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 sovrapposta separata. La struttura WSAOverlapped è definita nella relativa 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. Il client SPI Windows Sockets può usare LPWSPGetOverlappedResult per attendere o eseguire il polling sull'oggetto evento.
Se lpCompletionRoutine non è Null, il membro hEvent viene ignorato e può essere usato dal client SPI Windows Sockets per passare le informazioni di contesto alla routine di completamento. Un client che passa un lpCompletionRoutine non null 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 membro hEvent non è definito e il tentativo di attendere il membro hEvent produrrà risultati imprevedibili.
Un provider di servizi dispone che una funzione venga eseguita nel contesto di thread e processo appropriato chiamando WPUQueueApc. Questa funzione può essere chiamata da qualsiasi contesto di processo e thread, anche da un contesto diverso dal thread e dal processo usato per avviare l'operazione sovrapposta.
Un provider di servizi dispone l'esecuzione di una funzione nel thread appropriato chiamando WPUQueueApc. Si noti che questa funzione deve essere richiamata nel contesto dello stesso processo (ma non necessariamente dello stesso thread) usata per avviare l'operazione sovrapposta. È responsabilità del provider di servizi disporre che il contesto del processo sia attivo prima di chiamare WPUQueueApc.
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é è disponibile solo un singolo valore di contesto, 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 utilizza il valore di contesto fornito per accedere alle informazioni sul 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
);
CompletionRoutine è un segnaposto per un nome di funzione fornito dal client. dwError specifica lo stato di completamento per l'operazione sovrapposta, come indicato da lpOverlapped. cbTransferred specifica il numero di byte inviati. Non sono attualmente definiti valori di 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 inviati vengono inviati nello stesso ordine in cui vengono forniti.
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 .
Requisiti
| Client minimo supportato | Windows 2000 Professional [solo app desktop] |
| Server minimo supportato | Windows 2000 Server [solo app desktop] |
| Intestazione | ws2spi.h |