WSAPoll, fonction (winsock2.h)

Article
08/27/2023

La fonction WSAPoll détermine status d’un ou plusieurs sockets.

Syntaxe

int WSAAPI WSAPoll(
  [in, out] LPWSAPOLLFD fdArray,
  [in]      ULONG       fds,
  [in]      INT         timeout
);

Paramètres

[in, out] fdArray

Tableau d’une ou plusieurs structures POLLFD spécifiant l’ensemble de sockets pour lequel status est demandé. Le tableau doit contenir au moins une structure avec un socket valide. Lors du retour, ce paramètre reçoit les sockets mis à jour avec le membre revents status indicateurs défini sur chacun d’eux qui correspond aux critères de requête status.

[in] fds

Nombre de structures WSAPOLLFD dans fdarray. Il ne s’agit pas nécessairement du nombre de sockets pour lesquels status est demandé.

[in] timeout

Valeur qui spécifie le comportement d’attente, en fonction des valeurs suivantes.

Valeur	Signification
Supérieure à zéro	Temps, en millisecondes, d’attente.
Zéro	Retournez immédiatement.
Inférieure à zéro	Attendez indéfiniment.

Valeur retournée

Retourne l’une des valeurs suivantes.

Valeur retournée	Description
Zéro	Aucun socket n’était dans l’état interrogé avant l’expiration du minuteur.
Supérieure à zéro	Nombre d’éléments dans fdarray pour lesquels un membre revents de la structure POLLFD est différent de zéro.
SOCKET_ERROR	Une erreur est survenue. Appelez la fonction WSAGetLastError pour récupérer le code d’erreur étendu.

Code d’erreur étendu	Signification
WSAENETDOWN	Le sous-système réseau a échoué.
WSAEFAULT	Une exception s’est produite lors de la lecture des paramètres d’entrée utilisateur.
WSAEINVAL	Un paramètre non valide a été passé. Cette erreur est retournée si les structures WSAPOLLFD pointent vers par le paramètre fdarray lors de la demande de socket status. Cette erreur est également retournée si aucun des sockets spécifiés dans le membre fd d’une des structures WSAPOLLFD pointées par le paramètre fdarray n’était valide.
WSAENOBUFS	La fonction n’a pas pu allouer suffisamment de mémoire.

Remarques

La fonction WSAPoll est définie sur Windows Vista et versions ultérieures.

Structures WSAPOLLFD . Une application définit les indicateurs appropriés dans le membre d’événements de la structure WSAPOLLFD pour spécifier le type de status demandé pour chaque socket correspondant. La fonction WSAPoll retourne la status d’un socket dans le membre revents de la structure WSAPOLLFD.

Pour chaque socket, un appelant peut demander des informations sur les status de lecture ou d’écriture. Les conditions d’erreur sont toujours retournées. Il n’est donc pas nécessaire de demander des informations sur celles-ci.

Structure WSAPOLLFD pointée vers le paramètre fdarray . Tous les sockets qui ne répondent pas à ces critères et qui n’ont aucune condition d’erreur auront le membre revents correspondant défini sur 0.

Une combinaison des indicateurs suivants peut être définie dans la structure WSAPOLLFD pour un socket donné lors de la demande d’status pour ce socket :

Indicateur	Description
POLLPRI	Les données de priorité peuvent être lues sans blocage. Cet indicateur n’est pas pris en charge par le fournisseur Microsoft Winsock.
POLLRDBAND	Les données de la bande de priorité (hors bande) peuvent être lues sans blocage.
POLLRDNORM	Les données normales peuvent être lues sans blocage.
POLLWRNORM	Les données normales peuvent être écrites sans blocage.

L’indicateur POLLIN est défini comme la combinaison des valeurs des indicateurs POLLRDNORM et POLLRDBAND. L’indicateur POLLOUT est défini comme étant identique à la valeur de l’indicateur POLLWRNORM.

