PFN_WSK_SOCKET fonction de rappel (wsk.h)

Article
08/08/2023

La fonction WskSocket crée un nouveau socket et retourne un pointeur vers l’objet socket associé.

Syntaxe

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
)
{...}

Paramètres

[in] Client

Pointeur vers une structure WSK_CLIENT qui a été retournée via le paramètre WskProviderNpi du Fonction WskCaptureProviderNPI .

[in] AddressFamily

Famille d’adresses pour le socket en cours de création. Pour plus d’informations sur les familles d’adresses prises en charge, consultez Familles d’adresses WSK.

[in] SocketType

Type de socket en cours de création. Les types de sockets suivants sont pris en charge :

SOCK_STREAM

Prend en charge une communication fiable de flux d’octets orientée connexion.

SOCK_DGRAM

Prend en charge la communication de datagramme sans connexion fiable.

SOCK_RAW

Prend en charge l’accès brut au protocole de transport.

Pour plus d’informations sur les types de sockets pris en charge pour chaque famille d’adresses prise en charge, consultez
Familles d’adresses WSK.

[in] Protocol

Protocole de transport du socket en cours de création. Pour plus d’informations sur les protocoles pris en charge pour chaque famille d’adresses prise en charge, consultez Familles d’adresses WSK.

[in] Flags

Indicateur qui spécifie la catégorie de socket WSK pour le socket en cours de création. Ce paramètre peut être l’un des indicateurs suivants :

WSK_FLAG_BASIC_SOCKET

Un socket de base sera créé qui ne peut être utilisé que pour obtenir et définir les options de socket de pile de transport ou pour effectuer des opérations de contrôle d’E/S de socket.

WSK_FLAG_LISTEN_SOCKET

Un socket d’écoute sera créé qui peut être utilisé pour écouter les connexions entrantes à partir d’adresses de transport distantes.

WSK_FLAG_DATAGRAM_SOCKET

Un socket de datagramme sera créé qui peut être utilisé pour envoyer et recevoir des datagrammes.

WSK_FLAG_CONNECTION_SOCKET

Un socket orienté connexion sera créé qui peut être utilisé pour envoyer et recevoir des données réseau via une connexion.

WSK_FLAG_STREAM_SOCKET

Un socket de flux sera créé qui peut soit être utilisé pour écouter les connexions entrantes à partir d’adresses de transport distantes, soit envoyer et recevoir des données réseau via une connexion.

Si une application WSK ne spécifie aucun des indicateurs précédents, WskSocket crée un socket de base.

[in, optional] SocketContext

Pointeur vers un contexte fourni par l’appelant pour le socket en cours de création. Le sous-système WSK transmet ce pointeur aux fonctions de rappel d’événements du socket. Les informations de contexte sont opaques pour le sous-système WSK et doivent être stockées dans une mémoire non paginée. Si l’application WSK n’active aucune fonction de rappel d’événement sur le nouveau socket, elle doit définir ce pointeur sur NULL. Pour un socket de base, ce pointeur doit toujours avoir la valeur NULL.

[in, optional] Dispatch

Pointeur vers une structure de répartition de client constante. Cette structure est une table de répartition qui contient des pointeurs vers les fonctions de rappel d’événement pour le nouveau socket. Selon la catégorie de socket WSK du socket (comme spécifié par le paramètre Flags ), ce paramètre est un pointeur vers l’une des structures suivantes.

Indicateur	Structure de table de répartition
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

Si l’application WSK n’active pas toutes les fonctions de rappel d’événements pour le nouveau socket, elle doit définir les pointeurs de la table dispatch sur NULL pour les fonctions de rappel d’événements qu’elle n’active pas. Si l’application WSK n’active aucune fonction de rappel d’événement sur le nouveau socket, elle doit définir le pointeur Dispatch sur NULL. Pour un socket de base, ce pointeur doit toujours avoir la valeur NULL.

[in, optional] OwningProcess

