PFN_WSK_SOCKET_CONNECT funzione di callback (wsk.h)

Articolo
02/07/2025

La funzione WskSocketConnect crea un nuovo socket orientato alla connessione, lo associa a un indirizzo di trasporto locale, lo connette a un indirizzo di trasporto remoto specificato e restituisce un puntatore all'oggetto socket associato.

Sintassi

PFN_WSK_SOCKET_CONNECT PfnWskSocketConnect;

NTSTATUS PfnWskSocketConnect(
  [in]           PWSK_CLIENT Client,
  [in]           USHORT SocketType,
  [in]           ULONG Protocol,
  [in]           PSOCKADDR LocalAddress,
  [in]           PSOCKADDR RemoteAddress,
                 ULONG Flags,
  [in, optional] PVOID SocketContext,
  [in, optional] const WSK_CLIENT_CONNECTION_DISPATCH *Dispatch,
  [in, optional] PEPROCESS OwningProcess,
  [in, optional] PETHREAD OwningThread,
  [in, optional] PSECURITY_DESCRIPTOR SecurityDescriptor,
  [in, out]      PIRP Irp
)
{...}

Parametri

[in] Client

Puntatore a una struttura WSK_CLIENT restituita tramite il parametro WskProviderNpi di funzione di WskCaptureProviderNPI.

[in] SocketType

Tipo del socket in fase di creazione. Sono supportati i tipi di socket seguenti:

SOCK_STREAM

Supporta la comunicazione affidabile del flusso di byte orientata alla connessione.

SOCK_DGRAM

Supporta la comunicazione datagrammi senza connessione affidabile.

SOCK_RAW

Supporta l'accesso non elaborato al protocollo di trasporto.

Per altre informazioni sui tipi di socket supportati per ogni famiglia di indirizzi supportata, vedere
famiglie di indirizzi WSK.

[in] Protocol

Protocollo di trasporto per il socket in fase di creazione. Per altre informazioni sui protocolli supportati per ogni famiglia di indirizzi supportata, vedere famiglie di indirizzi WSK.

[in] LocalAddress

Puntatore a una struttura che specifica l'indirizzo di trasporto locale a cui associare il socket. L'applicazione WSK deve specificare un puntatore al tipo di struttura SOCKADDR specifico che corrisponde alla famiglia di indirizzi per il socket che viene creato.

[in] RemoteAddress

Puntatore a una struttura che specifica l'indirizzo di trasporto remoto a cui connettere il socket. L'applicazione WSK deve specificare un puntatore al tipo di struttura SOCKADDR specifico che corrisponde alla famiglia di indirizzi per il socket che viene creato.

Flags

Questo parametro è riservato per l'uso del sistema. Le applicazioni WSK devono impostare questo parametro su zero.

[in, optional] SocketContext

Puntatore a un contesto fornito dal chiamante per il socket in fase di creazione. Il sottosistema WSK passa questo puntatore alle funzioni di callback degli eventi del socket. Le informazioni sul contesto sono opache per il sottosistema WSK e devono essere archiviate in memoria non di paging. Se l'applicazione WSK non abilita alcuna funzione di callback degli eventi nel nuovo socket, deve impostare questo puntatore su NULL.

[in, optional] Dispatch

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 nuovo socket. Se l'applicazione WSK non abilita tutte le funzioni di callback degli eventi per il nuovo socket, 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 nuovo socket, deve impostare questo puntatore su NULL.

[in, optional] OwningProcess

Puntatore al processo da cui il sottosistema WSK recupererà il contesto di sicurezza da usare quando associa il socket. Il sottosistema WSK usa il contesto di sicurezza per determinare se l'indirizzo di trasporto locale può essere condiviso se tale indirizzo è già in uso. Per specificare il processo corrente, un'applicazione WSK imposta questo puntatore su NULL.

[in, optional] OwningThread

Puntatore a un thread specifico da cui il sottosistema WSK recupererà il contesto di sicurezza da usare quando associa il socket. Il sottosistema WSK usa il contesto di sicurezza per determinare se l'indirizzo di trasporto locale può essere condiviso se tale indirizzo è già in uso. Se un'applicazione WSK non deve specificare un thread specifico, imposta questo puntatore su NULL.

[in, optional] SecurityDescriptor

Puntatore a una struttura SECURITY_DESCRIPTOR che specifica il descrittore di sicurezza da applicare al socket in fase di creazione. Il descrittore di sicurezza controlla la condivisione dell'indirizzo di trasporto locale a cui è associato il socket. Se un'applicazione WSK specifica un puntatore nullnon, deve specificare un puntatore a una copia memorizzata nella cache di un descrittore di sicurezza ottenuto chiamando la funzione WskControlClient con il codice di controllo WSK_CACHE_SD. Per specificare un descrittore di sicurezza predefinito che non consente la condivisione dell'indirizzo di trasporto locale, un'applicazione WSK imposta securityDescriptor su NULL.

Per altre informazioni sulla struttura SECURITY_DESCRIPTOR, vedere la pagina di riferimento per SECURITY_DESCRIPTOR nella documentazione di Microsoft Windows SDK.

[in, out] Irp

Puntatore a un IRP allocato dal chiamante usato dal sottosistema WSK per completare la creazione del nuovo socket 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

WskSocketConnect restituisce uno dei codici NTSTATUS seguenti:

Codice restituito	Descrizione
STATUS_SUCCESS	Il nuovo socket è stato creato correttamente. L'IRP verrà completato con lo stato di esito positivo.
STATUS_PENDING	Il sottosistema WSK non è riuscito a creare immediatamente il socket. Il sottosistema WSK completerà l'IRP dopo aver creato il nuovo socket. Lo stato della creazione del socket verrà restituito nel campo IoStatus.Status di IRP.
Altri codici di stato	Si è verificato un errore. L'IRP verrà completato con lo stato di errore.

Osservazioni

Se l'IRP viene completato con lo stato di esito positivo, il campo IoStatus.Information di IRP contiene un puntatore a una struttura di oggetti socket ( WSK_SOCKET) per il nuovo socket.

Un'applicazione WSK può ottenere un elenco di protocolli di trasporto disponibili chiamando la funzione WskControlClient con il codice di controllo WSK_TRANSPORT_LIST_QUERY. WskControlClient restituisce un elenco di strutture WSK_TRANSPORT che contengono tutte le combinazioni valide dei parametri SocketType e Protocol.

Il sottosistema WSK determina la famiglia di indirizzi per il nuovo socket dalla famiglia di indirizzi specificata nella struttura SOCKADDR a cui punta il parametro LocalAddress.

Se l'applicazione WSK deve impostare un'opzione socket o eseguire un'operazione di controllo I/O sul socket prima dell'associazione o della connessione del socket, l'applicazione WSK deve chiamare il WskSocket, WskBinde funzioni WskConnect invece di chiamare la funzione WskSocketConnect.

Quando un'applicazione WSK crea correttamente un nuovo socket, tutte le funzioni di callback degli eventi nel nuovo socket sono disabilitate per impostazione predefinita. Per altre informazioni sull'abilitazione di una delle funzioni di callback degli eventi del nuovo socket, vedere Abilitazione e disabilitazione delle funzioni di callback degli eventi.

Se un'applicazione WSK specifica un puntatore null nonnull per il parametro securityDescriptor, non deve rilasciare il descrittore di sicurezza memorizzato nella cache fino al completamento dell'IRP.

Il sottosistema WSK alloca la memoria per la struttura di oggetti socket (WSK_SOCKET) per il nuovo socket 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