Fonction de rappel LPNSPIOCTL (ws2spi.h)
La fonction NSPIoctl envoie un IOCTL à un fournisseur de services d’espace de noms.
Syntaxe
LPNSPIOCTL Lpnspioctl;
INT Lpnspioctl(
[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,
[in] LPWSATHREADID lpThreadId
)
{...}
Paramètres
[in] hLookup
Handle de recherche retourné par un appel précédent à la fonction NSPLookupServiceBegin .
[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 |
|---|---|
|
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 NSPLookupServiceBegin pour récupérer le paramètre hLookup . Ces appels précédents peuvent également inclure des appels à la fonction NSPLookupServiceNext à 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).
[in] lpThreadId
Pointeur vers une structure WSATHREADID à utiliser par le fournisseur dans un appel ultérieur à WPUQueueApc. Le fournisseur doit stocker la structure WSATHREADID référencée (et non le pointeur) jusqu’à ce que la fonction WPUQueueApc soit retournée.
Valeur retournée
Si aucune erreur ne se produit et que l’opération est terminée immédiatement, la fonction NSPIoctl doit retourner NO_ERROR (zéro). Notez que dans ce cas, la routine d’achèvement, si elle est spécifiée, aura déjà été mise en file d’attente.
La fonction NSPIoctl doit retourner SOCKET_ERROR (autrement dit, 1) si la routine échoue et qu’elle doit définir le code d’erreur approprié à l’aide de WSASetLastError.
Le code d’erreur WSA_IO_PENDING indique qu’une opération qui se chevauche a été lancée avec succès et que l’achèvement sera indiqué ultérieurement. Tout autre code d’erreur indique qu’aucune opération chevauchée n’a été lancée et qu’aucune indication d’achèvement ne se produira.
| Code d'erreur | Description |
|---|---|
| Le paramètre hLookup n’était pas un handle de requête valide retourné par NSPLookupServiceBegin. | |
| Une opération qui se chevauche a été lancée avec succès et l’achèvement sera indiqué ultérieurement. | |
| 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. | |
| 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. | |
| Le sous-système réseau a échoué. | |
| 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. | |
|
La ressource est temporairement indisponible. Le socket n’utilise pas d’E/S superposées (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 NSPIoctl est utilisée pour envoyer un code de contrôle d’E/S à un fournisseur d’espace de noms afin de définir ou de récupérer les paramètres d’exploitation associés à un handle de requête. 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 NSPLookupServiceBegin (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 NSPIoctl , 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 NSPIoctl 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 NSPIoctl s’exécute comme un appel bloquant. Le fournisseur d’espace de noms doit revenir immédiatement et ne doit pas bloquer. Mais chaque fournisseur d’espaces de noms est responsable de l’application de ce comportement.
Le code IOCTL suivant est pris en charge par plusieurs fournisseurs d’espaces de noms Microsoft :
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’a pas la valeur NULL et pointe vers une structure WSACOMPLETION , la fonction NSPIoctl 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 NSPIoctl est la suivante. Appelez la fonction NSPIoctl 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 NSPLookupServiceNext pour vous assurer que les données de requête sont toujours valides. Si les données deviennent non valides, appelez la fonction NSPLookupServiceEnd pour fermer le handle de requête. Appelez la fonction NSPLookupServiceBegin 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 NSPIoctl est la suivante. Appelez la fonction NSPIoctl 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 NSPLookupServiceBegin . 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 NSPLookupServiceEnd pour fermer le handle de requête. Appelez les fonctions NSPLookupServiceBegin et NSPIoctl 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 gourmandes en ressources, 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 NSPLookupServiceEnd 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.
Spécifications
| Client minimal pris en charge | Windows XP [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | ws2spi.h |