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.

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.

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.

Requisiti

Vedi anche

WPUQueueApc

LPWSPGetOverlappedResult

LPWSPSocket