WpUCreateSocketHandle, fonction (ws2spi.h)

Article
08/28/2023

La fonction WPUCreateSocketHandle crée un descripteur de socket.

Syntaxe

SOCKET WPUCreateSocketHandle(
  [in]  DWORD     dwCatalogEntryId,
  [in]  DWORD_PTR dwContext,
  [out] LPINT     lpErrno
);

Paramètres

[in] dwCatalogEntryId

Descripteur identifiant le fournisseur de services appelant.

[in] dwContext

Valeur de contexte à associer au nouveau handle de socket.

[out] lpErrno

Pointeur vers le code d’erreur.

Valeur retournée

Si aucune erreur ne se produit, WPUCreateSocketHandle retourne le nouveau handle de socket. Sinon, elle retourne INVALID_SOCKET et un code d’erreur spécifique est disponible dans lpErrno.

Code d'erreur	Signification
WSAENOBUFS	Il n’y a pas suffisamment de mémoires tampons disponibles pour créer le nouveau handle de socket.

Remarques

La fonction WPUCreateSocketHandle crée un descripteur de socket pour le fournisseur spécifié. Les handles créés par WPUCreateSocketHandle ne sont pas reconnaissables des vrais handles de système de fichiers. C’est important à deux égards. Tout d’abord, l’architecture Windows Socket 2 s’occupe de rediriger les fonctions de système de fichiers ReadFile et WriteFile vers les fonctions LPWSPRecv et LPWSPSend de ce fournisseur de services, respectivement. Deuxièmement, dans les systèmes d’exploitation qui prennent en charge les ports d’achèvement, l’architecture Windows Sockets 2 prend en charge l’association d’un port d’achèvement au handle de socket et son utilisation pour signaler l’achèvement des E/S qui se chevauchent.

**Remarque** Le mécanisme de redirection de ReadFile et WriteFile implique nécessairement une transition utilisateur-noyau pour accéder au redirecteur, suivie d’une transition noyau-utilisateur pour accéder à [LPWSPRecv](nc-ws2spi-lpwsprecv.md) ou [LPWSPSend](nc-ws2spi-lpwspsend.md). Au retour, ces transitions sont retracées à l’envers. Il peut s’agir d’une pénalité importante en matière de performances. Tout fournisseur de services qui utilise **WPUCreateSocketHandle** pour créer ses descripteurs de socket ne doit pas définir XP1_IFS_HANDLES dans sa structure WSAProtocol_Info . Les clients doivent prendre en compte l’absence de XP1_IFS_HANDLES pour éviter d’utiliser **ReadFile** et **WriteFile**.

**Remarque** L’utilisation du mécanisme de port d’achèvement avec des handles de socket créés avec **WPUCreateSocketHandle**n’entraîne aucune pénalité de performances exceptionnelle. Un fournisseur de services doit utiliser WPUCompleteOverlappedRequest pour annoncer l’achèvement des opérations d’E/S qui se chevauchent et qui peuvent impliquer un port d’achèvement. Les clients peuvent utiliser librement les fonctions du système d’exploitation pour créer, associer et utiliser un port d’achèvement pour la notification d’achèvement (par exemple, CreateIoCompletionPort, GetQueuedCompletionStatus, consultez la documentation correspondante sur le système d’exploitation pour plus d’informations). Notez que les ports d’achèvement ne sont pas intégrés aux autres mécanismes de notification asynchrone proposés par Windows Sockets 2. Autrement dit, un client peut effectuer une attente multiple qui inclut plusieurs événements et rappels d’achèvement, mais il n’existe aucun moyen prédéfini pour l’attente multiple d’inclure des ports d’achèvement.

**Considérations relatives au fournisseur de services en couches**

Cette procédure présente un intérêt particulier pour les fournisseurs de services en couches. Un fournisseur de services en couches peut utiliser cette procédure, au lieu de WPUModifyIFSHandle pour créer les handles de socket qu’il expose à son client. L’avantage de cette procédure est que toutes les demandes d’E/S impliquant le socket peuvent être garanties de passer par ce fournisseur de services. Cela est vrai même si le client suppose que les sockets sont des handles de système de fichiers et appelle les fonctions de système de fichiers ReadFile et WriteFile (bien qu’il paierait une pénalité de performances pour cette hypothèse).

La garantie que toutes les E/S passent par cette couche est une exigence pour les couches qui doivent traiter le flux d’E/S avant ou après l’opération d’E/S réelle. La création de handles de socket à l’aide de WPUCreateSocketHandle et la spécification d’une table de répartition de procédure d’interface de fournisseur de services appropriée au moment de WSPStartup garantissent que la couche a la possibilité de participer au démarrage de chaque opération d’E/S. Lorsque le client demande des opérations d’E/S qui se chevauchent, cette couche de fournisseur de services doit généralement s’organiser pour accéder également au chemin d’accès de la notification d’achèvement des E/S.

Pour voir pourquoi cela est vrai, réfléchissez à ce qui se passe si le client associe un port d’achèvement au handle de socket pour la notification d’achèvement d’E/S qui se chevauche. Le port est associé au handle de socket exposé par cette couche, et non au handle de socket de la couche suivante. Il n’existe aucun moyen pour cette couche de déterminer si un port d’achèvement a été associé ou quel est le port. Lorsque cette couche appelle l’opération d’E/S de la couche suivante, elle utilise le handle de socket de la couche suivante. Le handle de socket de la couche suivante n’aura pas la même association de port d’achèvement. La notification de port d’achèvement attendue du client ne se produit pas sans une aide supplémentaire.

La façon habituelle pour un fournisseur de services en couches de s’en occuper consiste à remplacer une structure d’E/S différente et des paramètres d’E/S qui se chevauchent différents lors de l’appel d’une opération d’E/S dans la couche suivante. La structure d’E/S superposée de remplacement fait référence à la structure et aux paramètres superposés stockés du client. L’appel de la couche suivante configure une notification de rappel. Lorsque la notification de rappel se produit, cette couche effectue tout post-traitement souhaité, récupère les informations d’E/S superposées qu’elle a stockées pour le compte du client, ignore les structures de remplacement et transmet une notification d’achèvement appropriée au client.

Spécifications


Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	ws2spi.h