PFN_WSK_CONNECT_EX funzione di callback (wsk.h)

Articolo
02/07/2025

La funzione WskConnectEx connette un socket di flusso o orientato alla connessione a un indirizzo di trasporto remoto.

WskConnectEx è simile a WskConnect, ad eccezione del fatto che può anche inviare facoltativamente un buffer di dati durante o dopo la sincronizzazione della connessione.

Sintassi

PFN_WSK_CONNECT_EX PfnWskConnectEx;

NTSTATUS PfnWskConnectEx(
  [in]           PWSK_SOCKET Socket,
  [in]           PSOCKADDR RemoteAddress,
  [in, optional] PWSK_BUF Buffer,
                 ULONG Flags,
  [in, out]      PIRP Irp
)
{...}

Parametri

[in] Socket

Puntatore a una struttura WSK_SOCKET che specifica l'oggetto socket per il socket connesso a un indirizzo di trasporto remoto.

[in] RemoteAddress

Puntatore a una struttura che specifica l'indirizzo di trasporto remoto a cui connettere il socket. Questo puntatore deve essere un puntatore allo specifico tipo di struttura SOCKADDR che corrisponde alla famiglia di indirizzi specificata dall'applicazione WSK al momento della creazione del socket.

[in, optional] Buffer

Puntatore a una struttura di WSK_BUF che contiene i dati da inviare durante o dopo la sincronizzazione della connessione. La dimensione massima consentita in byte è 65.535.

Flags

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

[in, out] Irp

Puntatore a un IRP allocato dal chiamante usato dal sottosistema WSK per completare l'operazione di connessione 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

WskConnectEx restituisce uno dei codici NTSTATUS seguenti:

Codice restituito	Descrizione
STATUS_SUCCESS	Il socket è stato connesso correttamente all'indirizzo di trasporto remoto. L'IRP verrà completato con lo stato di esito positivo.
STATUS_PENDING	Il sottosistema WSK non è riuscito a connettere immediatamente il socket. Il sottosistema WSK completerà l'IRP dopo aver collegato il socket all'indirizzo di trasporto remoto. Lo stato dell'operazione di connessione verrà restituito nel campo IoStatus.Status di IRP.
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.
STATUS_INVALID_PARAMETER	L'applicazione WSK ha tentato di passare un flag al parametro flag ( poiché non sono attualmente definiti flag validi per WskConnectEx, questo non è consentito).
STATUS_BUFFER_OVERFLOW	L'applicazione WSK ha tentato di passare un buffer maggiore di 65.535 byte al parametro buffer.
Altri codici di stato	Si è verificato un errore. L'IRP verrà completato con lo stato di errore.

Osservazioni

Un'applicazione WSK può creare, associare e connettere un socket orientato alla connessione in una singola chiamata di funzione chiamando la funzione WskSocketConnect anziché chiamare la funzione WskSocket, la funzione WskBind e quindi la funzione WskConnectEx. È consigliabile chiamare la funzione WskSocketConnect a meno che l'applicazione WSK non debba impostare un'opzione socket o eseguire un'operazione di controllo di I/O prima dell'associazione o della connessione del socket.

Un'applicazione WSK può chiamare la funzione WskConnectEx solo su un socket di flusso o orientato alla connessione associato in precedenza a un indirizzo di trasporto locale chiamando la funzione WskBind.

Per i socket di flusso, una volta WskConnectEx viene chiamato correttamente su un socket di flusso, il socket viene eseguito il commit in un flusso orientato alla connessione e potrebbe non chiamare più funzioni socket di ascolto.

Se viene usato il parametro buffer, il chiamante può liberare il file MDL nella struttura WSK_BUF non appena viene completata la richiesta di connessione.

Prima di chiamare WskConnectEx con un buffer di invio fornito, se l'applicazione WSK imposta l'opzione TCP_FASTOPEN su un socket WSK tramite la funzione WskControlSocket il sistema invierà facoltativamente alcuni o tutti i dati in un pacchetto SYN. Per altre informazioni, vedere l'opzione TCP Fastopen in IPPROTO_TCP Opzioni socket.