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 intérêt. Construit à l’aide de l’opérateur OR au niveau du bit avec l’une de ces valeurs.

[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 spécification du client SPI Windows Sockets des événements réseau et l’objet d’événement associé a réussi. Sinon, la valeur SOCKET_ERROR est retournée et un numéro d’erreur spécifique est disponible dans lpErrno.

Remarques

Cette fonction permet de 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 d’événement est défini lorsque l’un des événements réseau nommés se produit.

LPWSPEventSelect fonctionne de la même façon que LPWSPAsyncSelect, la différence 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 spécifié par le client SPI Windows Sockets, 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 quels événements réseau nommés ont eu lieu.

LPWSPEventSelect est la seule fonction qui provoque l’enregistrement et la récupération de l’activité réseau et des erreurs via LPWSPEnumNetworkEvents. Consultez les descriptions de LPWSPSelect et LPWSPAsyncSelect pour savoir comment ces fonctions signalent l’activité et les erreurs réseau.

Cette fonction définit automatiquement les de socket en mode non bloquant, quelle que soit la valeur de lNetworkEvents.

L’émission d’un LPWSPEventSelect pour un socket annule tout LPWSPAsyncSelect ou LPWSPEventSelect pour le même socket et efface l’enregistrement d’événement réseau interne. Par exemple, pour associer un objet événement à 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 suit.

rc = WSPEventSelect(s, hEventObject, FD_READ | FD_WRITE);

Il n’est pas possible de spécifier différents objets d’événements 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 LPWSPAccept« ed socket a les mêmes propriétés que le socket d’écoute utilisé pour l’accepter, tout LPWSPEventSelect association et la sélection des événements réseau définis 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, tous les sockets acceptés sur ce socket d’écoute auront é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 passant 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 tant que le client SPI Windows Sockets n’a pas effectué l’appel de fonction qui réactive implicitement le paramètre de cet événement réseau et signale l’objet d’événement associé.

Tout appel à la routine de réactivation, même en cas d’échec, entraîne une 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 FD_READ, FD_OOB et FD_ACCEPT événements réseau, l’enregistrement d’événements réseau et les signalisations d’objets d’événement sont déclenchées 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 étant inconcédant avec la quantité de données qui arrivent à tout moment. Considérez la séquence suivante.

1. Le fournisseur de services reçoit 100 octets de données sur lede socket , enregistre l’événement réseau FD_READ et signale l’objet d’événement d’événement associé.
2. Le client SPI Windows Sockets émet WSPRecv(s, buffptr, 50, 0) lire 50 octets.
3. Le fournisseur de services enregistre l’événement réseau FD_READ et signale à nouveau l’objet d’événement associé, car il existe toujours 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, une seule LPWSPRecv en réponse à chaque événement réseau FD_READ convient.

Les événements FD_QOS et FD_GROUP_QOS sont considérés commedéclenchés par la 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 ne détecte pas une modification supplémentaire de la qualité de service, 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 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’a pas réédité la IOCTL et 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.

1. Un client SPI Windows Sockets appelle LPWSPListen.
2. Une demande de connexion est reçue, mais pas encore acceptée.
3. 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 l’espace tampon devient 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 durable jusqu’à ce qu’un envoi retourne WSAEWOULDBLOCK. Après un tel échec, le client SPI Windows Sockets détecte 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 et obtenir, FD_READ événement réseau, et non pas 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 de fermeture est reçue pour le circuit virtuel correspondant au socket. En termes TCP, cela signifie que la FD_CLOSE est enregistrée lorsque la connexion passe aux états FIN WAIT ou CLOSE WAIT. Cela résulte de l’exécution à distance d’un LPWSPShutdown côté envoi, ou d’un LPWSPCloseSocket.

Les fournisseurs de services doivent 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’il y a eu une modification apportée à n’importe quel champ dans la spécification de flux associée audu socket , ou au groupe de sockets auquel appartient 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 lesdu socket , ou pour le groupe de sockets s 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 de telles durées de vie IOCTL.

L’événement réseau FD_ADDRESS_LIST_CHANGE est enregistré lorsque la liste des adresses de la famille de protocoles des sockets auxquelles le client SPI Windows Sockets peut lier des modifications après WSAIoctl avec SIO_ADDRESS_LIST_CHANGE a été émis.

Exigences

Voir aussi

LPWSPEnumNetworkEvents