Fonction WPUModifyIFSHandle (ws2spi.h)

Article
08/28/2023

La fonction WPUModifyIFSHandle reçoit un handle IFS (éventuellement) modifié de Ws2_32.dll.

Syntaxe

SOCKET WPUModifyIFSHandle(
  [in]  DWORD  dwCatalogEntryId,
  [in]  SOCKET ProposedHandle,
  [out] LPINT  lpErrno
);

Paramètres

[in] dwCatalogEntryId

Descripteur identifiant le fournisseur de services appelant.

[in] ProposedHandle

Handle IFS alloué par le fournisseur.

[out] lpErrno

Pointeur vers le code d’erreur.

Valeur retournée

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

Code d'erreur	Signification
WSAEINVAL	Le handle proposé n’est pas valide.

Remarques

Le handle WPUModifyIFSHandle permet au WS2_32.dll de rationaliser ses opérations internes en retournant une version éventuellement modifiée du handle IFS fourni. Il est garanti que le handle retourné ne peut pas être séparé du handle proposé en ce qui concerne le système d’exploitation. Les fournisseurs IFS doivent appeler cette fonction avant de renvoyer tout descripteur de socket nouvellement créé à un fournisseur de services. Le fournisseur de services n’utilisera le handle modifié que pour les opérations de socket suivantes. Cette routine n’est utilisée que par les fournisseurs IFS dont les descripteurs de socket sont de vrais handles IFS.

**Considérations relatives aux fournisseurs de services en couches**

Cette procédure peut également être utilisée par un fournisseur en couches qui est superposé à un fournisseur IFS de base et souhaite exposer les handles de socket du fournisseur de base en tant que propres au lieu de les créer avec un appel WPUCreateSocketHandle . Un fournisseur en couches qui souhaite « transmettre » le socket IFS qu’il reçoit de la couche suivante de la chaîne peut appeler WPUModifyIFSHandle, en passant son propre ID d’entrée de catalogue comme dwCatalogEntryId. Cela informe la DLL des sockets Windows que cette couche, et non la couche suivante, doit être la cible pour les appels SPI impliquant ce handle de socket.

Il existe plusieurs limitations qu’un fournisseur en couches doit observer s’il adopte cette approche.

Le fournisseur doit exposer les points d’entrée du fournisseur de base pour LPWSPSend et LPWSPRecv dans la table de répartition de procédure qu’il retourne au moment de WSPStartup pour s’assurer que l’accès du client SPI windows Sockets à ces fonctions est aussi efficace que possible.
Le fournisseur ne peut pas compter sur ses fonctions LPWSPSend et LPWSPRecv appelées pour toutes les E/S, en particulier dans le cas des fonctions système d’E/S ReadFile et WriteFile. Ces fonctions contournent le fournisseur en couches et appellent directement l’implémentation du fournisseur IFS de base, même si le fournisseur en couche place ses propres points d’entrée pour ces fonctions dans la table de répartition de procédure.
Le fournisseur ne peut compter sur aucune capacité à post-traiter les E/S qui se chevauchent à l’aide de LPWSPSend, LPWSPSendTo, LPWSPRecv,LPWSPRecvFrom ou LPWSPIoctl. La notification post-traitement peut se produire via les ports d’achèvement et contourner entièrement le fournisseur en couches. Un fournisseur en couches n’a aucun moyen de déterminer qu’un port d’achèvement a été utilisé ou de déterminer de quel port il s’agit. Le fournisseur en couches n’a aucun moyen de s’insérer dans la séquence de notification.
Le fournisseur doit passer toutes les demandes d’E/S qui se chevauchent directement au fournisseur de base à l’aide des paramètres d’origine qui se chevauchent (par exemple, la structure WSAOVERLAPPED et le pointeur de routine d’achèvement). Le fournisseur doit exposer le point d’entrée du fournisseur de base pour WSPGetOverlappedResult. Étant donné que certaines demandes d’E/S qui se chevauchent peuvent contourner complètement le fournisseur en couches, le fournisseur en couches ne peut pas marquer de manière fiable les structures WSAOVERLAPPED pour déterminer celles pour lesquelles il peut signaler des résultats et lesquelles doivent être transmises au WSPGetOverlappedResult du fournisseur sous-jacent. Cela signifie effectivement que LPWSPIoctl doit être une opération directe vers le fournisseur sous-jacent.

Configuration requise

Condition requise	Valeur
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