PFN_WSK_SOCKET_CONNECT fonction de rappel (wsk.h)
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 |
|---|---|
|
Le nouveau socket a été créé avec succès. Le IRP sera terminé avec succès status. |
|
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. |
|
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 |