PFN_WSK_RECEIVE funzione di callback (wsk.h)

Articolo
08/08/2023

La funzione WskReceive riceve i dati su un socket di flusso o orientato alla connessione da un indirizzo di trasporto remoto.

Sintassi

PFN_WSK_RECEIVE PfnWskReceive;

NTSTATUS PfnWskReceive(
  [in]      PWSK_SOCKET Socket,
  [in]      PWSK_BUF Buffer,
  [in]      ULONG Flags,
  [in, out] PIRP Irp
)
{...}

Parametri

[in] Socket

Puntatore a una struttura WSK_SOCKET che specifica l'oggetto socket per il socket da cui ricevere i dati.

[in] Buffer

Puntatore a una struttura di WSK_BUF inizializzata che descrive il buffer di dati che riceve i dati dal socket.

[in] Flags

Valore ULONG che contiene un OR bit per bit di una combinazione dei flag seguenti:

WSK_FLAG_WAITALL

Attendere fino a quando il buffer dei dati non viene riempito completamente. Se questo flag viene specificato, l'IRP specificato nel parametro Irp non verrà completato fino a quando non si verifica uno degli eventi seguenti:

Il buffer di dati descritto dalla struttura WSK_BUF a cui punta il parametro Buffer viene riempito completamente.
La connessione viene normalmente disconnessa dal mittente remoto.
La connessione viene interrotta in modo interrotto dall'applicazione WSK o dal mittente remoto.
L'IRP specificato viene annullato.

Questo flag è supportato dal protocollo di trasporto TCP/IP Microsoft. Questo flag potrebbe non essere supportato da altri protocolli di trasporto.

WSK_FLAG_DRAIN

Attendere che il socket venga disconnesso, rimuovendo tutti i dati ricevuti sul socket. Se questo flag viene specificato, l'IRP specificato non verrà completato fino a quando non si verifica uno degli eventi seguenti:

La connessione viene normalmente disconnessa dal mittente remoto.
La connessione viene interrotta in modo interrotto dall'applicazione WSK o dal mittente remoto.
L'IRP specificato viene annullato.

Tutti i dati ricevuti vengono eliminati dal sottosistema WSK. Nessun dato ricevuto verrà copiato nel buffer dei dati. Il parametro Buffer è ancora necessario quando viene specificato questo flag, ma la lunghezza del buffer descritta dalla struttura WSK_BUF deve essere zero.

Questo flag è supportato dal protocollo di trasporto TCP/IP Microsoft. Questo flag potrebbe non essere supportato da altri protocolli di trasporto.

I flag WSK_FLAG_WAITALL e WSK_FLAG_DRAIN si escludono a vicenda. Un'applicazione WSK non deve specificare entrambi questi flag contemporaneamente.

[in, out] Irp

Puntatore a un IRP allocato dal chiamante usato dal sottosistema WSK per completare l'operazione di ricezione in modo asincrono. Per altre informazioni sull'uso dei runtime di integrazione con le funzioni WSK, vedere Using IRPs with Winsock Kernel Functions .For more information about using IRPs with WSK functions, see Using IRPs with Winsock Kernel Functions.

Valore restituito

WskReceive restituisce uno dei codici NTSTATUS seguenti:

Codice restituito	Descrizione
STATUS_SUCCESS	I dati sono stati ricevuti correttamente dal socket. L'IRP verrà completato con lo stato di esito positivo. Il campo IoStatus.Information di IRP contiene il numero di byte ricevuti.
STATUS_PENDING	Il sottosistema WSK non è riuscito a ricevere immediatamente i dati dal socket. Il sottosistema WSK completerà l'IRP dopo aver ricevuto i dati dal socket. Lo stato dell'operazione di ricezione verrà restituito nel campo IoStatus.Status dell'IRP. Se l'operazione ha esito positivo, il campo IoStatus.Information dell'IRP conterrà il numero di byte ricevuti.
STATUS_FILE_FORCED_CLOSED	Il socket non è più funzionale. L'IRP verrà completato con lo stato di errore. L'applicazione WSK deve chiamare la funzione WskCloseSocket per chiudere il socket appena possibile.
STATUS_NOT_SUPPORTED	Un flag specificato non è supportato dal trasporto di rete sottostante.
Altri codici di stato	Si è verificato un errore. L'IRP verrà completato con lo stato di errore.

Commenti

Un'applicazione WSK può chiamare la funzione WskReceive solo su un socket di flusso o orientato alla connessione precedentemente connesso a un indirizzo di trasporto remoto. Un socket orientato alla connessione è connesso a un indirizzo di trasporto remoto tramite uno dei metodi seguenti:

L'applicazione WSK connette il socket chiamando la funzione WskConnect .
L'applicazione WSK crea, associa e connette il socket chiamando la funzione WskSocketConnect .
Il sottosistema WSK connette il socket quando l'applicazione WSK accetta una richiesta di connessione in ingresso su un socket di ascolto.

Se la funzione di callback dell'evento WskReceiveEvent di un'applicazione WSK è abilitata in un socket orientato alla connessione e l'applicazione ha anche una chiamata in sospeso alla funzione WskReceive sullo stesso socket orientato alla connessione, quando arrivano i dati, la chiamata in sospeso alla funzione WskReceive avrà la precedenza sulla funzione di callback dell'evento WskReceiveEvent . Il sottosistema WSK chiama la funzione di callback dell'evento WskReceiveEvent dell'applicazione solo se non sono presenti irP accodati da chiamate in sospeso alla funzione WskReceive . Tuttavia, un'applicazione WSK non deve presupporre che il sottosistema WSK non chiamerà la funzione di callback dell'evento WskReceiveEvent dell'applicazione per un socket orientato alla connessione con una chiamata in sospeso alla funzione WskReceive . Esistono race condition in cui il sottosistema WSK potrebbe comunque chiamare la funzione di callback dell'evento WskReceiveEvent dell'applicazione WskReceiveEvent per il socket. L'unico modo per un'applicazione WSK per garantire che il sottosistema WSK non chiamerà la funzione di callback dell'evento WskReceiveEvent dell'applicazione per un socket orientato alla connessione consiste nel disabilitare la funzione di callback dell'evento WskReceiveEvent dell'applicazione nel socket.

Un'applicazione WSK può chiamare la funzione WskReceive con una lunghezza zero specificata nel membro Length della struttura WSK_BUF a cui punta il parametro Buffer . La specifica di una lunghezza zero in questo membro è utile nelle situazioni seguenti:

Quando si riabilita la funzione di callback dell'evento WskReceiveEvent per un socket dopo la funzione di callback dell'evento WskReceiveEvent restituita in precedenza STATUS_DATA_NOT_ACCEPTED
Quando si specifica il flag di WSK_FLAG_DRAIN per rimuovere eventuali dati aggiuntivi ricevuti nel socket

Se la funzione WskReceive restituisce STATUS_PENDING, la catena MDL descritta nella struttura WSK_BUF a cui punta il parametro Buffer deve rimanere bloccata fino al completamento dell'IRP.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile in Windows Vista e versioni successive dei sistemi operativi Windows.
Piattaforma di destinazione	Universale
Intestazione	wsk.h (include Wsk.h)
IRQL	<= DISPATCH_LEVEL