WSAPoll-Funktion (winsock2.h)

Artikel
08/27/2023

Die WSAPoll-Funktion bestimmt status eines oder mehrerer Sockets.

Syntax

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

Parameter

[in, out] fdArray

Ein Array von mindestens einer POLLFD-Struktur, die den Satz von Sockets angibt, für die status angefordert wird. Das Array muss mindestens eine Struktur mit einem gültigen Socket enthalten. Nach der Rückgabe empfängt dieser Parameter die aktualisierten Sockets mit dem Element revents status Flags, das für jedes Element festgelegt ist, das den status Abfragekriterien entspricht.

[in] fds

Die Anzahl der WSAPOLLFD-Strukturen in fdarray. Dies ist nicht unbedingt die Anzahl der Sockets, für die status angefordert wird.

[in] timeout

Ein Wert, der das Warteverhalten basierend auf den folgenden Werten angibt.

Wert	Bedeutung
Größer als 0 (null)	Die Wartezeit in Millisekunden.
Null	Sofortige Rückgabe.
Kleiner als 0 (null)	Warten Sie unbegrenzt.

Rückgabewert

Gibt einen der folgenden Werte zurück.

Rückgabewert	BESCHREIBUNG
Null	Keine Sockets befanden sich im abgefragten Zustand, bevor der Timer abgelaufen ist.
Größer als 0 (null)	Die Anzahl der Elemente in fdarray , für die ein revents-Element der POLLFD-Struktur nichtzero ist.
SOCKET_ERROR	Ein Fehler ist aufgetreten. Rufen Sie die WSAGetLastError-Funktion auf, um den erweiterten Fehlercode abzurufen.

Erweiterter Fehlercode	Bedeutung
WSAENETDOWN	Beim Netzwerksubsystem ist ein Fehler aufgetreten.
WSAEFAULT	Beim Lesen von Benutzereingabeparametern ist eine Ausnahme aufgetreten.
WSAEINVAL	Es wurde ein ungültiger Parameter übergeben. Dieser Fehler wird zurückgegeben, wenn die WSAPOLLFD-Strukturen, auf die der fdarray-Parameter beim Anfordern des Sockets status verweist. Dieser Fehler wird auch zurückgegeben, wenn keiner der Sockets, die im fd-Member einer der WSAPOLLFD-Strukturen angegeben sind, auf die vom fdarray-Parameter verwiesen wird, gültig war.
WSAENOBUFS	Die Funktion konnte nicht genügend Arbeitsspeicher zuweisen.

Hinweise

Die WSAPoll-Funktion ist unter Windows Vista und höher definiert.

Die WSAPOLLFD-Strukturen . Eine Anwendung legt die entsprechenden Flags im Ereignismember der WSAPOLLFD-Struktur fest, um den Typ der für jeden entsprechenden Socket angeforderten status anzugeben. Die WSAPoll-Funktion gibt die status eines Sockets im revents-Member der WSAPOLLFD-Struktur zurück.

Für jeden Socket kann ein Aufrufer Informationen zum Lesen oder Schreiben status anfordern. Fehlerbedingungen werden immer zurückgegeben, sodass keine Informationen dazu angefordert werden müssen.

Die WSAPOLLFD-Struktur , auf die der fdarray-Parameter verweist. Für alle Sockets, die diese Kriterien nicht erfüllen und keine Fehlerbedingung aufweisen, ist der entsprechende revents-Member auf 0 festgelegt.

Eine Kombination der folgenden Flags kann in der WSAPOLLFD-Struktur für einen bestimmten Socket festgelegt werden, wenn status für diesen Socket angefordert wird:

Flag	Beschreibung
POLLPRI	Prioritätsdaten können ohne Blockierung gelesen werden. Dieses Flag wird vom Microsoft Winsock-Anbieter nicht unterstützt.
POLLRDBAND	Daten im Prioritätsband (Out-of-Band) können ohne Blockierung gelesen werden.
POLLRDNORM	Normale Daten können ohne Blockierung gelesen werden.
POLLWRNORM	Normale Daten können ohne Blockierung geschrieben werden.

Das POLLIN-Flag wird als Kombination der Werte des POLLRDNORM - und POLLRDBAND-Flags definiert. Das POLLOUT-Flag ist mit dem Wert des POLLWRNORM-Flags identisch.

Die WSAPOLLFD-Struktur darf nur eine Kombination der oben genannten Flags enthalten, die vom Winsock-Anbieter unterstützt werden. Alle anderen Werte gelten als Fehler, und WSAPoll gibt SOCKET_ERROR zurück. Ein anschließender Aufruf der WSAGetLastError-Funktion ruft den erweiterten Fehlercode von WSAEINVAL ab. Wenn das POLLPRI-Flag für einen Socket für den Microsoft Winsock-Anbieter festgelegt ist, schlägt die WSAPoll-Funktion fehl.