Pointeur vers le processus à partir duquel le sous-système WSK récupère le contexte de sécurité à utiliser lorsqu’il lie le socket. Le sous-système WSK utilise le contexte de sécurité pour déterminer si l’adresse de transport locale peut être partagée si cette adresse est déjà utilisée. Pour spécifier le processus actuel, une application WSK définit ce pointeur sur NULL.

[in, optional] OwningThread

Pointeur vers un thread spécifique à partir duquel le sous-système WSK récupère le contexte de sécurité à utiliser lorsqu’il lie le socket. Le sous-système WSK utilise le contexte de sécurité pour déterminer si l’adresse de transport locale peut être partagée si cette adresse est déjà utilisée. Si une application WSK n’a pas besoin de spécifier un thread spécifique, elle définit ce pointeur sur NULL.

[in, optional] SecurityDescriptor

Pointeur vers une structure de SECURITY_DESCRIPTOR qui spécifie le descripteur de sécurité à appliquer au socket en cours de création. Le descripteur de sécurité contrôle le partage de l’adresse de transport locale à laquelle le socket est lié. Si une application WSK spécifie un pointeur non NULL , elle doit spécifier un pointeur vers une copie mise en cache d’un descripteur de sécurité obtenu en appelant la fonction WskControlClient avec le code de contrôle WSK_CACHE_SD . Pour spécifier un descripteur de sécurité par défaut qui n’autorise pas le partage de l’adresse de transport locale, une application WSK définit SecurityDescriptor sur NULL.

Pour plus d’informations sur la structure SECURITY_DESCRIPTOR, consultez la page de référence pour SECURITY_DESCRIPTOR dans la documentation Microsoft Windows SDK.

[in, out] Irp

Pointeur vers un IRP alloué à l’appelant que le sous-système WSK utilise pour terminer la création du nouveau socket de manière asynchrone. Pour plus d’informations sur l’utilisation des irps avec des fonctions WSK, consultez Utilisation des irps avec les fonctions du noyau Winsock.

Valeur retournée

WskSocket retourne l’un des codes NTSTATUS suivants :

Code de retour	Description
STATUS_SUCCESS	Le nouveau socket a été créé avec succès. Le IRP sera terminé avec succès status.
STATUS_PENDING	Le sous-système WSK n’a pas pu créer le socket immédiatement. Le sous-système WSK termine l’IRP une fois qu’il a créé le nouveau socket. Le status de la création du socket sera retourné dans le champ IoStatus.Status de l’IRP.
Autres codes status	Une erreur est survenue. L’IRP sera terminé avec l’échec status.

Remarques

Si l’IRP est terminé avec succès status, le champ IoStatus.Information de l’IRP contient un pointeur vers une structure d’objet socket (WSK_SOCKET) pour le nouveau socket.

Une application WSK peut obtenir la liste des protocoles de transport disponibles en appelant la fonction WskControlClient avec le code de contrôle WSK_TRANSPORT_LIST_QUERY . WskControlClient retourne une liste de structures WSK_TRANSPORT qui contient toutes les combinaisons valides des paramètres AddressFamily, SocketType et Protocol .

Lorsqu’une application WSK crée correctement un nouveau socket, toutes les fonctions de rappel d’événement sur le nouveau socket sont désactivées par défaut. Pour plus d’informations sur l’activation de l’une des fonctions de rappel d’événements du nouveau socket, consultez Activation et désactivation des fonctions de rappel d’événements.

Si une application WSK spécifie un pointeur non NULL pour le paramètre SecurityDescriptor , elle ne doit pas libérer le descripteur de sécurité mis en cache tant qu’une fois l’IRP terminé.

Le sous-système WSK alloue la mémoire pour la structure d’objet socket (WSK_SOCKET) pour le nouveau socket pour le compte de l’application WSK. Le sous-système WSK libère cette mémoire lorsque le socket est fermé.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans Windows Vista et les versions ultérieures des systèmes d’exploitation Windows.
Plateforme cible	Universal
En-tête	wsk.h (inclure Wsk.h)
IRQL	<= DISPATCH_LEVEL