WSAPoll 函式 (winsock2.h)

  • 發行項

WSAPoll 函式會決定一或多個套接字的狀態。

語法

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

參數

[in, out] fdArray

一或多個 POLLFD 結構的陣列，指定要求狀態的套接字集。 數位至少必須包含一個具有有效套接字的結構。 傳回時，此參數會接收更新的套接字，其中包含每個符合狀態查詢準則的 revents 狀態旗標成員。

[in] fds

在 azurerray 中的 WSAPOLLFD 結構數目。 這不一定是要求狀態的套接字數目。

[in] timeout

值，根據下列值指定等候行為。

值 意義
大於零 要等候的時間，以毫秒為單位。
零個 立即傳回。
小於零 無限期等候。

傳回值

傳回下列其中一個值。

傳回值 描述
零個 定時器過期之前，沒有套接字處於查詢狀態。
大於零 pollFD 結構的 revents 成員為非零的項目數目。
SOCKET_ERROR 發生錯誤。 呼叫 WSAGetLastError 函式以擷取擴充的錯誤碼。
 
擴充錯誤碼 意義
WSAENETDOWN
 網路子系統失敗。
WSAEFAULT
 讀取使用者輸入參數時發生例外狀況。
WSAEINVAL
 傳遞了一個無效的參數。 如果要求套接字狀態時，由sslrray 參數指向的WSAPOLLFD結構，就會傳回此錯誤。 如果任何 WSAPOLLFD 結構所指向之 WSAPOLLFD 結構的 fd 成員中未指定任何套接字有效，也會傳回這個錯誤。
WSAENOBUFS
 函式無法配置足夠的記憶體。

備註

WSAPoll 函式是在 Windows Vista 和更新版本上定義。

WSAPOLLFD 結構。 應用程式會在 WSAPOLLFD 結構的事件成員中設定適當的旗標，以指定每個對應套接字所要求的狀態類型。 WSAPoll 函式會傳回 WSAPOLLFD 結構之 revents 成員中的套接字狀態。

針對每個套接字，呼叫端可以要求讀取或寫入狀態的相關信息。 錯誤條件一律會傳回，因此不需要要求它們的相關信息。

由 azurerray 參數指向的 WSAPOLLFD 結構。 不符合這些準則且沒有錯誤條件的所有套接字，都會將對應的 revents 成員設定為 0。

當要求該套接字的狀態時，可以在指定套接字的 WSAPOLLFD 結構中設定下列旗標的組合：

旗標 描述
POLLPRI 優先順序數據可能會讀取，而不會封鎖。 Microsoft Winsock 提供者不支援此旗標。
POLLRDBAND 優先順序訊號範圍 (頻外) 數據可能會讀取，而不會封鎖。
POLLRDNORM 一般數據可能會讀取而不封鎖。
POLLWRNORM 一般數據可以寫入而不封鎖。
 

POLLIN 旗標會定義為 POLLRDNORM 和 POLLRDBAND 旗標值的組合。 POLLOUT 旗標的定義與 POLLWRNORM 旗標值相同。

WSAPOLLFD 結構必須只包含 Winsock 提供者支援的上述旗標組合。 任何其他值都會被視為錯誤， WSAPoll 會傳回 SOCKET_ERROR。 後續呼叫 WSAGetLastError 函式將會擷取 WSAEINVAL 的擴充錯誤碼。 如果 POLLPRI 旗標是在 Microsoft Winsock 提供者的套接字上設定， WSAPoll 函式將會失敗。

當由 azurerray 參數指向的 WSAPOLLFD 結構指出套接字狀態時：

旗標 描述
POLLERR 發生錯誤了。
POLLHUP 數據流導向連線已中斷連線或中止。
POLLNVAL 使用無效的套接字。
POLLPRI 優先順序數據可能會讀取，而不會封鎖。 Microsoft Winsock 提供者不會傳回此旗標。
POLLRDBAND 優先順序訊號範圍 (頻外) 數據可能會讀取，而不會封鎖。
POLLRDNORM 一般數據可能會讀取而不封鎖。
POLLWRNORM 一般數據可以寫入而不封鎖。
 

關於 TCP 和 UDP 套接字：

  • WSAPOLLFD 結構做為 POLLRDNORM 的一般數據。
  • WSAPOLLFD 結構，後續 的 recv 作業保證會完成，而不會封鎖。
  • 由 POLLWRNORM 建立的 WSAPOLLFD 結構。
  • 由 POLLRDNORM 建立的 WSAPOLLFD 結構。 後續的 接受 呼叫保證會完成，而不會封鎖。
  • 由 POLLRDBAND 建立的 WSAPOLLFD 結構。
  • 當遠端對等關閉傳送作業時， (收到 TCP FIN) 時，WSAPOLLFD 結構。 後續 的 recv 函式要求會傳回零個字節。
  • 當遠端對等起始正常中斷連線時，WSAPOLLFD 結構。
  • 當遠端對等突然中斷連線時，傳回 WSAPOLLFD 結構。
  • 關閉本機套接字時，WSAPOLLFD 結構。

(不是在) 於) 的項目數目是由 nfds 表示。 已將其 fd 成員設定為負值的成員會被忽略，而且其回復會在傳回時設定為 POLLNVAL。 此行為對於維護固定 的 azurerray 配置的應用程式很有用，而且不會壓縮數位來移除未使用的專案或重新配置記憶體。 呼叫 WSAPoll 之前，不需要清除任何元素的回應。

timeout 自變數會指定函式在傳回前等候的時間長度。 正值包含傳回前要等候的毫秒數。 零值會強制 WSAPoll 立即傳回，負值表示 WSAPoll 應該無限期等候。

注意 發出封鎖的 Winsock 呼叫時，例如 WSAPoll ， 並將 timeout 參數設定為負數時，Winsock 可能需要等候網路事件，才能完成呼叫。 Winsock 會在這種情況中執行可警示的等候，而異步過程調用 (APC) 排程在同一個線程上，可能會中斷。 在 APC 內發出另一個封鎖 Winsock 呼叫，中斷相同線程上持續封鎖 Winsock 呼叫會導致未定義的行為，而且永遠不會由 Winsock 客戶端嘗試。
 
注意自 Windows 10 2004 版起，當 TCP 套接字無法連線時， (POLLHUP \|POLLERR \|指出POLLWRNORM) 。
 

Windows 8.1 和 Windows Server 2012 R2：Windows 8.1、Windows Server 2012 R2 及更新版本上的 Windows 市集應用程式支援此函式。

規格需求

需求 值
最低支援的用戶端 Windows 8.1、Windows Vista [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2008 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 winsock2.h (包括 Winsock2.h)
程式庫 Ws2_32.lib
Dll Ws2_32.dll

另請參閱

WSAGetLastError

WSAPOLLFD