Fonction de rappel LPWSPSELECT (ws2spi.h)

Article
07/16/2024

La fonction LPWSPSelect détermine l’état d’un ou plusieurs sockets.

Syntaxe

LPWSPSELECT Lpwspselect;

int Lpwspselect(
  [in]      int nfds,
  [in, out] fd_set *readfds,
  [in, out] fd_set *writefds,
  [in, out] fd_set *exceptfds,
  [in]      const timeval *timeout,
  [out]     LPINT lpErrno
)
{...}

Paramètres

[in] nfds

Ignoré et inclus uniquement pour la compatibilité.

[in, out] readfds

Pointeur facultatif vers un ensemble de sockets à vérifier pour la lisibilité.

[in, out] writefds

Pointeur facultatif vers un ensemble de sockets à vérifier pour la facilité d’écriture.

[in, out] exceptfds

Pointeur facultatif vers un ensemble de sockets à vérifier pour les erreurs.

[in] timeout

Durée maximale pour LPWSPSelect attendre, ou null pour une opération bloquante, sous la forme d’une structure de timeval.

[out] lpErrno

Pointeur vers le code d’erreur.

Valeur de retour

La fonction LPWSPSelect retourne le nombre total de descripteurs prêts et contenus dans les structures fd_set, ou SOCKET_ERROR si une erreur s’est produite. Si la valeur de retour est SOCKET_ERROR, un code d’erreur spécifique est disponible dans lpErrno.

Code d’erreur	Signification
WSAEFAULT	Le fournisseur de services Windows Sockets n’a pas pu allouer les ressources nécessaires pour ses opérations internes, ou les readfds, writefds, à l’exception des ou paramètres timeval ne font pas partie de l’espace d’adressage utilisateur.
WSAENETDOWN	Le sous-système réseau a échoué.
WSAEINVAL	La valeur du délai d’expiration n’est pas valide, ou les trois paramètres de descripteur ont été NULL .
WSAEINTR	(Blocage) l’appel a été annulé via LPWSPCancelBlockingCall.
WSAEINPROGRESS	Le blocage de l’appel Windows Sockets est en cours ou le fournisseur de services traite toujours une fonction de rappel.
WSAENOTSOCK	L’un des jeux de descripteurs contient une entrée qui n’est pas un socket.

Remarques

Cette fonction est utilisée pour déterminer l’état d’un ou plusieurs sockets. Pour chaque socket, l’appelant peut demander des informations sur l’état de lecture, d’écriture ou d’erreur. L’ensemble de sockets pour lesquels un état donné est demandé est indiqué par une structure fd_set. Toutes les entrées d’un fd_set correspondent aux sockets créés par le fournisseur de services (autrement dit, les structures WSAPROTOCOL_INFO décrivant leurs protocoles ont la même valeur providerId). Lors du retour, les structures sont mises à jour pour refléter le sous-ensemble de ces sockets qui répondent à la condition spécifiée, et LPWSPSelect retourne le nombre total de sockets répondant aux conditions. Un ensemble de macros est fourni pour manipuler un fd_set. Ces macros sont compatibles avec celles utilisées dans le logiciel Berkeley, mais la représentation sous-jacente est complètement différente.

Le paramètre readfds identifie ces sockets à vérifier pour la lisibilité. Si le socket écoute actuellement via LPWSPListen, il est marqué comme lisible si une demande de connexion entrante a été reçue, afin qu’un LPWSPAccept soit garanti sans blocage. Pour les autres sockets, la lisibilité signifie que les données mises en file d’attente sont disponibles pour la lecture afin qu’une LPWSPRecv ou LPWSPRecvFrom ne soit pas bloquée.

Pour les sockets orientés connexion, la lisibilité peut également indiquer qu’une demande de fermeture a été reçue de l’homologue. Si le circuit virtuel a été fermé correctement, un LPWSPRecv retourne immédiatement avec zéro octets lus. Si le circuit virtuel a été réinitialisé, une LPWSPRecv se termine immédiatement avec un code d’erreur, tel que WSAECONNRESET. La présence de données OOB est vérifiée si l’option de socket SO_OOBINLINE a été activée (voir LPWSPSetSockOpt).

Le paramètre writefds identifie ces sockets à vérifier pour la facilité d’écriture :