La structure WSAPOLLFD doit uniquement contenir une combinaison des indicateurs ci-dessus pris en charge par le fournisseur Winsock. Toutes les autres valeurs sont considérées comme des erreurs et WSAPoll retourne SOCKET_ERROR. Un appel ultérieur à la fonction WSAGetLastError récupère le code d’erreur étendu de WSAEINVAL. Si l’indicateur POLLPRI est défini sur un socket pour le fournisseur Microsoft Winsock, la fonction WSAPoll échoue.

Lorsque les structures WSAPOLLFD pointées vers par le paramètre fdarray pour indiquer le socket status :

Indicateur	Description
POLLERR	Une erreur s’est produite.
POLLHUP	Une connexion orientée flux a été déconnectée ou abandonnée.
POLLNVAL	Un socket non valide a été utilisé.
POLLPRI	Les données de priorité peuvent être lues sans blocage. Cet indicateur n’est pas retourné par le fournisseur Microsoft Winsock.
POLLRDBAND	Les données de la bande de priorité (hors bande) peuvent être lues sans blocage.
POLLRDNORM	Les données normales peuvent être lues sans blocage.
POLLWRNORM	Les données normales peuvent être écrites sans blocage.

En ce qui concerne les sockets TCP et UDP :

Structure WSAPOLLFD en tant que données normales comme POLLRDNORM.
Structure WSAPOLLFD , une opération recv ultérieure est garantie pour se terminer sans blocage.
Structure WSAPOLLFD par POLLWRNORM.
Structure WSAPOLLFD par POLLRDNORM. Un appel suivant à accepter est garanti pour se terminer sans blocage.
Structure WSAPOLLFD par POLLRDBAND.
Structure WSAPOLLFD lorsqu’un homologue distant arrête une opération d’envoi (une fin TCP a été reçue). Une requête de fonction recv suivante retourne zéro octet.
Structure WSAPOLLFD lorsque l’homologue distant lance une déconnexion normale.
Structure WSAPOLLFD retournée lorsqu’un homologue distant se déconnecte soudainement.
Structure WSAPOLLFD lorsque le socket local est fermé.

Le nombre d’éléments (et non de sockets) dans fdarray est indiqué par nfds. Les membres de fdarray dont le membre fd est défini sur une valeur négative sont ignorés et leurs revents seront définis sur POLLNVAL au retour. Ce comportement est utile pour une application qui maintient une allocation fdarray fixe et ne compacte pas le tableau pour supprimer les entrées inutilisées ou pour réallouer la mémoire. Il n’est pas nécessaire d’effacer les revents pour un élément avant d’appeler WSAPoll.

L’argument de délai d’expiration spécifie la durée d’attente de la fonction avant de retourner. Une valeur positive contient le nombre de millisecondes à attendre avant de retourner. Une valeur zéro force WSAPoll à retourner immédiatement, et une valeur négative indique que WSAPoll doit attendre indéfiniment.

Note Lors de l’émission d’un appel Winsock bloquant tel que WSAPoll avec le paramètre de délai d’attente défini sur un nombre négatif, Winsock peut avoir besoin d’attendre qu’un événement réseau puisse se terminer. Winsock effectue une attente alertable dans cette situation, qui peut être interrompue par un appel de procédure asynchrone (APC) planifié sur le même thread. L’émission d’un autre appel Winsock bloquant à l’intérieur d’un APC qui a interrompu un appel Winsock bloquant en cours sur le même thread entraîne un comportement non défini et ne doit jamais être tenté par les clients Winsock.

Note À partir de Windows 10 version 2004, lorsqu’un socket TCP ne parvient pas à se connecter, (POLLHUP \| POLLERR \| POLLWRNORM) est indiqué.

Windows 8.1 et Windows Server 2012 R2 : cette fonction est prise en charge pour les applications du Windows Store sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8.1, Windows Vista [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	winsock2.h (inclure Winsock2.h)
Bibliothèque	Ws2_32.lib
DLL	Ws2_32.dll

Voir aussi

WSAGetLastError

WSAPOLLFD