Fonction WSANSPIoctl (winsock2.h)

Article
08/27/2023

La fonction WSANSPIoctl des sockets Windows permet aux développeurs d’effectuer des appels de contrôle d’E/S à un espace de noms inscrit.

Syntaxe

INT WSAAPI WSANSPIoctl(
  [in]      HANDLE          hLookup,
  [in]      DWORD           dwControlCode,
  [in]      LPVOID          lpvInBuffer,
  [in, out] DWORD           cbInBuffer,
  [out]     LPVOID          lpvOutBuffer,
  [in]      DWORD           cbOutBuffer,
  [out]     LPDWORD         lpcbBytesReturned,
  [in]      LPWSACOMPLETION lpCompletion
);

Paramètres

[in] hLookup

Handle de recherche retourné par un appel précédent à la fonction WSALookupServiceBegin .

[in] dwControlCode

Code de contrôle de l’opération à effectuer.

Les valeurs qui peuvent être utilisées pour le paramètre dwControlCode sont déterminées par le fournisseur d’espaces de noms.

La valeur suivante est prise en charge par plusieurs fournisseurs d’espaces de noms Microsoft, notamment le fournisseur d’espaces de noms Network Location Awareness (NS_NLA). Ce IOCTL est défini dans le fichier d’en-tête Winsock2.h.

Valeur	Signification
SIO_NSP_NOTIFY_CHANGE	Cette opération vérifie si les résultats retournés avec les appels précédents à l’aide du paramètre hLookup sont toujours valides. Ces appels précédents incluent l’appel initial à la fonction WSALookupServiceBegin pour récupérer le paramètre hLookup . Ces appels précédents peuvent également inclure des appels à la fonction WSALookupServiceNext à l’aide du paramètre hLookup .

Valeur

Signification

SIO_NSP_NOTIFY_CHANGE

Cette opération vérifie si les résultats retournés avec les appels précédents à l’aide du paramètre hLookup sont toujours valides. Ces appels précédents incluent l’appel initial à la fonction WSALookupServiceBegin pour récupérer le paramètre hLookup . Ces appels précédents peuvent également inclure des appels à la fonction WSALookupServiceNext à l’aide du paramètre hLookup .

[in] lpvInBuffer

Pointeur vers la mémoire tampon d’entrée.

[in, out] cbInBuffer

Taille, en octets, de la mémoire tampon d’entrée.

[out] lpvOutBuffer

Pointeur vers la mémoire tampon de sortie.

[in] cbOutBuffer

Taille, en octets, de la mémoire tampon de sortie.

[out] lpcbBytesReturned

Pointeur vers le nombre d’octets retournés.

[in] lpCompletion

Pointeur vers une structure WSACOMPLETION , utilisé pour le traitement asynchrone. Définissez lpCompletion surNULL pour forcer l’exécution bloquante (synchrone).

Valeur retournée

Success retourne NO_ERROR. L’échec retourne SOCKET_ERROR, et un code d’erreur spécifique peut être récupéré en appelant la fonction WSAGetLastError . Le tableau suivant décrit les codes d’erreur.

Code d'erreur	Description
WSA_INVALID_HANDLE	Le paramètre hLookup n’était pas un handle de requête valide retourné par WSALookupServiceBegin.
WSA_IO_PENDING	Une opération qui se chevauche a été lancée avec succès et l’achèvement sera indiqué ultérieurement.
WSAEFAULT	L’argument lpvInBuffer, cbInBuffer, lpvOutBuffer, cbOutBuffer ou lpCompletion n’est pas entièrement contenu dans une partie valide de l’espace d’adressage utilisateur. Sinon, l’argument cbInBuffer ou cbOutBuffer est trop petit et l’argument est modifié pour refléter la taille d’allocation requise.
WSAEINVAL	Un paramètre fourni n’est pas acceptable, ou l’opération retourne de manière inappropriée les résultats de plusieurs espaces de noms lorsqu’elle n’a pas de sens pour l’opération spécifiée.
WSAENETDOWN	Le sous-système réseau a échoué.
WSAEOPNOTSUPP	L'opération n'est pas prise en charge. Cette erreur est retournée si le fournisseur d’espaces de noms n’implémente pas cette fonction. Cette erreur peut également être retournée si le dwControlCode spécifié est une commande non reconnue.
WSAEWOULDBLOCK	Le socket n’utilise pas d’E/S qui se chevauchent (traitement asynchrone), mais le paramètre lpCompletion n’est pas NULL. Cette erreur est utilisée comme notification spéciale pour le SIO_NSP_NOTIFY_CHANGE IOCTL lorsque le paramètre lpCompletion a la valeur NULL (un sondage) pour indiquer qu’un jeu de requêtes reste valide.

Remarques

La fonction WSANSPIoctl est utilisée pour définir ou récupérer des paramètres d’exploitation associés à un handle de requête sur un fournisseur d’espace de noms. Le paramètre hLookup est un handle de la requête du fournisseur d’espace de noms précédemment retournée par la fonction WSALookupServiceBegin (et non un handle de socket).

Tout IOCTL envoyé à un fournisseur d’espaces de noms peut être bloqué indéfiniment, en fonction de l’implémentation de l’espace de noms. Si une application ne peut pas tolérer le blocage dans un appel de fonction WSANSPIoctl , les E/S qui se chevauchent doivent être utilisées et le paramètre lpCompletion doit pointer vers une structure WSACOMPLETION . Pour rendre un appel de fonction WSANSPIoctl non bloquant et retourner immédiatement, définissez le membre Type de la structure WSACOMPLETIONsur NSP_NOTIFY_IMMEDIATELY.