Wenn die WSAPOLLFD-Strukturen vom fdarray-Parameter auf den Socket status:

Flag	Beschreibung
POLLERR	Es ist ein Fehler aufgetreten.
POLLHUP	Eine streamorientierte Verbindung wurde entweder getrennt oder abgebrochen.
POLLNVAL	Es wurde ein ungültiger Socket verwendet.
POLLPRI	Prioritätsdaten können ohne Blockierung gelesen werden. Dieses Flag wird vom Microsoft Winsock-Anbieter nicht zurückgegeben.
POLLRDBAND	Daten im Prioritätsband (Out-of-Band) können ohne Blockierung gelesen werden.
POLLRDNORM	Normale Daten können ohne Blockierung gelesen werden.
POLLWRNORM	Normale Daten können ohne Blockierung geschrieben werden.

In Bezug auf TCP- und UDP-Sockets:

WSAPOLLFD-Struktur als normale Daten wie POLLRDNORM.
WSAPOLLFD-Struktur : Ein anschließender Recv-Vorgang wird garantiert abgeschlossen, ohne zu blockieren.
WSAPOLLFD-Struktur von POLLWRNORM.
WSAPOLLFD-Struktur von POLLRDNORM. Ein nachfolgender Annehmen-Aufruf wird garantiert abgeschlossen, ohne zu blockieren.
WSAPOLLFD-Struktur von POLLRDBAND.
WSAPOLLFD-Struktur , wenn ein Remotepeer einen Sendevorgang herunterfährt (ein TCP-FIN wurde empfangen). Eine nachfolgende Recv-Funktionsanforderung gibt null Bytes zurück.
WSAPOLLFD-Struktur , wenn der Remotepeer eine ordnungsgemäße Trennung initiiert.
Die WSAPOLLFD-Struktur wurde zurückgegeben, wenn ein Remotepeer plötzlich die Verbindung trennt.
WSAPOLLFD-Struktur , wenn der lokale Socket geschlossen ist.

Die Anzahl der Elemente (nicht Sockets) in fdarray wird durch nfds angegeben. Mitglieder von fdarray , deren fd-Member auf einen negativen Wert festgelegt ist, werden ignoriert, und ihre Revents werden nach der Rückgabe auf POLLNVAL festgelegt. Dieses Verhalten ist nützlich für eine Anwendung, die eine feste Fdarray-Zuordnung verwaltet und das Array nicht komprimiert, um nicht verwendete Einträge zu entfernen oder Speicher neu zuzuordnen. Es ist nicht erforderlich, revents für ein Element zu löschen, bevor WSAPoll aufgerufen wird.

Das Timeoutargument gibt an, wie lange die Funktion warten soll, bevor sie zurückgegeben wird. Ein positiver Wert enthält die Anzahl von Millisekunden, die vor der Rückgabe gewartet werden müssen. Ein Nullwert zwingt WSAPoll , sofort zurückzugeben, und ein negativer Wert gibt an, dass WSAPoll auf unbestimmte Zeit warten sollte.

Hinweis Wenn Sie einen blockierenden Winsock-Aufruf wie WSAPoll ausgeben, bei dem der Timeoutparameter auf eine negative Zahl festgelegt ist, muss Winsock möglicherweise auf ein Netzwerkereignis warten, bevor der Aufruf abgeschlossen werden kann. Winsock führt in dieser Situation eine warnbare Wartezeit aus, die durch einen asynchronen Prozeduraufruf (APC) unterbrochen werden kann, der für denselben Thread geplant ist. Das Ausgeben eines weiteren blockierenden Winsock-Aufrufs in einem APC, der einen fortlaufenden blockierenden Winsock-Aufruf im selben Thread unterbrochen hat, führt zu nicht definiertem Verhalten und darf niemals von Winsock-Clients versucht werden.

Hinweis Ab Windows 10 Version 2004, wenn ein TCP-Socket keine Verbindung herstellen kann, (POLLHUP \| POLLERR \| POLLWRNORM) angegeben ist.

Windows 8.1 und Windows Server 2012 R2: Diese Funktion wird für Windows Store-Apps auf Windows 8.1, Windows Server 2012 R2 und höher unterstützt.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8.1, Windows Vista [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	winsock2.h (einschließlich Winsock2.h)
Bibliothek	Ws2_32.lib
DLL	Ws2_32.dll

Weitere Informationen

WSAGetLastError

WSAPOLLFD