Fonction de rappel LPWSPEVENTSELECT (ws2spi.h)
La fonction LPWSPEventSelect spécifie un objet d’événement à associer au jeu d’événements réseau fourni.
Syntaxe
LPWSPEVENTSELECT Lpwspeventselect;
int Lpwspeventselect(
[in] SOCKET s,
[in] WSAEVENT hEventObject,
[in] long lNetworkEvents,
[out] LPINT lpErrno
)
{...}
Paramètres
[in] s
Descripteur identifiant le socket.
[in] hEventObject
Handle identifiant l’objet d’événement à associer à l’ensemble d’événements réseau fourni.
[in] lNetworkEvents
Masque de bits qui spécifie la combinaison d’événements réseau dans lesquels le client SPI Windows Sockets a de l’intérêt. 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 à la rédaction. |
|
Émet une notification de l’arrivée des données OOB. |
|
Émet la notification des connexions entrantes. |
|
Émet une notification de connexion terminée. |
|
Émet une notification de fermeture du socket. |
|
Émet la notification des modifications de socket (QoS). |
|
Réservé. |
|
Émet une notification des modifications de l’interface de routage pour la ou les destinations spécifiées. |
|
Problèmes de notification des modifications de la liste d’adresses locale pour la famille d’adresses 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 spécification des événements réseau et de l’objet d’événement associé par le client SPI windows Sockets a réussi. Sinon, la valeur SOCKET_ERROR est retournée et un numéro 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 ou que le socket spécifié est dans un état non valide. | |
| Le blocage de l’appel de sockets Windows est en cours ou le fournisseur de services traite toujours une fonction de rappel. | |
| Le descripteur n’est pas un socket. |
Remarques
Cette fonction est utilisée pour spécifier un objet d’événement, hEventObject, à associer aux événements réseau sélectionnés, lNetworkEvents. Le socket pour lequel un objet d’événement est spécifié est identifié par s. L’objet événement est défini lorsque l’un des événements réseau nommés se produit.
LPWSPEventSelect fonctionne de la même manière que LPWSPAsyncSelect, la différence étant dans les actions effectuées lorsqu’un événement réseau nommé se produit. Alors que WSPAsyncSelect entraîne la publication d’un message Windows spi spécifié par le client, LPWSPEventSelect définit l’objet d’événement associé et enregistre l’occurrence de cet événement dans un enregistrement d’événement réseau interne. Un client SPI Windows Sockets peut utiliser LPWSPEnumNetworkEvents pour récupérer le contenu de l’enregistrement d’événements réseau interne et ainsi déterminer lequel des événements réseau nommés s’est produit.
LPWSPEventSelect est la seule fonction qui permet d’enregistrer et de récupérer l’activité et les erreurs réseau via LPWSPEnumNetworkEvents. Consultez les descriptions de LPWSPSelect et LPWSPAsyncSelect pour découvrir comment ces fonctions signalent l’activité et les erreurs du réseau.
Cette fonction définit automatiquement les sockets en mode non bloquant, quelle que soit la valeur de lNetworkEvents.
L’émission d’un LPWSPEventSelect pour un socket annule tout LPWSPAsyncSelect ou LPWSPEventSelect précédent pour le même socket et efface l’enregistrement d’événement réseau interne. Par exemple, pour associer un objet événement à la fois à la lecture et à l’écriture d’événements réseau, le client SPI Windows Sockets doit appeler LPWSPEventSelect avec FD_READ et FD_WRITE, comme ceci.
rc = WSPEventSelect(s, hEventObject, FD_READ | FD_WRITE);
Il n’est pas possible de spécifier différents objets d’événement pour différents événements réseau. Le code suivant ne fonctionnera pas ; le deuxième appel annule les effets du premier, et la seule association sera l’événement réseau FD_WRITE associé à hEventObject2.
// Incorrect example.
rc = WSPEventSelect(s, hEventObject1, FD_READ);
rc = WSPEventSelect(s, hEventObject2, FD_WRITE);
Pour annuler l’association et la sélection d’événements réseau sur un socket, vous devez définir lNetworkEvents sur zéro, auquel cas le paramètre hEventObject est ignoré.
rc = WSPEventSelect(s, hEventObject, 0);
La fermeture d’un socket avec LPWSPCloseSocket annule également l’association et la sélection d’événements réseau spécifiés dans LPWSPEventSelect pour le socket. Toutefois, le client SPI Windows Sockets doit toujours appeler WSACloseEvent pour fermer explicitement l’objet d’événement et libérer toutes les ressources.
Étant donné qu’un socket LPWSPAccept’ed a les mêmes propriétés que le socket d’écoute utilisé pour l’accepter, toute association LPWSPEventSelect et l’ensemble de sélection d’événements réseau pour le socket d’écoute s’appliquent au socket accepté. Par exemple, si un socket d’écoute a LPWSPEventSelect association de hEventObject avec FD_ACCEPT, FD_READ et FD_WRITE, tout socket accepté sur ce socket d’écoute aura également FD_ACCEPT, FD_READ et FD_WRITE événements réseau associés au même hEventObject. Si un autre hEventObject ou des événements réseau sont souhaités, le client SPI Windows Sockets doit appeler LPWSPEventSelect, en transmettant le socket accepté et les nouvelles informations souhaitées.
Après avoir enregistré avec succès l’occurrence de l’événement réseau et signalé l’objet d’événement associé, aucune autre action n’est effectuée pour cet événement réseau jusqu’à ce que le client SPI Windows Sockets effectue l’appel de fonction qui réactive implicitement le paramètre de cet événement réseau et la signalisation de l’objet d’événement associé.
| É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 l’enregistrement et de la signalisation pour l’événement réseau et l’objet d’événement appropriés, respectivement.
Pour les événements réseau FD_READ, FD_OOB et FD_ACCEPT, l’enregistrement des événements réseau et la signalisation des objets d’événement sont déclenchés au niveau. Cela signifie que si la routine de réactivation est appelée et que la condition réseau appropriée est toujours valide après l’appel, l’événement réseau est enregistré et l’objet d’événement associé est signalé. Cela permet à un client SPI Windows Sockets d’être piloté par les événements tout en n’étant pas concerné par la quantité de données qui arrive à un moment donné. Examinez la séquence suivante.
- Le fournisseur de services reçoit 100 octets de données sur les sockets, enregistre l’événement réseau FD_READ et signale l’objet d’événement associé.
- Les problèmes
WSPRecv(s, buffptr, 50, 0)du client SPI des sockets Windows pour lire 50 octets. - Le fournisseur de services enregistre l’événement réseau FD_READ et signale à nouveau l’objet d’événement associé, car il reste des données à lire.
Avec cette sémantique, un client SPI Windows Sockets n’a pas besoin de lire toutes les données disponibles en réponse à un événement réseau FD_READ. Au lieu de cela, un seul LPWSPRecv en réponse à chaque événement réseau FD_READ est approprié.
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 de qualité de service (QOS) se produit. D’autres indications ne seront pas émises tant que le fournisseur de services 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 l’émission du IOCTL.
Si un événement réseau s’est déjà produit lorsque le client SPI Windows Sockets appelle LPWSPEventSelect, ou lorsque la fonction de réactivation est appelée, un événement réseau est enregistré et l’objet d’événement associé est signalé, le cas échéant. 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 LPWSPEventSelect en spécifiant qu’il est intéressé par l’événement réseau FD_ACCEPT pour le socket. Le fournisseur de services enregistre l’événement réseau FD_ACCEPT et signale immédiatement l’objet d’événement associé.
L’événement réseau FD_WRITE est géré légèrement différemment. Un événement réseau FD_WRITE est enregistré lorsqu’un socket est d’abord connecté à LPWSPConnect ou accepté avec LPWSPAccept, puis après qu’un LPWSPSend ou LPWSPSendTo é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 paramètre d’événement réseau FD_WRITE et durent jusqu’à ce qu’un envoi retourne WSAEWOULDBLOCK. Après un tel échec, le client SPI Windows Sockets constate que les envois sont à nouveau possibles lorsqu’un événement réseau FD_WRITE est enregistré et que l’objet d’événement associé est signalé.
L’événement réseau 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 s’inscrire à l’FD_READ’événement réseau et non FD_OOB événement réseau. Un client SPI Windows Sockets peut définir ou inspecter la façon dont les données hors bande doivent être gérées à l’aide de LPWSPSetSockOpt ou LPWSPGetSockOpt pour l’option SO_OOBINLINE.
Le code d’erreur d’un événement réseau 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.
L’événement réseau FD_CLOSE est enregistré lorsqu’une indication proche est reçue pour le circuit virtuel correspondant au socket. En termes TCP, cela signifie que le FD_CLOSE est enregistré lorsque la connexion passe aux états FIN WAIT ou CLOSE WAIT. Cela résulte de l’exécution d’un LPWSPShutdown côté envoi ou d’un LPWSPCloseSocket.
Un fournisseur de services doit enregistrer uniquement un événement réseau FD_CLOSE pour indiquer la fermeture d’un circuit virtuel ; il ne doit pas enregistrer un événement réseau FD_READ pour indiquer cette condition.
L’événement réseau FD_QOS ou FD_GROUP_QOS est enregistré 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. Cette modification doit être mise à la disposition des clients SPI windows Sockets via la fonction LPWSPIoctl avec SIO_GET_QOS et/ou SIO_GET_GROUP_QOS pour récupérer la QOS actuelle pour les sockets, ou pour le groupe de sockets auquel appartient , respectivement.
L’événement réseau FD_ROUTING_INTERFACE_CHANGE est enregistré lorsque l’interface locale qui doit être utilisée pour atteindre la destination spécifiée dans WSAIoctl avec SIO_ROUTING_INTERFACE_CHANGE modifications après l’émission d’un tel IOCTL.
L’événement réseau FD_ADDRESS_LIST_CHANGE est enregistré lorsque la liste des adresses de la famille de protocoles des sockets à laquelle le client SPI Windows Sockets peut lier des modifications aprèsl’émission de WSAIoctl avec SIO_ADDRESS_LIST_CHANGE.
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