Si lpCompletion a la valeur NULL, la fonction WSANSPIoctl s’exécute comme un appel bloquant. Le fournisseur d’espace de noms doit revenir immédiatement et ne doit pas bloquer. Mais chaque espace de noms est responsable de l’application de ce comportement.

Le code IOCTL suivant est pris en charge par plusieurs fournisseurs d’espace de noms Microsoft :

SIO_NSP_NOTIFY_CHANGE

Les fournisseurs d’espaces de noms Microsoft qui prennent en charge ce IOCTL sont les suivants :

NS_NLA : fournisseur d’espace de noms NLA (Network Location Awareness).
NS_PNRPNAME : fournisseur d’espaces de noms PNRP (Peer Name Resolution Protocol).
NS_PNRPCLOUD : fournisseur d’espaces de noms cloud PNRP (Peer Name Resolution Protocol).

D’autres fournisseurs d’espaces de noms autres que Microsoft peuvent être installés et prennent également en charge ce IOCTL.

Lorsque le paramètre lpCompletion a la valeur NULL, cette propriété IOCTL implémente un comportement spécial. Si le paramètre lpCompletion a la valeur NULL pour ce IOCTL, cette opération est un sondage et retourne immédiatement. Si le jeu de requêtes reste valide, WSAEWOULDBLOCK est retourné en tant que notification indiquant que le jeu de requêtes reste valide. Si le jeu de requêtes a changé et n’est pas valide, NO_ERROR est retourné indiquant que l’interrogation a réussi pour l’invalidation du jeu de requêtes.

Si le paramètre lpCompletion n’est pas NULL et pointe vers une structure WSACOMPLETION , la fonction WSANSPIoctl retourne WSA_IO_PENDING si l’opération superposée a été correctement lancée et que l’achèvement sera indiqué ultérieurement. La méthode spécifiée dans la structure WSACOMPLETION est utilisée pour informer l’application si le jeu de requêtes est toujours valide.

Tous les protocoles de résolution de noms ne sont pas en mesure de prendre en charge cette fonctionnalité. Par conséquent, cet appel de fonction peut échouer avec WSAEOPNOTSUPP. Une requête contenant des données provenant de plusieurs fournisseurs ne peut pas appeler ce IOCTL et retourne WSAEINVAL.

Les paramètres lpvInBuffer, cbInBuffer, lpvOutBuffer et cbOutBuffer sont actuellement ignorés par les fournisseurs d’espaces de noms Microsoft.

Pour les applications à thread unique, une méthode classique pour utiliser la fonction WSANSPIoctl est la suivante. Appelez la fonction WSANSPIoctl avec le paramètre dwControlCode défini sur SIO_NSP_NOTIFY_CHANGE sans routine d’achèvement (paramètre lpCompletion défini sur NULL) après chaque appel de fonction WSALookupServiceNext pour vous assurer que les données de requête sont toujours valides. Si les données deviennent non valides, appelez la fonction WSALookupServiceEnd pour fermer le handle de requête. Appelez la fonction WSALookupServiceBegin pour récupérer un nouveau handle de requête et recommencer la requête.

Pour les applications multithread, une méthode classique pour utiliser la fonction WSANSPIoctl est la suivante. Appelez la fonction WSANSPIoctl avec le paramètre dwControlCode défini sur SIO_NSP_NOTIFY_CHANGE avec une routine d’achèvement après l’appel initial à la fonction WSALookupServiceBegin . L’application utiliserait le mécanisme de notification spécifié dans la routine d’achèvement pour être avertie lorsque les données ne sont plus valides. Un mécanisme courant consiste à utiliser un événement spécifié dans la routine d’achèvement. Si les données deviennent non valides, appelez la fonction WSALookupServiceEnd pour fermer le handle de requête. Appelez les fonctions WSALookupServiceBegin et WSANSPIoctl pour récupérer un nouveau handle de requête et recommencer la requête.

Certains protocoles peuvent simplement mettre en cache les informations localement et les invalider après un certain temps, auquel cas une notification peut être émise pour indiquer que le cache local a été invalidé.

Pour les protocoles de résolution de noms pour lesquels les modifications sont peu fréquentes, il est possible pour un fournisseur d’espace de noms d’indiquer un événement de modification global qui peut ne pas s’appliquer à la requête sur laquelle la notification de modification a été demandée et émise.

Les opérations d’interrogation immédiates sont généralement beaucoup moins coûteuses, car elles ne nécessitent pas d’objet de notification. Dans la plupart des cas, il s’agit d’une simple variable booléenne case activée. Toutefois, la notification asynchrone peut nécessiter la création de threads de travail dédiés et/ou de canaux de communication interprocessus, en fonction de l’implémentation du service fournisseur d’espaces de noms, et entraîne une surcharge de traitement liée à l’objet de notification impliqué dans la signalisation de l’événement de modification.

Pour annuler une demande de notification asynchrone, terminez la requête d’origine avec un appel de fonction WSALookupServiceEnd sur le handle de requête affecté. L’annulation de la notification asynchrone pour LUP_NOTIFY_HWND ne publiera aucun message. Toutefois, une opération se chevauchera et la notification sera remise avec l’erreur WSA_OPERATION_ABORTED.

Note Toutes les E/S initiées par un thread donné sont annulées à la sortie de ce thread. Pour les sockets qui se chevauchent, les opérations asynchrones en attente peuvent échouer si le thread est fermé avant la fin des opérations. Pour plus d’informations, consultez ExitThread .

Windows Phone 8 : cette fonction est prise en charge pour les applications du Store Windows Phone Windows Phone 8 et versions ultérieures.

Windows 8.1 et Windows Server 2012 R2 : cette fonction est prise en charge pour les applications du Windows Store sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8.1, Windows Vista [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	winsock2.h