PFN_WSK_SOCKET funzione di callback (wsk.h)

Articolo
08/08/2023

La funzione WskSocket crea un nuovo socket e restituisce un puntatore all'oggetto socket associato.

Sintassi

PFN_WSK_SOCKET PfnWskSocket;

NTSTATUS PfnWskSocket(
  [in]           PWSK_CLIENT Client,
  [in]           ADDRESS_FAMILY AddressFamily,
  [in]           USHORT SocketType,
  [in]           ULONG Protocol,
  [in]           ULONG Flags,
  [in, optional] PVOID SocketContext,
  [in, optional] const VOID *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 dell'oggetto Funzione WskCaptureProviderNPI .

[in] AddressFamily

Famiglia di indirizzi per il socket creato. Per altre informazioni sulle famiglie di indirizzi supportate, vedere Famiglie di indirizzi WSK.

[in] SocketType

Tipo di socket creato. Sono supportati i tipi di socket seguenti:

SOCK_STREAM

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

SOCK_DGRAM

Supporta le comunicazioni datagrammi non affidabili.

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 creato. Per altre informazioni sui protocolli supportati per ogni famiglia di indirizzi supportata, vedere Famiglie di indirizzi WSK.

[in] Flags

Flag che specifica la categoria socket WSK per il socket creato. Questo parametro può essere uno dei flag seguenti:

WSK_FLAG_BASIC_SOCKET

Verrà creato un socket di base che può essere usato solo per ottenere e impostare le opzioni del socket dello stack di trasporto o per eseguire operazioni di controllo di I/O socket.

WSK_FLAG_LISTEN_SOCKET

Verrà creato un socket di ascolto che può essere usato per ascoltare le connessioni in ingresso da indirizzi di trasporto remoto.

WSK_FLAG_DATAGRAM_SOCKET

Verrà creato un socket di datagram che può essere usato per inviare e ricevere datagrammi.

WSK_FLAG_CONNECTION_SOCKET

Verrà creato un socket orientato alla connessione che può essere usato per inviare e ricevere dati di rete tramite una connessione.

WSK_FLAG_STREAM_SOCKET

Verrà creato un socket di flusso che può essere usato per ascoltare le connessioni in ingresso da indirizzi di trasporto remoto o inviare e ricevere dati di rete tramite una connessione.

Se un'applicazione WSK non specifica uno dei flag precedenti, WskSocket crea un socket di base.

[in, optional] SocketContext

Puntatore a un contesto fornito dal chiamante per il socket creato. 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 a pagina. Se l'applicazione WSK non abilita alcuna funzione di callback eventi nel nuovo socket, deve impostare questo puntatore su NULL. Per un socket di base, questo puntatore deve sempre essere NULL.

[in, optional] Dispatch

Puntatore a una struttura di invio client costante. Questa struttura è una tabella di invio che contiene puntatori alle funzioni di callback dell'evento per il nuovo socket. A seconda della categoria socket WSK del socket (come specificato dal parametro Flags ), questo parametro è un puntatore a una delle strutture seguenti.

Contrassegno	Struttura della tabella dispatch
WSK_FLAG_LISTEN_SOCKET	WSK_CLIENT_LISTEN_DISPATCH
WSK_FLAG_DATAGRAM_SOCKET	WSK_CLIENT_DATAGRAM_DISPATCH
WSK_FLAG_CONNECTION_SOCKET	WSK_CLIENT_CONNECTION_DISPATCH
WSK_FLAG_STREAM_SOCKET	WSK_CLIENT_STREAM_DISPATCH

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 tali funzioni di callback degli eventi che non abilita. Se l'applicazione WSK non abilita alcuna funzione di callback eventi nel nuovo socket, deve impostare il puntatore Dispatch su NULL. Per un socket di base, questo puntatore deve sempre essere NULL.

[in, optional] OwningProcess

Puntatore al processo da cui il sottosistema WSK recupera 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 recupera 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 di SECURITY_DESCRIPTOR che specifica il descrittore di sicurezza da applicare al socket creato. 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 chiamante allocato IRP usato dal sottosistema WSK per completare la creazione del nuovo socket in modo asincrono. Per altre informazioni sull'uso di IRP con funzioni WSK, vedere Uso di IRP con Funzioni kernel Winsock.

Valore restituito

WskSocket 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	Impossibile creare immediatamente il socket nel sottosistema WSK. 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 AddressFamily, SocketType e Protocol .

Quando un'applicazione WSK crea correttamente un nuovo socket, tutte le funzioni di callback evento 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 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