PFN_WSK_RECEIVE_EVENT funzione di callback (wsk.h)

Articolo
08/08/2023

La funzione di callback dell'evento WskReceiveEvent notifica a un'applicazione WSK che i dati sono stati ricevuti in un socket orientato alla connessione.

Sintassi

PFN_WSK_RECEIVE_EVENT PfnWskReceiveEvent;

NTSTATUS PfnWskReceiveEvent(
  [in, optional] PVOID SocketContext,
  [in]           ULONG Flags,
  [in, optional] PWSK_DATA_INDICATION DataIndication,
  [in]           SIZE_T BytesIndicated,
  [in, out]      SIZE_T *BytesAccepted
)
{...}

Parametri

[in, optional] SocketContext

Puntatore al contesto del socket per il socket orientato alla connessione che ha ricevuto i dati. L'applicazione WSK ha fornito questo puntatore al sottosistema WSK in uno dei modi seguenti:

Ha chiamato la funzione WskSocket per creare il socket.
Ha chiamato la funzione WskSocketConnect per creare il socket.
Ha chiamato la funzione WskAccept per accettare il socket come connessione in ingresso.
La funzione di callback dell'evento WskAcceptEvent è stata chiamata per accettare il socket come connessione in ingresso.

[in] Flags

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

Valore	Significato
WSK_FLAG_RELEASE_ASAP	I buffer di dati che contengono i dati ricevuti non devono essere conservati dall'applicazione WSK se possibile. Se l'applicazione WSK mantiene i buffer, deve rilasciarli il prima possibile chiamando la funzione WskRelease .
WSK_FLAG_ENTIRE_MESSAGE	I buffer di dati contengono un intero messaggio o la parte finale di un messaggio. L'interpretazione di ciò che costituisce un intero messaggio è specifico del protocollo di trasporto. Per TCP, questo flag indica che il bit push è stato impostato per uno o più segmenti TCP che costituiscono i dati nei buffer di dati.
WSK_FLAG_AT_DISPATCH_LEVEL	Il sottosistema WSK denominato funzione di callback dell'evento WskReceiveEvent in IRQL = DISPATCH_LEVEL. Se questo flag non è impostato, il sottosistema WSK potrebbe aver chiamato la funzione di callback dell'evento WskReceiveEvent in qualsiasi

[in, optional] DataIndication

Puntatore a un elenco collegato di strutture WSK_DATA_INDICATION che descrivono i dati ricevuti. Se questo parametro è NULL, il socket non è più funzionale e l'applicazione WSK deve chiamare la funzione WskCloseSocket per chiudere il socket il prima possibile.

[in] BytesIndicated

Numero di byte di dati ricevuti descritti dall'elenco collegato di strutture WSK_DATA_INDICATION .

[in, out] BytesAccepted

Puntatore a una variabile SIZE_T tipizzata che riceve il numero di byte di dati ricevuti accettati dall'applicazione WSK. Questa variabile deve essere impostata solo se l'applicazione WSK accetta una parte del numero totale di byte dei dati ricevuti. Se l'applicazione WSK accetta tutti i dati ricevuti, non deve impostare questa variabile. Se la funzione di callback dell'evento WskReceiveEvent restituisce uno stato diverso da STATUS_SUCCESS, il sottosistema WSK ignora il valore di questa variabile.

Valore restituito

La funzione di callback dell'evento WskReceiveEvent dell'applicazione WskReceiveEvent può restituire uno dei codici NTSTATUS seguenti:

