PFN_WSK_SOCKET fonction de rappel (wsk.h)
La fonction WskSocket crée un 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 du 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 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] 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 est créé qui peut être utilisé uniquement 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 est créé qui peut être utilisé pour écouter les connexions entrantes à partir d’adresses de transport distantes.
WSK_FLAG_DATAGRAM_SOCKET
Un socket de datagramme est créé qui peut être utilisé pour envoyer et recevoir des datagrammes.
WSK_FLAG_CONNECTION_SOCKET
Un socket orienté connexion est 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 est créé qui peut être utilisé pour écouter les connexions entrantes à partir d’adresses de transport distantes, ou 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é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. Pour un socket de base, ce pointeur doit toujours être NULL.
[in, optional] Dispatch
Pointeur vers une structure de répartition constante du client. 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.
| Drapeau | Structure de table 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 |
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 le pointeur Dispatch sur NULL. Pour un socket de base, ce pointeur doit toujours être 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
WskSocket retourne l’un des codes NTSTATUS suivants :
| Retourner le code | Description |
|---|---|
|
Le nouveau socket a été créé avec succès. L’IRP sera terminé avec l’état de réussite. |
|
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. |
|
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 AddressFamily, SocketTypeet Protocol.
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 |