PFN_WSK_ACCEPT_EVENT funzione di callback (wsk.h)

Articolo
02/27/2024

La funzione di callback dell'evento WskAcceptEvent notifica a un'applicazione WSK che è stata accettata una connessione in ingresso in un socket di ascolto.

Sintassi

PFN_WSK_ACCEPT_EVENT PfnWskAcceptEvent;

NTSTATUS PfnWskAcceptEvent(
  [in, optional] PVOID SocketContext,
  [in]           ULONG Flags,
  [in]           PSOCKADDR LocalAddress,
  [in]           PSOCKADDR RemoteAddress,
  [in, optional] PWSK_SOCKET AcceptSocket,
  [out]          PVOID *AcceptSocketContext,
  [out]          const WSK_CLIENT_CONNECTION_DISPATCH **AcceptSocketDispatch
)
{...}

Parametri

[in, optional] SocketContext

Puntatore al contesto del socket per il socket in ascolto in cui è stata accettata la connessione in ingresso. L'applicazione WSK ha fornito questo puntatore al sottosistema WSK quando ha chiamato la funzione WskSocket per creare il socket di ascolto.

[in] Flags

Valore ULONG contenente il flag seguente o zero:

WSK_FLAG_AT_DISPATCH_LEVEL

Il sottosistema WSK denominato funzione di callback dell'evento WskAcceptEvent in IRQL = DISPATCH_LEVEL. Se questo flag non è impostato, il sottosistema WSK potrebbe aver chiamato la funzione di callback dell'evento WskAcceptEvent in qualsiasi irQL <= DISPATCH_LEVEL.

[in] LocalAddress

Puntatore a un buffer contenente l'indirizzo di trasporto locale in cui è arrivata la connessione in ingresso. Il buffer contiene il tipo di struttura SOCKADDR specifico che corrisponde alla famiglia di indirizzi specificata dall'applicazione WSK quando ha creato il socket di ascolto.

[in] RemoteAddress

Puntatore a un buffer che contiene l'indirizzo di trasporto remoto da cui ha avuto origine la connessione in ingresso. Il buffer contiene il tipo di struttura SOCKADDR specifico che corrisponde alla famiglia di indirizzi specificata dall'applicazione WSK quando ha creato il socket di ascolto.

[in, optional] AcceptSocket

Puntatore a una struttura WSK_SOCKET che è l'oggetto socket per il socket accettato. Se questo puntatore è NULL, il socket di ascolto non è più funzionale e l'applicazione WSK deve chiamare la funzione WskCloseSocket per chiudere il socket di ascolto il prima possibile.

[out] AcceptSocketContext

Puntatore a una variabile che riceve un puntatore a un contesto fornito dall'applicazione WSK per il socket che viene accettato. Il sottosistema WSK passa questo puntatore alle funzioni di callback degli eventi del socket accettato. Le informazioni sul contesto sono opache per il sottosistema WSK e devono essere archiviate in memoria non a pagina. Se l'applicazione WSK non abilita alcuna funzione di callback eventi nel socket accettato, l'applicazione deve impostare la variabile a cui fa riferimento il parametro AcceptSocketContext su NULL.

[out] AcceptSocketDispatch

Puntatore a una variabile che riceve un puntatore a una costante WSK_CLIENT_CONNECTION_DISPATCH struttura. Questa struttura è una tabella di invio che contiene puntatori alle funzioni di callback dell'evento per il socket accettato. Se l'applicazione WSK non abilita tutte le funzioni di callback eventi per il socket accettato, l'applicazione deve impostare i puntatori nella tabella dispatch su NULL per tali funzioni di callback evento che non abilita. Se l'applicazione WSK non abilita alcuna funzione di callback eventi nel socket accettato, deve impostare la variabile a cui fa riferimento il parametro AcceptSocketDispatch su NULL.

Valore restituito

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

Codice restituito	Descrizione
STATUS_SUCCESS	L'applicazione WSK ha accettato la connessione in ingresso.
STATUS_REQUEST_NOT_ACCEPTED	L'applicazione WSK ha rifiutato la connessione in ingresso. Se questo valore viene restituito, il sottosistema WSK chiuderà il socket accettato per conto dell'applicazione WSK.

Commenti

Il sottosistema WSK chiama la funzione di callback dell'evento WskAcceptEvent dell'applicazione WskAcceptEvent quando una connessione in ingresso viene accettata nel socket in ascolto 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 WskAcceptEvent dell'applicazione è abilitata in un socket di ascolto e l'applicazione ha una chiamata in sospeso alla funzione WskAccept nello stesso socket di ascolto, quando arriva una connessione in ingresso, la chiamata in sospeso a WskAccept ha la precedenza sulla funzione di callback dell'evento WskAcceptEvent. Il sottosistema WSK chiama la funzione di callback dell'evento WskAcceptEvent dell'applicazione solo se non sono presenti gruppi di integrazione accodati da chiamate in sospeso alla funzione WskAccept . Tuttavia, un'applicazione WSK non presuppone che il sottosistema WSK non chiami la funzione di callback dell'evento WskAcceptEvent dell'applicazione per un socket di ascolto con una chiamata in sospeso alla funzione WskAccept . Esistono condizioni di gara in cui il sottosistema WSK potrebbe comunque chiamare la funzione di callback dell'applicazione WskAcceptEvent dell'applicazione WskAcceptEvent per il socket. L'unico modo per un'applicazione WSK per assicurarsi che il sottosistema WSK non chiamerà la funzione di callback dell'evento WskAcceptEvent dell'applicazione per un socket di ascolto consiste nel disabilitare la funzione di callback dell'evento WskAcceptEvent dell'applicazione nel socket.

Quando il sottosistema WSK chiama la funzione di callback dell'evento WskAcceptEvent dell'applicazione WskAcceptEvent , tutte le funzioni di callback degli eventi nel socket accettato sono disabilitate per impostazione predefinita. Se un'applicazione WSK abilita una delle funzioni di callback degli eventi di socket orientate alla connessione in un socket in ascolto, tali funzioni di callback degli eventi verranno abilitate per impostazione predefinita su tutti i socket orientati alla connessione accettati su tale socket in ascolto. Per altre informazioni sull'abilitazione di una delle funzioni di callback degli eventi del socket accettato, vedere Abilitazione e disabilitazione delle funzioni di callback degli eventi.

Le strutture SOCKADDR a cui puntano i parametri LocalAddress e RemoteAddress sono valide solo per la durata della chiamata alla funzione di callback dell'evento WskAcceptEvent. Se un'applicazione WSK necessita di questi indirizzi di trasporto in un secondo momento, può copiare il contenuto di queste strutture nelle proprie strutture SOCKADDR prima di restituire dalla funzione di callback eventi WskAcceptEvent oppure può chiamare successivamente le funzioni WskGetLocalAddress e WskGetRemoteAddress nel socket accettato.

Il sottosistema WSK alloca la memoria per la struttura di oggetti socket ( WSK_SOCKET) per la connessione accettata per conto dell'applicazione WSK. Il sottosistema WSK dealloca questa memoria quando il socket viene chiuso.

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

La funzione di callback dell'evento WskAcceptEvent dell'applicazione WskAcceptEvent non deve attendere il completamento di altre richieste WSK nel contesto delle funzioni di completamento o callback 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