Si un socket se connecte via LPWSPConnect, l’écriture signifie que l’établissement de la connexion s’est correctement terminé.
Si le socket n’est pas en cours d’écoute via LPWSPConnect, l’écriture signifie qu’un LPWSPSend ou LPWSPSendTo sont garantis pour réussir.

Toutefois, ils peuvent bloquer sur un socket bloquant si le len dépasse la quantité d’espace tampon système sortant disponible. Il n’est pas spécifié combien de temps ces garanties peuvent être considérées comme valides, en particulier dans un environnement multithread.

Le paramètre exceptfds identifie les sockets à vérifier pour la présence de données OOB ou toute condition d’erreur exceptionnelle. Notez que les données OOB ne sont signalées de cette façon que si l’option SO_OOBINLINE est FALSE. Si un socket effectue une connexion LPWSPConnect (sans blocage), l’échec de la tentative de connexion est indiqué dans sauf les. Cette spécification ne définit pas les autres erreurs qui seront incluses.

Deux readfds , writefdsou à l’exception des peuvent être donnés en tant que null si aucun descripteur ne doit être vérifié pour la condition d’intérêt. Au moins une doit êtrenull, et tout jeu de descripteur null nonnull doit contenir au moins un descripteur de socket.

Résumé : un socket est identifié dans un ensemble particulier lorsque LPWSPSelect retourne en fonction des éléments suivants.

Paramètre	Description
readfds:	Si LPWSPListen est appelé, une connexion est en attente, LPWSPAccept réussit. Les données sont disponibles pour la lecture (inclut les données OOB si SO_OOBINLINE est activée). La connexion a été fermée/réinitialisée/terminée.
writefds :	Si LPWSPConnect (non bloquant), la connexion a réussi. Les données peuvent être envoyées.
sauf les:	Si LPWSPConnect (non bloquant), la tentative de connexion a échoué. Les données OOB sont disponibles pour la lecture (uniquement si SO_OOBINLINE est désactivée).

Trois macros et une fonction upcall sont définies dans le fichier d’en-tête Ws2spi.h pour manipuler et vérifier les jeux de descripteurs. La variable FD_SETSIZE détermine le nombre maximal de descripteurs dans un jeu. (La valeur par défaut de FD_SETSIZE est 64, qui peut être modifiée par #defining FD_SETSIZE vers une autre valeur avant #including Ws2spi.h.) En interne, les handles de socket dans un fd_set ne sont pas représentés comme indicateurs de bits comme dans Berkeley UNIX. Leur représentation des données est opaque. L’utilisation de ces macros maintient la portabilité logicielle entre différents environnements de socket.

Les macros à manipuler et à vérifier fd_set contenu sont les suivantes :

FD_CLR(s, *): Supprime le descripteur s de set.
FD_SET(s, *): Ajoute le descripteur s à définir.
FD_ZERO(*): Initialise le jeu de au jeu de null.

La fonction upcall utilisée pour vérifier l’appartenance est la suivante :

intWPUFDIsSet (de socket, FD_SETfardéfini) ;: qui retourne non zéro si s est membre du défini ou zéro.

Le paramètre délai d’expiration contrôle la durée de LPWSPSelect peut prendre. Si délai d’expiration est un pointeur de null , LPWSPSelect se bloque indéfiniment jusqu’à ce qu’au moins un descripteur réponde aux critères spécifiés. Sinon, délai d’expiration pointe vers une structure timeval qui spécifie la durée maximale pendant laquelle LPWSPSelect doit attendre avant de retourner. Lorsque LPWSPSelect retourne, le contenu de la structure timeval n’est pas modifié. Si timeval est initialisé sur {0, 0}, LPWSPSelect retourne immédiatement ; permet d’interroger l’état des sockets sélectionnés. Si c’est le cas, l’appel LPWSPSelect est considéré comme non bloquant et les hypothèses standard pour les appels non bloquants s’appliquent. Par exemple, le hook bloquant ne sera pas appelé et le fournisseur Windows Sockets ne génère pas.

Note

La fonction LPWSPSelect n’a aucun effet sur la persistance des événements de socket enregistrés avec LPWSPAsyncSelect ou LPWSPEventSelect.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau uniquement]
d’en-tête	ws2spi.h