WSAPoll Function

The WSAPoll function determines status of one or more sockets.

Syntax

int WSAAPI WSAPoll(
  __inout  WSAPOLLFD fdarray[],
  __in     ULONG nfds,
  __in     INT timeout
);

Parameter

• fdarray [in, out]
  An array of one or more POLLFD structures specifying the set of sockets for which status is requested. The array must contain at least one structure with a valid socket. Upon return, this parameter receives the updated sockets with the revents status flags member set on each one that matches the status query criteria.

• nfds [in]
  The number of WSAPOLLFD structures in fdarray. This is not necessarily the number of sockets for which status is requested.

• timeout [in]
  A value that specifies the wait behavior, based on the following values.

  Return value	Meaning
  Greater than zero	The time, in milliseconds, to wait.
  Zero	Return immediately.
  Less than zero	Wait indefinitely.

   

Rückgabewert

Returns one of the following values.

Hinweise

The WSAPoll function is defined on Windows Vista and later.

The WSAPoll function is used to determine the status of one or more sockets. The set of sockets for which status is requested is specified in fdarray parameter, which is an array of WSAPOLLFD structures. An application sets the appropriate flags in the events member of the WSAPOLLFD structure to specify the type of status requested for each corresponding socket. The WSAPoll function returns the status of a socket in the revents member of the WSAPOLLFD structure.

For each socket, a caller can request information on read or write status. Error conditions are always returned, so information on them need not be requested.

The fdarray parameter must contain at least one valid non-negative socket. Upon return, all of the supplied sockets that either satisfy the requested status conditions or have an error condition will have the appropriate flags set on the revents member of their corresponding WSAPOLLFD structure pointed to by the fdarray parameter. All sockets that do not meet these criteria and have no error condition will have the corresponding revents member set to 0.

A combination of the following flags can be set in the events member of the WSAPOLLFD structure for a given socket when requesting status for that socket:

The POLLIN flag is defined as the combination of the POLLRDNORM and POLLRDBAND flag values. The POLLOUT flag is defined as the same as the POLLWRNORM flag value.

The events member of the WSAPOLLFD structure must only contain a combination of the above flags that are supported by the Winsock provider. Any other values are considered errors and WSAPoll will return SOCKET_ERROR. A subsequent call to the WSAGetLastError function will retrieve the extended error code of WSAEINVAL. If the POLLPRI flag is set on a socket for the Microsoft Winsock provider, the WSAPoll function will fail.

When the WSAPoll function returns a positive value, a combination of the following flags are returned in the revents member of the WSAPOLLFD structures pointed to by the fdarray parameter to indicate socket status:

With regard to TCP and UDP sockets:

• All regular TCP data and all UDP data is considered normal. So if SO_OOBINLINE has been enabled for a socket, out-of-band data will be indicated in the returned revents member of WSAPOLLFD structure as normal data as POLLRDNORM.
• When normal data is indicated in the returned revents member of WSAPOLLFD structure, a subsequent recv operation is guaranteed to complete without blocking.
• Pending connect requests are indicated in the returned revents member of WSAPOLLFD structure by POLLWRNORM.
• Pending connections on a listening socket are indicated in the returned revents member of WSAPOLLFD structure by POLLRDNORM. A subsequent call to accept is guaranteed to complete without blocking.
• Any out-of-band data is considered priority band for TCP, and is indicated in the returned revents member of WSAPOLLFD structure by POLLRDBAND.
• POLLRDNORM is indicated in the returned revents member of WSAPOLLFD structure when a remote peer shuts down a send operation (a TCP FIN was received). A subsequent recv function request will return zero bytes.
• POLLHUP is indicated in the returned revents member of WSAPOLLFD structure when the remote peer initiates a graceful disconnect.
• The POLLHUP and POLLERR are indicated in the returned revents member of WSAPOLLFD structure returned when a remote peer suddenly disconnects.
• POLLERR is indicated in the returned revents member of WSAPOLLFD structure when the local socket is closed.

The number of elements (not sockets) in fdarray is indicated by nfds. Members of fdarray which have their fd member set to a negative value are ignored and their revents will be cleared upon return. This behavior is useful to an application which maintains a fixed fdarray allocation and will not compact the array to remove unused entries or to reallocate memory. It is not necessary to clear revents for any element prior to calling WSAPoll.

The timeout argument specifies how long the function is to wait before returning. A positive value contains the number of milliseconds to wait before returning. A zero value forces WSAPoll to return immediately, and a negative value indicates that WSAPoll should wait indefinitely.

Hinweis  When issuing a blocking Winsock call such as WSAPoll with the timeout parameter set to a negative number, Winsock may need to wait for a network event before the call can complete. Winsock performs an alertable wait in this situation, which can be interrupted by an asynchronous procedure call (APC) scheduled on the same thread. Issuing another blocking Winsock call inside an APC that interrupted an ongoing blocking Winsock call on the same thread will lead to undefined behavior, and must never be attempted by Winsock clients.

Anforderungen

Siehe auch

WSAGetLastError

WSAPOLLFD