PFN_WSK_SOCKET_CONNECT fonction de rappel (wsk.h)

Article
02/07/2025

La fonction WskSocketConnect crée un socket orienté connexion, le lie à une adresse de transport locale, le connecte à une adresse de transport distante donnée et retourne un pointeur vers l’objet socket associé.

Syntaxe

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

Paramètres

[in] Client

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

[in] SocketType

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

SOCK_STREAM

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

SOCK_DGRAM

Prend en charge la connexion non fiable, sans communication de datagramme.

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 pour le 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] LocalAddress

Pointeur vers une structure qui spécifie l’adresse de transport locale à laquelle lier le socket. L’application WSK doit spécifier un pointeur vers le type de structure SOCKADDR spécifique qui correspond à la famille d’adresses du socket en cours de création.

[in] RemoteAddress

Pointeur vers une structure qui spécifie l’adresse de transport distante à laquelle connecter le socket. L’application WSK doit spécifier un pointeur vers le type de structure SOCKADDR spécifique qui correspond à la famille d’adresses du socket en cours de création.

Flags

Ce paramètre est réservé à l’utilisation du système. Les applications WSK doivent définir ce paramètre sur zéro.

[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énement du socket. Les informations de contexte sont opaques sur le sous-système WSK et doivent être stockées en 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.

[in, optional] Dispatch

Pointeur vers une constante structure WSK_CLIENT_CONNECTION_DISPATCH. Cette structure est une table de répartition qui contient des pointeurs vers les fonctions de rappel d’événement pour le nouveau socket. Si l’application WSK n’active pas toutes les fonctions de rappel d’événement pour le nouveau socket, elle doit définir les pointeurs dans la table de distribution sur NULL pour ces 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 ce pointeur sur 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 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 pointeurNULL non, il 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 du Kit de développement logiciel (SDK) Microsoft Windows.

[in, out] Irp

Pointeur vers un IRP alloué par 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 d’IRPs avec des fonctions WSK, consultez Utilisation d’IRPs avec winsock Kernel Functions.

Valeur de retour

WskSocketConnect retourne l’un des codes NTSTATUS suivants :

Retourner le code	Description
STATUS_SUCCESS	Le nouveau socket a été créé avec succès. L’IRP sera terminé avec l’état de réussite.
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. L’état de la création du socket est retourné dans le champ IoStatus.Status du protocole IRP.
Autres codes d’état	Une erreur s’est produite. L’IRP est terminé avec l’état d’échec.

Remarques

Si l’IRP est terminé avec l’état de réussite, 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 socketType et Protocol.

Le sous-système WSK détermine la famille d’adresses du nouveau socket de la famille d’adresses spécifiée dans la structure SOCKADDR pointée par le paramètre LocalAddress.

Si l’application WSK doit définir une option de socket ou émettre une opération de contrôle d’E/S sur le socket avant la liaison ou la connexion du socket, l’application WSK doit appeler les fonctions WskSocket, WskBindet fonctions WskConnect au lieu d’appeler la fonction WskSocketConnect.

Lorsqu’une application WSK crée 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 Fonctions d’activation et de désactivation des fonctions de rappel d’événements.

Si une application WSK spécifie un pointeur deNULL non pour le paramètre SecurityDescriptor, il ne doit pas libérer le descripteur de sécurité mis en cache tant que l’IRP n’est pas terminé.

Le sous-système WSK alloue la mémoire de la structure d’objets de 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é.

Exigences

Exigence	Valeur
client minimum pris en charge	Disponible dans Windows Vista et versions ultérieures des systèmes d’exploitation Windows.
plateforme cible	Universel
d’en-tête	wsk.h (include Wsk.h)
IRQL	<= DISPATCH_LEVEL