PFN_WSK_SOCKET funzione di callback (wsk.h)
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_FLAG_DATAGRAM_SOCKET | WSK_CLIENT_DATAGRAM_DISPATCH |
| WSK_FLAG_CONNECTION_SOCKET | WSK_CLIENT_CONNECTION_DISPATCH |
| WSK_FLAG_STREAM_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 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 |
|---|---|
|
Il nuovo socket è stato creato correttamente. L'IRP verrà completato con lo stato di esito positivo. |
|
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 . |
|
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 |