PFN_WSK_ACCEPT funzione di callback (wsk.h)

Articolo
02/07/2025

La funzione WskAccept accetta una connessione in ingresso su 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 di WSK_SOCKET che specifica l'oggetto socket per il socket in ascolto o flusso 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 di paging. Se l'applicazione WSK non abilita alcuna funzione di callback degli 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 dispatch che contiene puntatori alle funzioni di callback degli eventi per il socket accettato. Se l'applicazione WSK non abilita tutte le funzioni di callback degli eventi per il socket accettato, deve impostare i puntatori nella tabella dispatch su null per le funzioni di callback degli eventi non abilitate. Se l'applicazione WSK non abilita alcuna funzione di callback degli 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 di paging. Il buffer deve anche essere sufficientemente grande da contenere il tipo di struttura SOCKADDR specifico che corrisponde alla famiglia di indirizzi specificata dall'applicazione WSK al momento della creazione del socket di ascolto. Questo puntatore è facoltativo e può essere NULL.

[out, optional] RemoteAddress

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

[in, out] Irp

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

Valore restituito

WskAccept restituisce uno dei codici NTSTATUS seguenti:

Codice restituito	Descrizione
STATUS_SUCCESS	È stata accettata correttamente 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 sul socket di 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.

Osservazioni

Un'applicazione WSK può chiamare la funzione WskAccept su un socket di ascolto o un socket di flusso associato in precedenza a un indirizzo di trasporto locale chiamando la funzione WskBind.

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

Se una connessione in ingresso è già arrivata sul socket di ascolto ed è in attesa di essere accettata, la funzione WskAccept restituisce STATUS_SUCCESS. In questo caso, 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 finché non viene ricevuta una connessione in ingresso. Quando viene ricevuta una connessione in ingresso, il sottosistema WSK completa in modo asincrono l'IRP con lo stato di esito positivo. In questa situazione, il campo IoStatus.Information di IRP contiene un puntatore all'oggetto socket per il socket accettato.

Se un'applicazione WSK WskAcceptEvent funzione di callback degli eventi è abilitata in un socket di ascolto e l'applicazione ha una chiamata in sospeso alla funzione WskAccept sullo stesso socket di ascolto, quindi, quando arriva una connessione in ingresso, la chiamata in sospeso a WskAccept ha la precedenza sulla WskAcceptEvent funzione di callback dell'evento. Il sottosistema WSK chiama la funzione di callback dell'evento WskAcceptEvent dell'applicazione solo se non sono presenti irP accodati da chiamate in sospeso a WskAccept. Tuttavia, un'applicazione WSK non deve presupporre che il sottosistema WSK non chiamerà il WskAcceptEvent funzione di callback dell'evento per un socket in ascolto con una chiamata in sospeso alla funzione WskAccept. Esistono race condition in cui il sottosistema WSK potrebbe comunque chiamare la funzione di callback dell'evento WskAcceptEvent WskAcceptE vent per il socket. L'unico modo per un'applicazione WSK per garantire che il sottosistema WSK non chiami la funzione di callback dell'evento WskAcceptEvent 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 degli eventi nel socket accettato vengono 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 nullnon 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 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.

Fabbisogno

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