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 di funzione di WskCaptureProviderNPI.
[in] AddressFamily
Famiglia di indirizzi per il socket in fase di creazione. Per altre informazioni sulle famiglie di indirizzi supportate, vedere famiglie di indirizzi WSK.
[in] SocketType
Tipo di socket che viene creato. 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] Flags
Flag che specifica la categoria di socket WSK per il socket in fase di creazione. 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 restare in ascolto delle connessioni in ingresso da indirizzi di trasporto remoti.
WSK_FLAG_DATAGRAM_SOCKET
Verrà creato un socket di datagrammi 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 alcun flag precedente, WskSocket crea un socket di base.
[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. Per un socket di base, questo puntatore deve essere sempre NULL.
[in, optional] Dispatch
Puntatore a una struttura di invio client costante. Questa struttura è una tabella dispatch che contiene puntatori alle funzioni di callback degli eventi per il nuovo socket. A seconda della categoria di socket WSK del socket (come specificato dal parametro Flag), questo parametro è un puntatore a una delle strutture seguenti.
| Bandiera | 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 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 il puntatore dispatch su NULL. Per un socket di base, questo puntatore deve essere sempre 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
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. |
|
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. |
|
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 AddressFamily, SocketTypee Protocol.
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 |