Funzione di callback LPWSPGETOVERLAPPEDRESULT (ws2spi.h)

Articolo
08/28/2023

La funzione LPWSPGetOverlappedResult restituisce i risultati di un'operazione sovrapposta sul socket specificato.

Sintassi

LPWSPGETOVERLAPPEDRESULT Lpwspgetoverlappedresult;

BOOL Lpwspgetoverlappedresult(
  [in]  SOCKET s,
  [in]  LPWSAOVERLAPPED lpOverlapped,
  [out] LPDWORD lpcbTransfer,
  [in]  BOOL fWait,
  [out] LPDWORD lpdwFlags,
  [out] LPINT lpErrno
)
{...}

Parametri

[in] s

Identifica il socket. Si tratta dello stesso socket specificato quando l'operazione sovrapposta è stata avviata da una chiamata a LPWSPRecv, LPWSPRecvFrom, LPWSPSend, LPWSPSendTo o LPWSPIoctl.

[in] lpOverlapped

Puntatore a una struttura WSAOverlapped specificata all'avvio dell'operazione sovrapposta.

[out] lpcbTransfer

Puntatore a una variabile a 32 bit che riceve il numero di byte effettivamente trasferiti da un'operazione di invio o ricezione o da LPWSPIoctl.

[in] fWait

Specifica se la funzione deve attendere il completamento dell'operazione sovrapposta in sospeso. Se TRUE, la funzione non restituisce fino al completamento dell'operazione. Se FALSE e l'operazione è ancora in sospeso, la funzione restituisce FALSE e lpErrno è WSA_IO_INCOMPLETE. Il parametro fWait può essere impostato su TRUE solo se l'operazione sovrapposta ha selezionato la notifica di completamento basata su eventi.

[out] lpdwFlags

Puntatore a una variabile a 32 bit che riceverà uno o più flag che integrano lo stato di completamento. Se l'operazione sovrapposta è stata avviata tramite LPWSPRecv o LPWSPRecvFrom, questo parametro conterrà il valore dei risultati per il parametro lpFlags .

[out] lpErrno

Puntatore al codice di errore.

Valore restituito

Se LPWSPGetOverlappedResult ha esito positivo, il valore restituito è TRUE. Ciò significa che l'operazione sovrapposta è stata completata correttamente e il valore a cui punta lpcbTransfer è stato aggiornato. Se LPWSPGetOverlappedResult restituisce FALSE, significa che l'operazione sovrapposta non è stata completata o l'operazione sovrapposta è stata completata, ma con errori o lo stato di completamento non è stato possibile determinare a causa di errori in uno o più parametri in LPWSPGetOverlappedResult. In caso di errore, il valore a cui punta lpcbTransfer non verrà aggiornato. Il parametro lpErrno indica la causa dell'errore ( LPWSPGetOverlappedResult o dell'operazione sovrapposta associata).

Codice di errore	Significato
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAENOTSOCK	Il descrittore non è un socket.
WSA_INVALID_HANDLE	Il membro hEvent della struttura WSAOverlapped non contiene un handle di oggetto evento valido.
WSAEINVAL	Uno dei parametri è inaccettabile.
WSA_IO_INCOMPLETE	Il parametro fWait è FALSE e l'operazione di I/O non è ancora stata completata.

Commenti

I risultati segnalati dalla funzione LPWSPGetOverlappedResult sono quelli dell'ultima operazione sovrapposta del socket specificato a cui è stata fornita la struttura WSAOverlapped specificata e per cui i risultati dell'operazione erano in sospeso. Un'operazione in sospeso viene indicata quando la funzione che ha avviato l'operazione restituisce SOCKET_ERROR e lpErrno è WSA_IO_PENDING. Quando un'operazione di I/O è in sospeso, la funzione che ha avviato l'operazione reimposta il membro hEvent della struttura WSAOVERLAPPED sullo stato non firmato. Al termine dell'operazione in sospeso, il sistema imposta quindi l'oggetto evento sullo stato segnalato.

Se il parametro fWait è TRUE, LPWSPGetOverlappedResult determina se l'operazione in sospeso è stata completata bloccando e attendendo che l'oggetto evento sia nello stato segnalato. Un client può impostare il parametro fWait su TRUE solo se è stata selezionata la notifica di completamento basata su eventi quando è stata richiesta l'operazione di I/O. Se è stata selezionata un'altra forma di notifica, l'utilizzo del membro hEvent della struttura WSAOverlapped è diverso e l'impostazione di fWait su TRUE causa risultati imprevedibili.

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 .

Interazione con WPUCompleteOverlappedRequest

Il comportamento di WPUCompleteOverlappedRequest pone alcuni vincoli sul modo in cui un provider di servizi implementa LPWSPGetOverlappedResult poiché solo i membri Offset e OffsetHigh della struttura WSAOverlapped sono controllati esclusivamente dal provider di servizi anche se tre valori (conteggio byte, flag ed errore) devono essere recuperati dalla struttura da LPWSPGetOverlappedResult. Un provider di servizi può eseguire questa operazione in qualsiasi modo scelto, purché interagisca correttamente con il comportamento di WPUCompleteOverlappedRequest . La descrizione seguente presenta un'implementazione tipica:

All'inizio dell'elaborazione sovrapposta, il provider di servizi imposta Internal su WSS_OPERATION_IN_PROGRESS.

Al termine dell'operazione di I/O, il provider imposta OffsetHigh sul codice di errore di Windows Sockets 2 risultante dall'operazione, imposta Offset sui flag risultanti dall'operazione di I/O e chiama WPUCompleteOverlappedRequest, passando il conteggio dei byte di trasferimento come uno dei parametri. WPUCompleteOverlappedRequest imposta infine InternalHigh sul conteggio dei byte di trasferimento, quindi imposta Internal su un valore diverso da WSS_OPERATION_IN_PROGRESS.

Quando viene chiamato LPWSPGetOverlappedResult , il provider di servizi controlla Internal. Se è WSS_OPERATION_IN_PROGRESS, il provider attende l'handle dell'evento nel membro hEvent o restituisce un errore, in base all'impostazione del flag fWait di LPWSPGetOverlappedResult. Se non è in corso o dopo il completamento dell'attesa, il provider restituisce i valori rispettivamente da InternalHigh, OffsetHigh e Offset come numero di trasferimento, codice di errore del risultato dell'operazione e flag.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Intestazione	ws2spi.h