Fonction de rappel LPWSPSELECT (ws2spi.h)

Article
08/28/2023

La fonction LPWSPSelect détermine la status 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 des raisons de 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 rechercher des erreurs.

[in] timeout

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

[out] lpErrno

Pointeur vers le code d’erreur.

Valeur retournée

La fonction LPWSPSelect retourne le nombre total de descripteurs prêts et contenus dans les structures de 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, exceptfds ou timeval paramètres ne font pas partie de l’espace d’adressage utilisateur.
WSAENETDOWN	Le sous-système réseau a échoué.
WSAEINVAL	La valeur de délai d’expiration n’est pas valide ou les trois paramètres de descripteur étaient NULL.
WSAEINTR	L’appel (bloquant) a été annulé via LPWSPCancelBlockingCall.
WSAEINPROGRESS	L’appel de sockets Windows 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 la status d’un ou plusieurs sockets. Pour chaque socket, l’appelant peut demander des informations sur la lecture, l’écriture ou les status d’erreur. L’ensemble de sockets pour lesquels un status donné est demandé est indiqué par une structure fd_set. Toutes les entrées d’un fd_set correspondent à des sockets créés par le fournisseur de services (autrement dit, les structures WSAPROTOCOL_INFO décrivant leurs protocoles ont la même valeur providerId ). Au 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 les sockets qui doivent être vérifiés 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, de sorte qu’un LPWSPAccept est garanti pour se terminer sans blocage. Pour les autres sockets, la lisibilité signifie que les données en file d’attente sont disponibles pour la lecture, de sorte qu’un LPWSPRecv ou LPWSPRecvFrom ne se bloque pas.

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 est immédiatement retourné avec zéro octet lus. Si le circuit virtuel a été réinitialisé, un 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 les sockets qui doivent être vérifiés pour l’écriture :

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

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

Le paramètre exceptfds identifie les sockets qui doivent être vérifiés pour la présence de données OOB ou de conditions d’erreur exceptionnelles. Notez que les données OOB ne seront signalées de cette manière que si l’option SO_OOBINLINE est FALSE. Si un socket établit une connexion LPWSPConnect (non bloquante), l’échec de la tentative de connexion est indiqué dans exceptfds. Cette spécification ne définit pas les autres erreurs qui seront incluses.

Deux de readfds, writefds ou exceptfds peuvent être donnés comme null si aucun descripteur ne doit être vérifié pour la condition d’intérêt. Au moins un doit être non null, et tout jeu de descripteur non null doit contenir au moins un descripteur de socket.

Résumé : Un socket est identifié dans un ensemble particulier lorsque LPWSPSelect retourne les valeurs suivantes.

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é). 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.
exceptfds :	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é).

Trois macros et une fonction upcall sont définies dans le fichier d’en-tête Ws2spi.h pour la manipulation et la vérification des jeux de descripteurs. La variable FD_SETSIZE détermine le nombre maximal de descripteurs dans un ensemble. (La valeur par défaut de FD_SETSIZE est 64, qui peut être modifiée par #defining FD_SETSIZE en une autre valeur avant #including Ws2spi.h.) En interne, les handles de socket d’un fd_set ne sont pas représentés en tant qu’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 à case activée contenu fd_set sont les suivantes :

FD_CLR(s, *set): Supprime le descripteur s de l’ensemble.
FD_SET(s, *set): Ajoute le descripteur s à définir.
FD_ZERO(*set): Initialise le jeu défini sur le jeu null .

La fonction upcall utilisée pour case activée l’appartenance est :

intWPUFDIsSet (SOCKETs, FD_SET FAR *set) ;: qui retourne une valeur différente de zéro si s est un membre de l’ensemble ou de zéro.

Le délai d’expiration du paramètre contrôle la durée d’exécution du LPWSPSelect . Si le délai d’expiration est un pointeur null , LPWSPSelect est bloqué indéfiniment jusqu’à ce qu’au moins un descripteur réponde aux critères spécifiés. Sinon, le 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 ; il est utilisé pour interroger l’état des sockets sélectionnés. Si tel 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 crochet de blocage n’est pas appelé et le fournisseur de sockets Windows ne produit pas.

Notes

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

Configuration requise


Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
En-tête	ws2spi.h