Fonction de rappel LPWSPASYNCSELECT (ws2spi.h)
La fonction LPWSPAsyncSelect demande une notification d’événements réseau basée sur un message Windows pour un socket.
Syntaxe
LPWSPASYNCSELECT Lpwspasyncselect;
int Lpwspasyncselect(
[in] SOCKET s,
[in] HWND hWnd,
[in] unsigned int wMsg,
[in] long lEvent,
[out] LPINT lpErrno
)
{...}
Paramètres
[in] s
Descripteur identifiant le socket pour lequel une notification d’événement est requise.
[in] hWnd
Gérer l’identification de la fenêtre qui doit recevoir un message lorsqu’un événement réseau se produit.
[in] wMsg
Message à envoyer lorsqu’un événement réseau se produit.
[in] lEvent
Masque de bits qui spécifie une combinaison d’événements réseau dans lesquels le client SPI (Service Provider Interface) Windows Sockets est intéressé. Construit à l’aide de l’opérateur OR au niveau du bit avec l’une de ces valeurs.
| Valeur | Signification |
|---|---|
|
Émet une notification de préparation à la lecture. |
|
Émet une notification de préparation à l’écriture. |
|
Émet une notification de l’arrivée des données OOB. |
|
Émet une notification des connexions entrantes. |
|
Émet une notification des connexions terminées. |
|
Émet une notification de fermeture de socket. |
|
Émet une notification de modification de la qualité de service (QoS) du socket. |
|
Réservé. |
|
Émet une notification de modification de l’interface de routage pour la destination spécifiée. |
|
Émet une notification de modification de la liste d’adresses locale pour la famille de protocoles du socket. |
[out] lpErrno
Pointeur vers le code d’erreur. Pour plus d’informations, consultez la section Valeur de retour.
Valeur retournée
La valeur de retour est égale à zéro si la déclaration d’intérêt du client SPI Windows Sockets dans le jeu d’événements réseau a réussi. Sinon, la valeur SOCKET_ERROR est retournée et un code d’erreur spécifique est disponible dans lpErrno.
| Code d'erreur | Signification |
|---|---|
| Le sous-système réseau a échoué. | |
| Indique que l’un des paramètres spécifiés n’était pas valide, comme le handle de fenêtre ne faisant pas référence à une fenêtre existante, ou que le socket spécifié n’est pas dans un état non valide. | |
| Un appel Windows Sockets bloquant est en cours ou le fournisseur de services traite toujours une fonction de rappel. | |
| Le descripteur n’est pas un socket. |
Consultez Remarques pour plus d’informations sur les codes d’erreur supplémentaires qui peuvent être définis (dans le mot élevé de lParam dans le message) lorsqu’une fenêtre d’application reçoit un message.
Remarques
Cette fonction est utilisée pour demander au fournisseur de services d’envoyer un message Windows à la fenêtre du client hWnd chaque fois que le fournisseur de services détecte l’un des événements réseau spécifiés par l’argument lEvent . Le fournisseur de services doit utiliser la fonction WPUPostMessage pour publier le message. Le message à envoyer est spécifié par le paramètre wMsg . Le socket pour lequel la notification est requise est identifié par s.
Cette fonction définit automatiquement les sockets en mode non bloquant, quelle que soit la valeur de lEvent. Consultez LPWSPIoctl pour savoir comment remettre le socket en mode bloquant.
L’appel de LPWSPAsyncSelect pour un socket annule tout LPWSPAsyncSelect ou LPWSPEventSelect précédent pour le même socket. Par exemple, pour recevoir une notification pour la lecture et l’écriture, le client SPI Windows Sockets doit appeler LPWSPAsyncSelect avec FD_READ et FD_WRITE, comme ceci.
rc = WSPAsyncSelect(s, hWnd, wMsg, FD_READ | FD_WRITE, &error);
Il n’est pas possible de spécifier des messages différents pour différents événements. Le code suivant ne fonctionne pas ; Le deuxième appel annule les effets du premier, et la seule association sera l’événement FD_WRITE associé à wMsg2.
// Incorrect example.
rc = WSPAsyncSelect(s, hWnd, wMsg1, FD_READ, &error);
rc = WSPAsyncSelect(s, hWnd, wMsg2, FD_WRITE, &error);
Pour annuler toutes les notifications (autrement dit, pour indiquer que le fournisseur de services ne doit envoyer aucun autre message lié aux événements réseau sur le socket), définissez lEvent sur zéro.
rc = WSPAsyncSelect(s, hWnd, 0, 0, &error);
Étant donné qu’un socket LPWSPAccept’ed a les mêmes propriétés que le socket d’écoute utilisé pour l’accepter, tous les événements LPWSPAsyncSelect définis pour le socket d’écoute s’appliquent au socket accepté. Par exemple, si un socket d’écoute a des événements LPWSPAsyncSelect FD_ACCEPT, FD_READ et FD_WRITE, tout socket accepté sur ce socket d’écoute aura également des événements FD_ACCEPT, FD_READ et FD_WRITE avec la même valeur wMsg utilisée pour les messages. Si un wMsg ou des événements différents sont souhaités, le client SPI Windows Sockets doit appeler LPWSPAsyncSelect, en passant le socket accepté et les nouvelles informations souhaitées.
Quand l’un des événements réseau désignés se produit sur les sockets spécifiés, le fournisseur de services utilise WPUPostMessage pour envoyer un message wMsg à la fenêtre hWnd du client SPI windows Sockets. Dans le message publié, l’argument wParam identifie le socket sur lequel un événement réseau s’est produit. Le mot bas de lParam spécifie l’événement réseau qui s’est produit. Les codes d’événement réseau possibles qui peuvent être indiqués sont les suivants.
| Valeur | Signification |
|---|---|
| FD_READ | Le socket est prêt pour la lecture |
| FD_WRITE | Le socket est prêt pour l’écriture |
| FD_OOB | Les données hors bande sont prêtes pour la lecture sur les sockets |
| FD_ACCEPT | Le socket est prêt à accepter une nouvelle connexion entrante |
| FD_CONNECT | La connexion qui a été lancée sur le socket s est terminée |
| FD_CLOSE | La connexion identifiée par le socket s a été fermée |
| FD_QOS | La qualité de service associée aux sockets a changé |
| FD_GROUP_QOS | Réservé pour une utilisation ultérieure avec les groupes de sockets : la qualité de service associée au groupe de sockets auquel appartient le socket s a changé |
| FD_ROUTING_INTERFACE_CHANGE | L’interface locale qui doit être utilisée pour envoyer à la destination spécifiée a changé |
| FD_ADDRESS_LIST_CHANGE | La liste des adresses de la famille de protocoles du socket à laquelle le client SPI Windows Sockets peut lier a changé. |
Le mot élevé de lParam contient n’importe quel code d’erreur (il peut être extrait à l’aide de la macro WSAGETSELECTERROR ). Le code d’erreur est toute erreur définie dans ws2spi.h. Les codes d’erreur possibles pour chaque événement réseau sont répertoriés dans le tableau suivant.
Événement : FD_CONNECT
| Code d'erreur | Signification |
|---|---|
| Impossible d'utiliser les adresses figurant dans la famille spécifiée avec ce socket. | |
| La tentative de connexion a été rejetée. | |
| Le réseau ne peut pas être atteint à partir de cet hôte en ce moment. | |
| Le paramètre namelen n’est pas valide. | |
| Le socket est déjà lié à une adresse. | |
| Le socket est déjà connecté. | |
| Aucun autre descripteur de fichier n'est disponible. | |
| Aucune zone tampon disponible. Le socket ne peut pas être connecté. | |
| Le socket n'est pas connecté. | |
| La tentative de connexion a expiré sans établir de connexion. |
Événement : FD_CLOSE
| Code d'erreur | Signification |
|---|---|
| Échec du sous-système réseau. | |
| La connexion a été réinitialisée par le côté distant. | |
| La connexion a été arrêtée en raison d’un délai d’attente ou d’un autre échec. |
Événement... : FD_ACCEPT, FD_ADDRESS_LIST_CHANGE, FD_GROUP_QOS, FD_OOB, FD_QOS, FD_READ, FD_WRITE
| Code d'erreur | Signification |
|---|---|
| Échec du sous-système réseau. |
Événement : FD_ROUTING_INTERFACE_CHANGE
| Code d'erreur | Signification |
|---|---|
| La destination spécifiée n’est plus accessible. | |
| Échec du sous-système réseau. |
Bien que LPWSPAsyncSelect puisse être appelé avec intérêt dans plusieurs événements, le fournisseur de services émet le même message Windows pour chaque événement.
Un fournisseur Windows Sockets 2 ne doit pas continuellement inonder un client SPI Windows Sockets avec des messages pour un événement réseau particulier. Une fois que la notification d’un événement particulier a été correctement publiée dans une fenêtre cliente SPI Windows Sockets, aucun autre message pour cet événement réseau n’est publié dans la fenêtre cliente SPI windows Sockets jusqu’à ce que le client SPI Windows Sockets effectue l’appel de fonction qui réactive implicitement la notification de cet événement réseau.
| Événement réseau | Réactivation de la fonction |
|---|---|
| FD_READ | LPWSPRecv ou LPWSPRecvFrom |
| FD_WRITE | LPWSPSend ou LPWSPSendTo |
| FD_OOB | LPWSPRecv ou LPWSPRecvFrom |
| FD_ACCEPT | LPWSPAccept, sauf si le code d’erreur retourné est WSATRY_AGAIN indiquant que la fonction condition retournée CF_DEFER |
| FD_CONNECT | Aucune |
| FD_CLOSE | Aucune |
| FD_QOS | LPWSPIoctl avec SIO_GET_QOS |
| FD_GROUP_QOS | Réservé à une utilisation ultérieure avec les groupes de sockets : LPWSPIoctl avec SIO_GET_GROUP_QOS |
| FD_ROUTING_INTERFACE_CHANGE | LPWSPIoctl avec SIO_ROUTING_INTERFACE_CHANGE de commande |
| FD_ADDRESS_LIST_CHANGE | LPWSPIoctl avec SIO_ADDRESS_LIST_CHANGE de commande |
Tout appel à la routine de réactivation, même en cas d’échec, entraîne la réactivation de la publication de messages pour l’événement approprié.
Pour les événements FD_READ, FD_OOB et FD_ACCEPT, la publication de messages est déclenchée au niveau. Cela signifie que si la routine de réactivation est appelée et que la condition appropriée est toujours remplie après l’appel, un message LPWSPAsyncSelect est publié sur le client SPI Windows Sockets.
Les événements FD_QOS et FD_GROUP_QOS sont considérés comme déclenchés en périphérie. Un message est publié exactement une fois lorsqu’une modification qoS se produit. D’autres messages ne seront pas envoyés tant que le fournisseur n’aura pas détecté une nouvelle modification de qos ou que le client SPI Windows Sockets renégocie la QOS pour le socket.
Les événements FD_ROUTING_INTERFACE_CHANGE et FD_ADDRESS_LIST_CHANGE sont également considérés comme déclenchés par la périphérie . Un message est publié exactement une fois lorsqu’une modification se produit après que le client SPI Windows Sockets a demandé la notification en émettant WSAIoctl avec SIO_ROUTING_INTERFACE_CHANGE ou SIO_ADDRESS_LIST_CHANGE correspondant. D’autres messages ne seront pas à venir tant que le client SPI Windows Sockets n’aura pas réédité le IOCTL et qu’une autre modification est détectée depuis que le IOCTL a été émis.
Si un événement s’est déjà produit lorsque le client SPI Windows Sockets appelle LPWSPAsyncSelect, ou lorsque la fonction de réactivation est appelée, un message est publié comme il convient. Par exemple, considérez la séquence suivante.
- Un client SPI Windows Sockets appelle LPWSPListen.
- Une demande de connexion est reçue, mais pas encore acceptée.
- Le client SPI Windows Sockets appelle LPWSPAsyncSelect en spécifiant qu’il souhaite recevoir FD_ACCEPT messages pour le socket. En raison de la persistance des événements, le fournisseur de services WinSock publie immédiatement un message FD_ACCEPT.
L’événement FD_WRITE est géré légèrement différemment. Un message FD_WRITE est publié lorsqu’un socket est connecté à LPWSPConnect (après FD_CONNECT, s’il est également inscrit) ou accepté avec LPWSPAccept, puis après qu’un LPWSPSend ou LPWSPSPSendTo échoue avec WSAEWOULDBLOCK et que l’espace tampon soit disponible. Par conséquent, un client SPI Windows Sockets peut supposer que les envois sont possibles à partir du premier FD_WRITE message et durent jusqu’à ce qu’un envoi retourne WSAEWOULDBLOCK. Après un tel échec, le client SPI Windows Sockets est averti que les envois sont à nouveau possibles avec un message FD_WRITE.
L’événement FD_OOB est utilisé uniquement lorsqu’un socket est configuré pour recevoir des données hors bande séparément. Si le socket est configuré pour recevoir des données hors bande en ligne, les données hors bande (accélérées) sont traitées comme des données normales, et le client SPI windows Sockets doit inscrire un intérêt pour les événements FD_READ, et non FD_OOB événements.
Le code d’erreur d’un message FD_CLOSE indique si la fermeture du socket était normale ou abandonnée. Si le code d’erreur est 0, la fermeture était normale ; si le code d’erreur est WSAECONNRESET, le circuit virtuel du socket a été réinitialisé. Cela s’applique uniquement aux sockets orientés connexion tels que SOCK_STREAM.
Le message FD_CLOSE est publié lorsqu’une indication proche est reçue pour le circuit virtuel correspondant au socket. En termes TCP, cela signifie que l’FD_CLOSE est publié lorsque la connexion passe aux états WAIT OU CLOSE WAIT. Cela résulte du fait que l’extrémité distante effectue un LPWSPShutdown côté envoi ou un LPWSPCloseSocket. Il est correct que FD_CLOSE ne soit publié qu’une fois que toutes les données ont été lues à partir d’un socket.
Dans le cas d’une fermeture normale, le fournisseur de services doit envoyer un message FD_CLOSE pour indiquer la fermeture du circuit virtuel uniquement une fois que toutes les données reçues ont été lues. Il ne doit pas envoyer de message FD_READ pour indiquer cette condition.
Le message FD_QOS ou FD_GROUP_QOS est publié lorsqu’une modification a été apportée à un champ dans la spécification de flux associée au socket s ou au groupe de sockets auquel appartient , respectivement. Le fournisseur de services doit mettre à jour les informations QOS disponibles pour le client via LPWSPIoctl avec SIO_GET_QOS et/ou SIO_GET_GROUP_QOS.
Le message FD_ROUTING_INTERFACE_CHANGE est publié lorsque l’interface locale qui doit être utilisée pour atteindre la destination spécifiée dans LPWSPIoctl avec SIO_ROUTING_INTERFACE_CHANGE modifications après l’émission de ce type IOCTL.
Le message FD_ADDRESS_LIST_CHANGE est publié lorsque la liste des adresses auxquelles le client SPI Windows Sockets peut lier des modifications aprèsl’émission de LPWSPIoctl avec SIO_ADDRESS_LIST_CHANGE a été émise.
Voici un résumé des événements et des conditions pour chaque message de notification asynchrone.
FD_READ
- Lorsque LPWSPAsyncSelect est appelé, s’il existe des données actuellement disponibles à recevoir.
- Lorsque les données arrivent, si FD_READ pas déjà publiée.
- Une fois LPWSPRecv ou LPWSPRecvFrom appelé (avec ou sans MSG_PEEK), si les données sont toujours disponibles pour recevoir.
Lorsque LPWSPSetSockOpt SO_OOBINLINE est activé, les données incluent à la fois des données normales et des données hors bande (OOB) dans les instances mentionnées ci-dessus.
FD_WRITE
- Lorsque LPWSPAsyncSelect est appelé, si un LPWSPSend ou LPWSPSendTo est possible.
- Après l’appel de LPWSPConnect ou LPWSPAccept , lorsque la connexion est établie.
- Après l’échec de LPWSPSend ou LPWSPSendTo avec WSAEWOULDBLOCK, lorsque LPWSPSend ou LPWSPSendTo est susceptible de réussir.
- Après LPWSPBind sur un socket sans connexion. FD_WRITE peut ou non se produire à ce stade (dépendant de l’implémentation). Dans tous les cas, un socket sans connexion est toujours accessible en écriture immédiatement après LPWSPBind.
FD_OOB (valide uniquement lorsque le SO_OOBINLINE LPWSPSetSockOpt est désactivé (par défaut))
- Lorsque LPWSPAsyncSelect est appelé, s’il existe des données OOB actuellement disponibles à recevoir avec l’indicateur MSG_OOB.
- Lorsque les données OOB arrivent, si FD_OOB pas déjà publiées.
- Une fois que LPWSPRecv ou LPWSPRecvFrom est appelé avec ou sans indicateur MSG_OOB, si les données OOB sont toujours disponibles pour recevoir.
FD_ACCEPT
- Lorsque LPWSPAsyncSelect est appelé, s’il existe actuellement une demande de connexion disponible à accepter.
- Lorsqu’une demande de connexion arrive, si FD_ACCEPT pas déjà publiée.
- Une fois LPWSPAccept appelé, s’il existe une autre demande de connexion disponible à accepter.
FD_CONNECT
- Lorsque LPWSPAsyncSelect est appelé, s’il existe actuellement une connexion établie.
- Après l’appel de LPWSPConnect , lorsque la connexion est établie (même lorsque LPWSPConnect réussit immédiatement, comme c’est le cas généralement avec un socket de datagramme), et même en cas d’échec immédiat).
- Une fois WSPJoinLeaf appelé, lorsque l’opération de jointure est terminée.
- Après la connexion, WSAConnect ou WSPJoinLeaf a été appelé avec un socket orienté connexion non bloquant. L’opération initiale a été retournée avec une erreur spécifique de WSAEWOULDBLOCK, mais l’opération réseau a été effectuée. Que l’opération aboutisse ou non, lorsque le résultat a été déterminé, FD_CONNECT se produit. Le client doit case activée le code d’erreur pour déterminer si le résultat était un succès ou un échec.
FD_CLOSE (valide uniquement sur les sockets orientés connexion (par exemple, SOCK_STREAM))
- Lorsque LPWSPAsyncSelect est appelé, si la connexion de socket a été fermée.
- Une fois que le système distant a lancé une fermeture normale, lorsqu’aucune donnée n’est actuellement disponible pour recevoir (si des données ont été reçues et attendent d’être lues lorsque le système distant lance une fermeture normale, le FD_CLOSE n’est pas remis tant que toutes les données en attente n’ont pas été lues).
- Une fois que le système local a lancé une fermeture normale avec LPWSPShutdown et que le système distant a répondu avec une notification de fin de données (par exemple, TCP FIN), quand aucune donnée n’est actuellement disponible à recevoir.
- Lorsque le système distant abandonne la connexion (par exemple, tcp RST envoyé), et lParam contient la valeur d’erreur WSAECONNRESET.
FD_CLOSE n’est pas publié après l’appel de LPWSPCloseSocket .
FD_QOS
- Lorsque LPWSPAsyncSelect est appelé, si la QOS associée au socket a été modifiée.
- Après LPWSPIoctl avec SIO_GET_QOS est appelée, lorsque la QOS est modifiée.
FD_GROUP_QOS
Réservé pour une utilisation ultérieure avec des groupes de sockets :
- Lorsque LPWSPAsyncSelect est appelé, si la QOS de groupe associée au socket a été modifiée.
- Après LPWSPIoctl avec SIO_GET_GROUP_QOS est appelée, lorsque la QOS de groupe est modifiée.
FD_ROUTING_INTERFACE_CHANGE
- après LPWSPIoctl avec SIO_ROUTING_INTERFACE_CHANGE est appelé, lorsque l’interface locale qui doit être utilisée pour atteindre la destination spécifiée dans l’IOCTL change.
FD_ADDRESS_LIST_CHANGE
- après LPWSPIoctl avec SIO_ADDRESS_LIST_CHANGE est appelée, lorsque la liste des adresses locales auxquelles le client SPI Windows Sockets peut lier des modifications.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows 10 Build 20348 |
| Serveur minimal pris en charge | Windows 10 Build 20348 |
| En-tête | ws2spi.h |
Voir aussi
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour