PFN_WSK_ACCEPT funzione di callback (wsk.h)

Articolo
08/08/2023

La funzione WskAccept accetta una connessione in ingresso in un socket in ascolto.

Sintassi

PFN_WSK_ACCEPT PfnWskAccept;

NTSTATUS PfnWskAccept(
  [in]            PWSK_SOCKET ListenSocket,
                  ULONG Flags,
  [in, optional]  PVOID AcceptSocketContext,
  [in, optional]  const WSK_CLIENT_CONNECTION_DISPATCH *AcceptSocketDispatch,
  [out, optional] PSOCKADDR LocalAddress,
  [out, optional] PSOCKADDR RemoteAddress,
  [in, out]       PIRP Irp
)
{...}

Parametri

[in] ListenSocket

Puntatore a una struttura WSK_SOCKET che specifica l'oggetto socket per il socket in ascolto o il socket di flusso che viene controllato per una connessione in ingresso.

Flags

Questo parametro è riservato per l'uso del sistema. Un'applicazione WSK deve impostare questo parametro su zero.

[in, optional] AcceptSocketContext

Puntatore a un contesto fornito dal chiamante 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. Le informazioni sul contesto devono essere archiviate in memoria non a pagina. Se l'applicazione WSK non abilita alcuna funzione di callback eventi nel socket accettato, deve impostare questo puntatore su NULL.

[in, optional] AcceptSocketDispatch

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, 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 questo puntatore su NULL.

[out, optional] LocalAddress

Puntatore a un buffer allocato dal chiamante che riceve l'indirizzo di trasporto locale in cui è arrivata la connessione in ingresso. Il buffer deve trovarsi nella memoria non a pagina. Il buffer deve anche essere abbastanza grande per contenere il tipo di struttura SOCKADDR specifico che corrisponde alla famiglia di indirizzi specificata dall'applicazione WSK quando ha creato il socket di ascolto. Questo puntatore è facoltativo e può essere NULL.

[out, optional] RemoteAddress

Puntatore a un buffer allocato del chiamante che riceve l'indirizzo di trasporto remoto da cui ha avuto origine la connessione in ingresso. Il buffer deve trovarsi nella memoria non a pagina. Il buffer deve anche essere abbastanza grande per contenere il tipo di struttura SOCKADDR specifico che corrisponde alla famiglia di indirizzi specificata dall'applicazione WSK quando ha creato il socket di ascolto. Questo puntatore è facoltativo e può essere NULL.

[in, out] Irp

Puntatore a un'IRP allocata dal chiamante che il sottosistema WSK usa per completare l'operazione di accettazione in modo asincrono. Per altre informazioni sull'uso di IRP con funzioni WSK, vedere Uso di IRP con Funzioni kernel Winsock.

Valore restituito

WskAccept restituisce uno dei codici NTSTATUS seguenti:

Codice restituito	Descrizione
STATUS_SUCCESS	È stata accettata una connessione in ingresso. L'IRP verrà completato con lo stato di esito positivo.
STATUS_PENDING	L'IRP è stato accodato dal sottosistema WSK, in attesa di una connessione in ingresso nel socket in ascolto.
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 il prima possibile.
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 WskAccept in un socket di ascolto o in un socket di flusso associato in precedenza a un indirizzo di trasporto locale chiamando la funzione WskBind .

Il comportamento della funzione WskAccept dipende dal fatto che una connessione in ingresso sia in attesa di essere accettata nel socket in ascolto:

Se una connessione in ingresso è già arrivata sul socket di ascolto e deve essere accettata, la funzione WskAccept restituisce STATUS_SUCCESS. In questa situazione, l'IRP viene completato con lo stato di esito positivo e il campo IoStatus.Information dell'IRP contiene un puntatore all'oggetto socket per il socket accettato.
Se una connessione in ingresso non è in attesa di essere accettata nel socket di ascolto, WskAccept restituisce STATUS_PENDING e il sottosistema WSK accoda l'IRP fino a quando non viene ricevuta una connessione in ingresso. Quando viene ricevuta una connessione in ingresso, il sottosistema WSK completa in modo asincrono l'IRP con stato di esito positivo. In questa situazione, il campo IoStatus.Information dell'IRP contiene un puntatore all'oggetto socket per il socket accettato.

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 a 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 la funzione WskAccept accetta correttamente una connessione in ingresso, tutte le funzioni di callback dell'evento nel socket accettato sono disabilitate per impostazione predefinita. 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.

Se un'applicazione WSK specifica un puntatore non NULL nel parametro LocalAddress, nel parametro RemoteAddress o in entrambi i parametri e se WskAccept restituisce STATUS_PENDING, i buffer a cui puntano tali parametri devono rimanere validi fino al completamento dell'IRP. Se l'applicazione WSK ha allocato i buffer con una delle funzioni ExAllocateXxx , non può liberare la memoria con la funzione ExFreeXxx corrispondente fino al completamento dell'IRP. Se l'applicazione WSK ha allocato i buffer nello stack, non può restituire dalla funzione che chiama la funzione WskAccept fino al completamento dell'IRP.

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.

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