PFN_WSK_SOCKET_CONNECT funzione di callback (wsk.h)

Articolo
03/05/2024

La funzione WskSocketConnect crea un nuovo socket orientato alla connessione, lo associa a un indirizzo di trasporto locale, lo connette a un determinato indirizzo di trasporto remoto 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 WskCaptureProviderNPI .

[in] SocketType

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

SOCK_STREAM

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

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 in fase di creazione.

[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 in fase di creazione.

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 di 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, questo puntatore deve essere impostato 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, questo puntatore deve essere impostato 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 non NULL , 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 dei runtime di integrazione con le funzioni WSK, vedere Using IRPs with Winsock Kernel Functions .For more information about using IRPs with WSK functions, see Using IRPs with Winsock Kernel Functions.

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 dell'IRP .
Altri codici di stato	Si è verificato un errore. L'IRP verrà completato con lo stato di errore.

Commenti

Se l'IRP viene completato con lo stato di esito positivo, il campo IoStatus.Information dell'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 contiene 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 di I/O sul socket prima dell'associazione o della connessione del socket, l'applicazione WSK deve chiamare le funzioni WskSocket, WskBind e WskConnect anziché chiamare la funzione WskSocketConnect .

Quando un'applicazione WSK crea correttamente un nuovo socket, tutte le funzioni di callback degli eventi nel nuovo socket vengono 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 non NULL 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.

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