Fonction de rappel LPWSPASYNCSELECT (ws2spi.h)
La fonction LPWSPAsyncSelect demande la notification d’événement basée sur les messages Windows des événements réseau 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 la notification d’événement est requise.
[in] hWnd
Gérez 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 (Windows Sockets Service Provider Interface) 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 la notification de l’arrivée des données OOB. |
|
Problèmes de notification des connexions entrantes. |
|
Émet la notification des connexions terminées. |
|
Émet une notification de fermeture de socket. |
|
Émet la notification des modifications de qualité de service (QoS) du socket. |
|
Réservé. |
|
Émet la notification de modification de l’interface de routage pour la destination spécifiée. |
|
Émet une notification de modification de 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 de retour
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 qu’un des paramètres spécifiés n’était pas valide, comme le handle de fenêtre qui ne fait pas référence à une fenêtre existante, ou que le socket spécifié est 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
Cette fonction définit automatiquement les de socket
L’appel LPWSPAsyncSelect pour un socket annule tout LPWSPAsyncSelect ou LPWSPEventSelect 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 suit.
rc = WSPAsyncSelect(s, hWnd, wMsg, FD_READ | FD_WRITE, &error);
Il n’est pas possible de spécifier différents messages pour différents événements. Le code suivant ne fonctionnera 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 toute notification (autrement dit, pour indiquer que le fournisseur de services ne doit pas envoyer d’autres messages liés 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 LPWSPAccept« le socket ed a les mêmes propriétés que le socket d’écoute utilisé pour l’accepter, tout LPWSPAsyncSelect événements définis pour le socket d’écoute s’applique au socket accepté. Par exemple, si un socket d’écoute a LPWSPAsyncSelect événements FD_ACCEPT, FD_READ et FD_WRITE, tous les sockets acceptés sur ce socket d’écoute auront également FD_ACCEPT, FD_READ et FD_WRITE événements avec la même valeur wMsg utilisée pour les messages. Si un autre wMsg ou les événements sont souhaités, le client SPI Windows Sockets doit appeler LPWSPAsyncSelect, en passant le socket accepté et les nouvelles informations souhaitées.
Lorsqu’un des événements réseau nommés se produit sur ledu socket spécifié
| Valeur | Signification |
|---|---|
| FD_READ | Le de socket |
| FD_WRITE | Le de socket |
| FD_OOB | Les données hors bande sont prêtes à être lues sur les de socket |
| FD_ACCEPT | Le de socket |
| FD_CONNECT | La connexion lancée sur le de socket |
| FD_CLOSE | La connexion identifiée par le de socket |
| FD_QOS | La qualité du service associé au de socket |
| FD_GROUP_QOS | Réservé pour une utilisation ultérieure avec les groupes de sockets : la qualité du service associé au groupe de sockets auquel le socket s appartient a changé |
| FD_ROUTING_INTERFACE_CHANGE | L’interface locale à utiliser 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 une erreur telle que 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 |
|---|---|
| Les adresses de la famille spécifiée ne peuvent pas être utilisées avec ce socket. | |
| La tentative de connexion a été rejetée. | |
| Le réseau ne peut pas être atteint à partir de cet hôte pour l’instant. | |
| Le paramètre namelen n’est pas valide. | |
| Le socket est déjà lié à une adresse. | |
| Le socket est déjà connecté. | |
| Aucun descripteur de fichier supplémentaire n’est disponible. | |
| Aucun espace tampon n’est disponible. Le socket ne peut pas être connecté. | |
| Le socket n’est pas connecté. | |
| Essayez de vous connecter 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. |
Event... : 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 pour 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. Après avoir publié avec succès la notification d’un événement particulier dans une fenêtre cliente SPI Windows Sockets, aucun autre message pour cet événement réseau ne sera publié sur la fenêtre du client 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éactiver 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 de condition retournée CF_DEFER |
| FD_CONNECT | AUCUN |
| FD_CLOSE | AUCUN |
| FD_QOS | LPWSPIoctl avec SIO_GET_QOS |
| FD_GROUP_QOS | Réservé à une utilisation ultérieure avec des 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 une 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 commedéclenchés par la périphérie
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
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é selon les besoins. 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 des messages FD_ACCEPT 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 d’abord connecté à LPWSPConnect (après FD_CONNECT, s’il est également inscrit) ou accepté avec LPWSPAccept, puis après qu’un LPWSPSend ou LPWSPSendTo échoue avec WSAEWOULDBLOCK et l’espace tampon devient disponible. Par conséquent, un client SPI Windows Sockets peut supposer que les envois sont possibles à partir du premier message FD_WRITE et durable 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 pas les événements FD_OOB.
Le code d’erreur dans 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 de fermeture est reçue pour le circuit virtuel correspondant au socket. En termes TCP, cela signifie que le FD_CLOSE est publié lorsque la connexion passe aux états TIME WAIT ou CLOSE WAIT. Cela résulte de l’exécution à distance d’un LPWSPShutdown côté envoi ou d’un LPWSPCloseSocket. Il est correct que les FD_CLOSE soient publiées uniquement une fois que toutes les données sont 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 à n’importe quel champ dans la spécification de flux associée audu socket
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 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ès LPWSPIoctl avec SIO_ADDRESS_LIST_CHANGE a été émis.
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 pour la réception.
- Lorsque les données arrivent, si FD_READ pas déjà publié.
- Une fois LPWSPRecv ou LPWSPRecvFrom est appelée (avec ou sans MSG_PEEK), si les données sont toujours disponibles pour la réception.
Lorsque LPWSPSetSockOpt SO_OOBINLINE est activé, données inclut des données normales et des données hors bande (OOB) dans les instances indiquées ci-dessus.
FD_WRITE
- Lorsque LPWSPAsyncSelect est appelé, si un LPWSPSend ou LPWSPSendTo est possible.
- Une fois LPWSPConnect ou LPWSPAccept est appelée, lorsque la connexion est établie.
- Une fois LPWSPSend ou LPWSPSendTo échouer avec WSAEWOULDBLOCK, lorsque LPWSPSend ou LPWSPSendTo sont susceptibles 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 LPWSPSetSockOpt SO_OOBINLINE est désactivé (par défaut))
- Lorsque LPWSPAsyncSelect est appelé, s’il existe actuellement des données OOB disponibles pour recevoir avec l’indicateur de MSG_OOB.
- Lorsque les données OOB arrivent, si FD_OOB pas encore publiées.
- Après LPWSPRecv ou LPWSPRecvFrom est appelé avec ou sans indicateur de MSG_OOB, si les données OOB sont toujours disponibles pour recevoir.
FD_ACCEPT
- Quand LPWSPAsyncSelect est appelé, s’il existe actuellement une demande de connexion disponible pour accepter.
- Lorsqu’une demande de connexion arrive, si FD_ACCEPT pas déjà publié.
- Une fois LPWSPAccept est appelée, s’il existe une autre demande de connexion disponible pour accepter.
FD_CONNECT
- Quand LPWSPAsyncSelect est appelé, s’il existe actuellement une connexion établie.
- Après LPWSPConnect est appelée, lorsque la connexion est établie (même quand LPWSPConnect réussit immédiatement, comme c’est le cas avec un socket de datagramme), et même lorsqu’elle échoue immédiatement).
- Une fois WSPJoinLeaf est appelée, une fois l’opération de jointure terminée.
- Après se connecter, WSAConnect ou WSPJoinLeaf a été appelé avec un socket non bloquant et orienté connexion. L’opération initiale retournée avec une erreur spécifique de WSAEWOULDBLOCK, mais l’opération réseau a été effectuée. Si l’opération réussit ou non, lorsque le résultat a été déterminé, FD_CONNECT se produit. Le client doit vérifier 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))
- Quand 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 les données ont été reçues et attend 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), lorsqu’aucune donnée n’est actuellement disponible pour recevoir.
- Lorsque le système distant abandonne la connexion (par exemple, le protocole TCP RST envoyé) et lParam contiendra la valeur d’erreur WSAECONNRESET.
FD_CLOSE n’est pas publié après LPWSPCloseSocket est appelé.
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.
- Une fois LPWSPIoctl avec SIO_GET_GROUP_QOS est appelée, lorsque la qoS du groupe est modifiée.
FD_ROUTING_INTERFACE_CHANGE
- après LPWSPIoctl avec SIO_ROUTING_INTERFACE_CHANGE est appelée, lorsque l’interface locale qui doit être utilisée pour atteindre la destination spécifiée dans les modifications IOCTL.
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.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows 10 Build 20348 |
| serveur minimum pris en charge | Windows 10 Build 20348 |
| d’en-tête | ws2spi.h |