Codice restituito	Descrizione
STATUS_SUCCESS	L'applicazione WSK ha accettato almeno alcuni dei dati ricevuti. Se l'applicazione WSK ha accettato tutti i dati ricevuti, il sottosistema WSK può chiamare nuovamente la funzione di callback dell'evento WskReceiveEvent quando vengono ricevuti nuovi dati nel socket. Tuttavia, se l'applicazione WSK accettava solo una parte dei dati ricevuti, il sottosistema WSK non chiamerà nuovamente la funzione di callback dell'evento WskReceiveEvent fino a quando l'applicazione WSK chiama la funzione WskReceive . Dopo che l'applicazione WSK chiama la funzione WskReceive , il sottosistema WSK riprenderà a chiamare la funzione di callback dell'evento WskReceiveEvent con eventuali dati memorizzati nel buffer rimanenti e quando vengono ricevuti nuovi dati nel socket. Un'applicazione WSK può chiamare la funzione WskReceive con un buffer a lunghezza zero, che consentirà al sottosistema WSK di riprendere la chiamata alla funzione di callback dell'evento WskReceiveEvent senza chiamare WskReceive per ricevere dati dal socket.
STATUS_PENDING	L'applicazione WSK ha accettato i dati ma non ha recuperato tutti i dati contenuti nell'elenco collegato di strutture WSK_DATA_INDICATION . L'applicazione WSK mantiene l'elenco collegato di strutture WSK_DATA_INDICATION finché non vengono recuperati tutti i dati. Dopo che l'applicazione WSK ha recuperato tutti i dati che chiama la funzione WskRelease per rilasciare l'elenco collegato di strutture WSK_DATA_INDICATION tornare al sottosistema WSK. Il sottosistema WSK può chiamare nuovamente la funzione di callback dell'evento WskReceiveEvent quando vengono ricevuti nuovi dati nel socket.
STATUS_DATA_NOT_ACCEPTED	L'applicazione WSK non accetta i dati. In questa situazione, il sottosistema WSK avrà il buffer di trasporto sottostante i dati, se possibile o se necessario dal protocollo. Il sottosistema WSK non chiamerà di nuovo la funzione di callback dell'evento WskReceiveEvent fino a quando l'applicazione WskReceive chiama la funzione WskReceive . Dopo che l'applicazione WSK chiama la funzione WskReceive , il sottosistema WSK riprenderà a chiamare la funzione di callback dell'evento WskReceiveEvent con eventuali dati memorizzati nel buffer rimanenti e quando vengono ricevuti nuovi dati nel socket. Un'applicazione WSK può chiamare la funzione WskReceive con un buffer a lunghezza zero, che consentirà al sottosistema WSK di riprendere la chiamata alla funzione di callback dell'evento WskReceiveEvent senza chiamare WskReceive per ricevere dati dal socket.

Commenti

Il sottosistema WSK chiama la funzione di callback dell'evento WskReceiveEvent dell'applicazione WskReceiveEvent quando vengono ricevuti nuovi dati in un socket orientato alla connessione solo se la funzione di callback evento è stata abilitata in precedenza con l'opzione socket SO_WSK_EVENT_CALLBACK . Per altre informazioni sull'abilitazione delle funzioni di callback degli eventi di un socket, vedere Abilitazione e disabilitazione delle funzioni di callback degli eventi.

Se la funzione di callback dell'evento WskReceiveEvent di un'applicazione WskReceiveEvent è abilitata in un socket orientato alla connessione e l'applicazione ha anche una chiamata in sospeso alla funzione WskReceive sulla stessa socket orientata alla connessione, quando i dati arrivano, 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 gruppi di integrazione accodati da chiamate in sospeso alla funzione WskReceive . Tuttavia, un'applicazione WSK non presuppone che il sottosistema WSK non chiami la funzione di callback dell'evento WskReceiveEvent dell'applicazione per un socket orientato alla connessione con una chiamata in sospeso alla funzione WskReceive . Esistono condizioni di gara in cui il sottosistema WSK potrebbe comunque chiamare la funzione di callback dell'applicazione WskReceiveEvent per il socket. L'unico modo per un'applicazione WSK per assicurarsi 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.

Nota

Winsock Kernel (WSK) chiama questo callback serialmente, quindi non viene sempre richiamato non appena vengono ricevuti i dati.

Il sottosistema WSK chiama la funzione di callback dell'evento WskReceiveEvent dell'applicazione WskReceiveEvent in IRQL <= DISPATCH_LEVEL.

La funzione di callback dell'evento WskReceiveEvent dell'applicazione WskReceiveEvent non deve attendere il completamento di altre richieste WSK nel contesto delle funzioni di completamento o callback degli eventi WSK. Il callback può avviare altre richieste WSK (presupponendo che non spenda troppo tempo in DISPATCH_LEVEL), ma non deve attendere il completamento anche quando il callback viene chiamato in IRQL = PASSIVE_LEVEL.

Requisiti

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