PFN_WSK_SOCKET_CONNECT fonction de rappel (wsk.h)

Article
08/08/2023

La fonction WskSocketConnect crée un nouveau 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 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] 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é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.

[in, optional] Dispatch

Pointeur vers une constante WSK_CLIENT_CONNECTION_DISPATCH structure. 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é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 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 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

WskSocketConnect 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 SocketType et Protocol .

Le sous-système WSK détermine la famille d’adresses du nouveau socket à partir de la famille d’adresses spécifiée dans la structure SOCKADDR vers laquelle pointe 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 de lier ou de connecter le socket, l’application WSK doit appeler les fonctions WskSocket, WskBind et WskConnect au lieu d’appeler la fonction WskSocketConnect .

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