WSCInstallProviderAndChains64_32, fonction (ws2spi.h)
La fonction WSCInstallProviderAndChains64_32 installe le fournisseur de transport spécifié et ses chaînes de protocoles spécifiques dans les bases de données de configuration système Winsock 2 32 bits et 64 bits sur un ordinateur 64 bits. Cette fonction garantit que les chaînes de protocole sont triées au début des informations de configuration du fournisseur de transport, ce qui rend inutile un appel distinct à WSCWriteProviderOrder .
Syntaxe
int WSCInstallProviderAndChains64_32(
[in] LPGUID lpProviderId,
[in] const LPWSTR lpszProviderDllPath,
[in] const LPWSTR lpszProviderDllPath32,
[in] const LPWSTR lpszLspName,
[in] DWORD dwServiceFlags,
[in] LPWSAPROTOCOL_INFOW lpProtocolInfoList,
[in] DWORD dwNumberOfEntries,
[out, optional] LPDWORD lpdwCatalogEntryId,
[out] LPINT lpErrno
);
Paramètres
[in] lpProviderId
Pointeur vers un identificateur global unique (GUID) pour le fournisseur.
[in] lpszProviderDllPath
Pointeur vers une chaîne Unicode qui contient le chemin de chargement de la DLL 64 bits du fournisseur. Cette chaîne respecte les règles habituelles de résolution de chemin d’accès et peut contenir des chaînes d’environnement incorporées (telles que %SystemRoot%). Ces chaînes d’environnement sont développées lorsque le Ws2_32.dll doit ensuite charger la DLL du fournisseur pour le compte d’une application. Une fois les chaînes d’environnement incorporées développées, le Ws2_32.dll transmet la chaîne résultante à la fonction LoadLibrary qui charge le fournisseur en mémoire. Pour plus d’informations, consultez LoadLibrary.
[in] lpszProviderDllPath32
Pointeur vers une chaîne Unicode qui contient le chemin complet de la DLL 32 bits du fournisseur. Cette chaîne respecte les règles habituelles de résolution de chemin d’accès et peut contenir des chaînes d’environnement incorporées (telles que %SystemRoot%). Ces chaînes d’environnement sont développées lorsque le Ws2_32.dll charge par la suite la DLL du fournisseur pour le compte d’une application. Une fois les chaînes d’environnement incorporées développées, le Ws2_32.dll transmet la chaîne résultante à la fonction LoadLibrary pour charger le fournisseur en mémoire. Pour plus d’informations, consultez LoadLibrary.
[in] lpszLspName
Pointeur vers une chaîne Unicode qui contient le nom du fournisseur de services en couches (LSP).
[in] dwServiceFlags
Indicateurs de service pour le type d’entrée de catalogue de protocoles en couches à créer. Une entrée de protocole en couches est une structure WSAProtocol_Info avec le membre ChainLen défini sur 0. L’entrée de catalogue réelle pour le LSP référencera l’ID de cette entrée de protocole en couches dans son membre ProtocolChain .
[in] lpProtocolInfoList
Pointeur vers un tableau de structures WSAProtocol_Info . Chaque structure définit un protocole, une famille d’adresses et un type de socket pris en charge par le fournisseur. Les membres de la structure WSAPROTOCOL_INFO examinés sont iProtocol, iAddressFamily et iSocketType.
[in] dwNumberOfEntries
Nombre d’entrées dans le tableau lpProtocolInfoList .
[out, optional] lpdwCatalogEntryId
Pointeur vers l’entrée de protocole en couches nouvellement installée pour le fournisseur de transport dans la base de données de configuration système Winsock 2. Il s’agissait de l’ID utilisé pour générer les entrées de chaîne de protocole installées dans le catalogue pour le LSP.
[out] lpErrno
Pointeur vers le code d’erreur généré par l’appel en cas d’échec de la fonction.
Valeur retournée
Si WSCInstallProviderAndChains64_32 réussit, elle retourne zéro. Sinon, elle retourne SOCKET_ERROR et un code d’erreur spécifique est retourné dans le paramètre lpErrno .
| Code d'erreur | Signification |
|---|---|
| Un ou plusieurs arguments ne se trouve pas dans une partie valide de l’espace d’adressage utilisateur. | |
| Un ou plusieurs arguments ne sont pas valides. Cette erreur est retournée pour les conditions suivantes : le paramètre lpProviderId est **NULL**, le paramètre lpszProviderDllPath n’est pas valide ou la longueur du chemin d’accès est trop grande (**MAX_PATH** a été dépassé), le paramètre lpszLspName n’est pas valide ou la longueur du nom est trop grande (**WSAPROTOCOL_LEN** est dépassé), lpProtocolInfoList est défini sur non-**NULL** et dwNumberOfEntries Le paramètre est égal à zéro, un ID de fournisseur en double ou le nom du fournisseur de services en couches existe déjà dans le catalogue, ou une correspondance est introuvable pour le protocole, la famille d’adresses et le type de socket spécifiés. | |
|
Les fonctionnalités requises du fournisseur sont manquantes. Un fournisseur non-IFS doit implémenter toutes les fonctions d’extension Winsock 2 (AcceptEx, ConnectEx, DisconnectEx, TransmitFile, TransmitPackets et LPFN_WSARECVMSG (WSARecvMsg)). |
| L’installation d’un fournisseur est déjà en cours. | |
| La mémoire ne peut pas être allouée pour les mémoires tampons. | |
| Une erreur non récupérable s’est produite. Cette erreur est retournée dans plusieurs conditions, notamment : le fournisseur est déjà installé, le paramètre lpProtocolInfoList était **NULL** et aucun fournisseur de base n’a été trouvé, la longueur maximale de la chaîne de protocole (**MAX_PROTOCOL_CHAIN**) a été atteinte, l’utilisateur n’a pas les privilèges administratifs requis pour écrire dans le Registre Winsock ou un échec s’est produit lors de la création ou de l’installation d’une entrée de catalogue. | |
| Un appel système qui ne devrait jamais échouer a échoué. |
Remarques
WSCInstallProviderAndChains64_32 est une version améliorée de la fonction de WSCInstallProvider64_32 de base utilisée pour installer un seul fournisseur de services de transport. Si un fournisseur de services en couches est installé, WSCInstallProviderAndChains64_32 devez être utilisé. WSCInstallProviderAndChains64_32 pouvez installer un protocole en couches et une ou plusieurs chaînes de protocoles avec un seul appel de fonction. Pour accomplir le même travail à l’aide de WSCInstallProvider64_32 nécessite plusieurs appels de fonction.
Winsock 2 prend en charge les protocoles en couches. Un protocole en couches est un protocole qui implémente uniquement des fonctions de communication de niveau supérieur tout en s’appuyant sur une pile de transport sous-jacente pour l’échange réel de données avec un point de terminaison distant. Un exemple de protocole en couches serait une couche de sécurité qui ajoute un protocole au processus d’établissement de la connexion afin d’effectuer l’authentification et d’établir un schéma de chiffrement mutuellement convenu. Un tel protocole de sécurité nécessite généralement les services d’un protocole de transport fiable sous-jacent, tel que TCP ou SPX. Le terme protocole de base fait référence à un protocole tel que TCP ou SPX qui est capable d’effectuer des communications de données avec un point de terminaison distant. Le terme protocole en couches est utilisé pour décrire un protocole qui ne peut pas être autonome. Une chaîne de protocole serait alors définie comme un ou plusieurs protocoles en couches, liés entre eux et ancrés par un protocole de base. Un protocole de base a le membre ChainLen de la structure WSAProtocol_Info défini sur BASE_PROTOCOL qui est défini sur 1. Un protocole en couches a le membre ChainLen de la structure WSAPROTOCOL_INFO définie sur LAYERED_PROTOCOL qui est défini sur zéro. Une chaîne de protocole a le membre ChainLen de la structure WSAPROTOCOL_INFO défini sur supérieur à 1.
WSCInstallProviderAndChains64_32 est la version 64 bits de WSCInstallProviderAndChains. Il installe le fournisseur dans les catalogues 32 bits et 64 bits sur les plateformes 64 bits. Cela signifie que sur les plateformes 64 bits, deux catalogues Winsock sont gérés et que les processus 32 bits et 64 bits sont en mesure de charger le LSP installé avec cette fonction.
Sur un ordinateur 64 bits, tous les appels qui ne sont pas spécifiquement conçus pour le 32 bits (par exemple, toutes les fonctions qui ne se terminent pas par « 32 ») fonctionnent sur le catalogue 64 bits natif. Les processus qui s’exécutent sur un ordinateur 64 bits doivent utiliser WSCInstallProviderAndChains64_32 pour fonctionner à la fois sur le catalogue 32 bits et sur le catalogue 64 bits, tout en préservant la compatibilité. Les définitions et la sémantique des appels 32 bits spécifiques sont les mêmes que leurs équivalents natifs.
Si lpProtocolInfoList a la valeur NULL, cette fonction crée des chaînes de protocoles où le fournisseur est superposé sur le protocole de base pour chaque type de protocole unique tel que défini par la famille d’adresses, le type de socket et le protocole. Cela élimine la création de toutes les entrées de fournisseur en double inaccessibles.
Si lpProtocolInfoList est défini sur une valeur non NULL , cette fonction crée des chaînes de protocoles en obtenant l’entrée la plus élevée dans les informations de configuration qui correspond au tuple {address family, socket type, protocol} de chaque élément du tableau fourni. Là encore, seul le tuple {address family, socket type, protocol} est pris en compte ; tous les autres membres et doublons sont ignorés.
Une fois cet appel terminé, tous les appels suivants à WSAEnumProtocols, WSCEnumProtocols ou WSCEnumProtocols32 retournent les entrées de chaîne de protocole nouvellement créées. N’oubliez pas que dans les environnements Windows, seules les instances de Ws_32.dll créées en appelant WSAStartup après la réussite de WSCInstallProviderAndChains64_32 incluent les nouvelles entrées lorsque WSAEnumProtocols, WSCEnumProtocols et WSCEnumProtocols32 retournent.
En cas de réussite, WSCInstallProviderAndChains64_32 tentez d’alerter toutes les applications intéressées qui se sont inscrites pour la notification de la modification en appelant WSAProviderConfigChange.
La fonction WSCInstallProviderAndChains64_32 ne peut être appelée que par un utilisateur connecté en tant que membre du groupe Administrateurs. Si WSCInstallProviderAndChains64_32 est appelé par un utilisateur qui n’est pas membre du groupe Administrateurs, l’appel de fonction échoue et WSANO_RECOVERY est retourné dans le paramètre lpErrno . Pour les ordinateurs exécutant Windows Vista ou Windows Server 2008, cette fonction peut également échouer en raison du contrôle de compte d’utilisateur (UAC). Si une application qui contient cette fonction est exécutée par un utilisateur connecté en tant que membre du groupe Administrateurs autre que l’administrateur intégré, cet appel échoue, sauf si l’application a été marquée dans le fichier manifeste avec un requestedExecutionLevel défini sur requireAdministrator. Si l’application sur Windows Vista ou Windows Server 2008 ne dispose pas de ce fichier manifeste, un utilisateur connecté en tant que membre du groupe Administrateurs autre que l’administrateur intégré doit ensuite exécuter l’application dans un interpréteur de commandes amélioré en tant qu’administrateur intégré (administrateur d’exécution) pour que cette fonction réussisse.
Toute installation de fichier ou configuration spécifique au fournisseur doit être effectuée par l’application appelante.
Fournisseurs IFS et non-IFS
Un fournisseur IFS est un fournisseur qui retourne des descripteurs de système d’exploitation natifs. En règle générale, ces handles sont associés aux pilotes de protocole en mode noyau. Par exemple, les fournisseurs TCP/IPv4 de base, UDP/IPv4, TCP/IPv6 et UDP/IPv6 sont des fournisseurs IFS, car ces entrées correspondent à un composant en mode noyau. Les handles IFS peuvent être utilisés dans les appels de fonction **ReadFile**, **WriteFile** et **CancelIo**. Un fournisseur de services en couches qui est un fournisseur IFS retourne simplement le handle de socket créé à partir du fournisseur inférieur (qui doit également être un fournisseur IFS) directement à l’application appelante. Un LSP IFS ne peut pas intercepter les notifications d’achèvement pour les appels Winsock.Un fournisseur non-IFS est un fournisseur qui crée un handle intermédiaire avec WPUCreateSocketHandle et retourne ce handle à l’appelant. Cela permet à un LSP non-IFS d’intercepter les événements d’envoi et de réception avant les applications appelantes pour permettre le post-traitement (par exemple, déchiffrer un bloc de données reçu). Les handles de socket non-IFS peuvent être utilisés dans les appels à ReadFile et WriteFile, mais ne peuvent pas être utilisés avec CancelIo. La seule méthode garantie d’annulation d’une opération sur un handle non-IFS consiste à fermer le socket avec closesocket.
Chemins d’accès pour les DLL de fournisseur 32 bits et 64 bits
lpszProviderDllPath représente le chemin d’accès complet à la version 64 bits de la DLL du fournisseur. Ce paramètre peut contenir des chaînes d’environnement incorporées (telles que %SystemRoot%).lpszProviderDllPath32 représente le chemin complet de la version 32 bits de la DLL du fournisseur. Ce paramètre peut contenir des chaînes d’environnement incorporées (telles que %SystemRoot%).
Si lpszProviderDllPath32 a la valeur NULL, lpszProviderDllPath est le chemin d’accès pour les fournisseurs 32 et 64 bits. Lorsqu’un processus 32 bits sur un ordinateur 64 bits est en cours d’exécution (par exemple, lorsqu’une application Winsock charge la version 32 bits d’un LSP), elle tente de charger le fournisseur 32 bits spécifié dans lpszProviderDllPath. Si lpszProviderDllPath32 a la valeur NULL, le paramètre lpszProviderDllPath doit être défini sur %windir%\system32< ; dllname>. Si ce n’est pas le cas, l’appel échoue avec WSAEINVAL. Si le chemin dans lpszProviderDllPath est %windir%\system32< ; dllname> lorsque lpszProviderDllPath32 a la valeur NULL, l’appel est redirigé (à l’aide du redirecteur du système de fichiers) vers le répertoire retourné par GetSystemWow64Directory où le LSP 32 bits doit résider. Pour Windows XP édition 64 bits, Windows Server 2003 et Windows Vista, ce répertoire est %windir%\syswow64.
Configuration requise
| Client minimal pris en charge | Windows Vista [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2008 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | ws2spi.h |
| Bibliothèque | Ws2_32.lib |
| DLL | Ws2_32.dll |
Voir aussi
Configuration et installation du transport