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.

[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.

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ée par s.

Cette fonction définit automatiquement les de socket en mode non bloquant, quelle que soit la valeur de lEvent. Consultez LPWSPIoctl sur la façon de définir le socket en mode bloquant.

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é , le fournisseur de services utilise WPUPostMessage pour envoyer des messages wMsg à la fenêtre du client SPI Windows Sockets hWnd. Dans le message publié, l’argument wParam identifie le socket sur lequel un événement réseau s’est produit. Le mot faible 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.

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

événement : FD_CLOSE

Event... : FD_ACCEPT, FD_ADDRESS_LIST_CHANGE, FD_GROUP_QOS, FD_OOB, FD_QOS, FD_READ, FD_WRITE

événement : FD_ROUTING_INTERFACE_CHANGE

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.

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 . Un message est publié exactement une fois lorsqu’une modification qoS se produit. D’autres messages ne seront pas à venir tant que le fournisseur ne détecte pas une modification supplémentaire 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 une fois 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’a pas réédité la IOCTL et une autre modification est détectée depuis l’émission du IOCTL.

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.

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 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 , ou au groupe de sockets auquel appartient respectivement s. 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 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

1. Lorsque LPWSPAsyncSelect est appelé, s’il existe des données actuellement disponibles pour la réception.
2. Lorsque les données arrivent, si FD_READ pas déjà publié.
3. 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

1. Lorsque LPWSPAsyncSelect est appelé, si un LPWSPSend ou LPWSPSendTo est possible.
2. Une fois LPWSPConnect ou LPWSPAccept est appelée, lorsque la connexion est établie.
3. Une fois LPWSPSend ou LPWSPSendTo échouer avec WSAEWOULDBLOCK, lorsque LPWSPSend ou LPWSPSendTo sont susceptibles de réussir.
4. 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))

1. Lorsque LPWSPAsyncSelect est appelé, s’il existe actuellement des données OOB disponibles pour recevoir avec l’indicateur de MSG_OOB.
2. Lorsque les données OOB arrivent, si FD_OOB pas encore publiées.
3. 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

1. Quand LPWSPAsyncSelect est appelé, s’il existe actuellement une demande de connexion disponible pour accepter.
2. Lorsqu’une demande de connexion arrive, si FD_ACCEPT pas déjà publié.
3. Une fois LPWSPAccept est appelée, s’il existe une autre demande de connexion disponible pour accepter.

FD_CONNECT

1. Quand LPWSPAsyncSelect est appelé, s’il existe actuellement une connexion établie.
2. 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).
3. Une fois WSPJoinLeaf est appelée, une fois l’opération de jointure terminée.
4. 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))

1. Quand LPWSPAsyncSelect est appelé, si la connexion de socket a été fermée.
2. 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).
3. 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.
4. 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

1. Lorsque LPWSPAsyncSelect est appelé, si la qoS associée au socket a été modifiée.
2. 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 :

1. Lorsque LPWSPAsyncSelect est appelé, si la qoS de groupe associée au socket a été modifiée.
2. Une fois LPWSPIoctl avec SIO_GET_GROUP_QOS est appelée, lorsque la qoS du groupe est modifiée.

FD_ROUTING_INTERFACE_CHANGE

1. 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

1. 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

Voir aussi

fonction de rappel LPWSPAsyncSelect