共用方式為

LPWSPEVENTSELECT 回調函式 （ws2spi.h）

  • 發行項

LPWSPEventSelect 函式會指定要與所提供網路事件集相關聯的事件物件。

語法

LPWSPEVENTSELECT Lpwspeventselect;

int Lpwspeventselect(
  [in]  SOCKET s,
  [in]  WSAEVENT hEventObject,
  [in]  long lNetworkEvents,
  [out] LPINT lpErrno
)
{...}

參數

[in] s

識別套接字的描述項。

[in] hEventObject

識別要與所提供網路事件集相關聯之事件物件的句柄。

[in] lNetworkEvents

位掩碼，指定 Windows Sockets SPI 用戶端感興趣的網路事件組合。 使用位 OR 運算元搭配任何這些值來建構。

價值 意義
FD_READ
 發出讀取整備的通知。
FD_WRITE
 發出準備寫入的通知。
FD_OOB
 發出 OOB 數據抵達的通知。
FD_ACCEPT
 發出連入連線的通知。
FD_CONNECT
 發出已完成連線的通知。
FD_CLOSE
 發出套接字關閉通知。
FD_QOS
 發出套接字 （QoS） 變更的通知。
FD_GROUP_QOS
 保留。
FD_ROUTING_INTERFACE_CHANGE
 發出指定目的地路由介面變更的通知。
FD_ADDRESS_LIST_CHANGE
 發出套接字位址系列之本機位址清單變更的通知。

[out] lpErrno

錯誤碼的指標。 如需詳細資訊，請參閱 傳回值 一節。

傳回值

如果 Windows Sockets SPI 用戶端的網路事件規格和相關聯的事件物件成功，則傳回值為零。 否則，會傳回 SOCKET_ERROR 值，而且 lpErrno中提供特定的錯誤號碼。

錯誤碼 意義
WSAENETDOWN
 網路子系統失敗。
WSAEINVAL
 表示其中一個指定的參數無效，或指定的套接字處於無效狀態。
WSAEINPROGRESS
 封鎖 Windows Sockets 呼叫正在進行中，或服務提供者仍在處理回呼函式。
WSAENOTSOCK
 描述元不是套接字。

言論

此函式可用來指定與所選網路事件相關聯的事件物件 hEventObject，lNetworkEvents。 指定事件物件的套接字是由 來識別。 當任何指定的網路事件發生時，就會設定事件物件。

LPWSPEventSelect 的運作方式與 LPWSPAsyncSelect非常類似，在發生指定網路事件時所採取的動作差異。 雖然 WSPAsyncSelect 會導致張貼 Windows Sockets SPI 用戶端指定的 Windows 訊息，LPWSPEventSelect 設定相關聯的事件物件，並將此事件記錄在內部網路事件記錄中。 Windows Sockets SPI 用戶端可以使用 LPWSPEnumNetworkEvents 來擷取內部網路事件記錄的內容，從而判斷已發生哪些指定的網路事件。

LPWSPEventSelect 是唯一會導致透過 LPWSPEnumNetworkEvents記錄和擷取網路活動和錯誤的功能。 請參閱 LPWSPSelect 和 LPWSPAsyncSelect 的描述，以了解這些函式如何報告網路活動和錯誤。

不論 lNetworkEvents的值為何，此函式會自動將套接字 設定為非封鎖模式。

針對套接字發出 LPWSPEventSelect 會取消任何先前的 LPWSPAsyncSelect 或 LPWSPEventSelect，並清除內部網路事件記錄。 例如，若要將事件對象與讀取和寫入網路事件產生關聯，Windows Sockets SPI 用戶端必須呼叫 LPWSPEventSelect，FD_READ和FD_WRITE，如下所示。

rc = WSPEventSelect(s, hEventObject, FD_READ | FD_WRITE);

無法為不同的網路事件指定不同的事件物件。 下列程式代碼無法運作;第二個呼叫會取消第一個的效果，唯一的關聯將是與 hEventObject2 相關聯的FD_WRITE網路事件。

// Incorrect example.
rc = WSPEventSelect(s, hEventObject1, FD_READ);
rc = WSPEventSelect(s, hEventObject2, FD_WRITE);

若要取消套接字上網路事件的關聯和選取，您應該將 lNetworkEvents 設定為零 ，在此情況下會忽略 hEventObject 參數。

rc = WSPEventSelect(s, hEventObject, 0);

關閉具有 LPWSPCloseSocket 的套接字 也會取消套接字在 LPWSPEventSelect 中指定的網路事件關聯和選取。 不過，Windows Sockets SPI 用戶端仍必須呼叫 WSACloseEvent，才能明確關閉事件物件，並釋放任何資源。

由於 LPWSPAccept'ed 套接字具有與用來接受它之接聽套接字相同的屬性，因此任何 LPWSPEventSelect 關聯和網路事件選取集的接聽套接字都會套用至接受的套接字。 例如，如果接聽套接字 LPWSPEventSelect 與FD_ACCEPT、FD_READ和FD_WRITE hEventObject 關聯，則接聽套接字上接受的任何套接字也會有與相同 hEventObject相關聯的FD_ACCEPT、FD_READ和FD_WRITE網路事件。 如果需要不同的 hEventObject 或網路事件，則 Windows Sockets SPI 用戶端應該呼叫 LPWSPEventSelect、傳遞接受的套接字和所需的新資訊。

成功記錄網路事件併發出相關事件對象的訊號后，除非 Windows Sockets SPI 用戶端發出函式呼叫，以隱含方式重新啟用該網路事件的設定，併發出相關聯事件對象的訊號，否則不會對該網路事件採取進一步的動作。

網路事件 重新啟用函式
FD_READ LPWSPRecv 或 LPWSPRecvFrom
FD_WRITE LPWSPSend 或 LPWSPSendTo
FD_OOB LPWSPRecv 或 LPWSPRecvFrom
FD_ACCEPT LPWSPAccept，除非傳回的錯誤碼WSATRY_AGAIN指出條件函式傳回CF_DEFER
FD_CONNECT 沒有
FD_CLOSE 沒有
FD_QOS LPWSPIoctl 與 SIO_GET_QOS
FD_GROUP_QOS 保留供未來搭配套接字群組使用：LPWSPIoctl 搭配 SIO_GET_GROUP_QOS
FD_ROUTING_INTERFACE_CHANGE 使用命令SIO_ROUTING_INTERFACE_CHANGE LPWSPIoctl
FD_ADDRESS_LIST_CHANGE 使用命令SIO_ADDRESS_LIST_CHANGE LPWSPIoctl

重新啟用例程的任何呼叫，甚至是失敗的例程，都會導致重新啟用相關網路事件和事件對象的錄製和訊號。

針對FD_READ、FD_OOB和FD_ACCEPT網路事件、網路事件錄製和事件物件訊號，層級觸發。 這表示，如果呼叫重新啟用例程，且相關網路條件在呼叫之後仍然有效，則會記錄網路事件，併發出相關聯的事件物件訊號。 這可讓 Windows Sockets SPI 用戶端成為事件驅動，同時也不會因為任何一次抵達的數據量而造成不滿。 請考慮下列順序。

  1. 服務提供者會在套接字 上接收 100 位元組的數據、記錄FD_READ網路事件，併發出相關聯的事件物件的訊號。
  2. Windows Sockets SPI 用戶端 WSPRecv(s, buffptr, 50, 0) 發出讀取 50 個字節的問題。
  3. 服務提供者會記錄FD_READ網路事件，並再次向相關聯的事件對象發出訊號，因為仍有待讀取的數據。

使用這些語意，Windows Sockets SPI 用戶端不需要讀取所有可用的數據，以回應FD_READ網路事件。 相反地，回應每個FD_READ網路事件的單一 LPWSPRecv 是適當的。

FD_QOS與FD_GROUP_QOS事件會視為 邊緣觸發。 當服務品質（QOS） 變更發生時，只會張貼一則訊息。 除非服務提供者偵測到 QOS 中的進一步變更，否則不會發出進一步指示，或 Windows Sockets SPI 用戶端會重新談判套接字的 QOS。

FD_ROUTING_INTERFACE_CHANGE和FD_ADDRESS_LIST_CHANGE事件也會視為 邊緣觸發。 在 Windows Sockets SPI 用戶端發出 WSAIoctl，並對應發出具有SIO_ROUTING_INTERFACE_CHANGE或SIO_ADDRESS_LIST_CHANGE的 WSAIoctl 之後，發生變更之後，就會只張貼一則訊息。 在 Windows Sockets SPI 用戶端重新發出 IOCTL 並偵測到另一個變更之後，才會發出進一步訊息， 另一個變更。

如果 Windows Sockets SPI 用戶端呼叫 LPWSPEventSelect時發生網路事件，或呼叫重新啟用函式時，就會記錄網路事件，並視需要發出相關聯的事件對象訊號。 例如，請考慮下列順序。

  1. Windows Sockets SPI 用戶端會呼叫 LPWSPListen。
  2. 收到連線要求，但尚未接受。
  3. Windows Sockets SPI 用戶端會呼叫 LPWSPEventSelect 指定它對套接字FD_ACCEPT網路事件感興趣。 服務提供者會記錄FD_ACCEPT網路事件，並立即發出相關事件對象的訊號。

FD_WRITE網路事件會以稍微不同的方式處理。 當套接字第一次與 LPWSPConnect 連線或接受 LPWSPAccept時，會記錄FD_WRITE網路事件，然後在 LPWSPSend 或 LPWSPSendTo 失敗，WSAEWOULDBLOCK 和緩衝區空間變成可用之後。 因此，Windows Sockets SPI 用戶端可以假設從第一個FD_WRITE網路事件設定開始傳送，並持續到傳送傳回 WSAEWOULDBLOCK 為止。 發生這類失敗之後，Windows Sockets SPI 用戶端會發現，當記錄FD_WRITE網路事件併發出相關聯的事件物件訊號時，可能會再次傳送傳送。

只有在套接字設定為個別接收頻外數據時，才會使用FD_OOB網路事件。 如果套接字設定為接收頻外數據內嵌，則會將頻外（加速）數據視為一般數據，而 Windows Sockets SPI 用戶端應該註冊感興趣的專案，而且會取得FD_READ網路事件，而不是FD_OOB網路事件。 Windows Sockets SPI 用戶端可以使用 LPWSPSetSockOpt 或 LPWSPGetSockOpt SO_OOBINLINE 來處理頻外數據的方式。

FD_CLOSE網路事件中的錯誤碼會指出套接字關閉是否正常或中止。 如果錯誤碼為 0，則關閉是正常;如果錯誤碼為 WSAECONNRESET，則會重設套接字的虛擬線路。 這隻適用於連線導向的套接字，例如SOCK_STREAM。

當收到對應至套接字之虛擬線路的關閉指示時，就會記錄FD_CLOSE網路事件。 在 TCP 方面，這表示當連線進入 FIN WAIT 或 CLOSE WAIT 狀態時，會記錄FD_CLOSE。 這會導致遠端端在傳送端執行 LPWSPShutdown，或 LPWSPCloseSocket。

服務提供者應該只記錄 FD_CLOSE 網路事件，以指出虛擬線路關閉：它應該 不要 記錄FD_READ網路事件，以指出該條件。

當流量規格中與套接字 相關聯的任何字段變更，或 所屬的套接字群組時，就會記錄FD_QOS或FD_GROUP_QOS網路事件。 您必須透過具有 SIO_GET_QOS 和/或 SIO_GET_GROUP_QOS 的 LPWSPIoctl 函式，向 Windows Sockets SPI 用戶端提供這項變更，以分別擷取套接字 的目前 QOS，或分別屬於 的套接字群組。

FD_ROUTING_INTERFACE_CHANGE網路事件是在發出這類 IOCTL 之後，SIO_ROUTING_INTERFACE_CHANGE 變更 WSAIoctl 中指定的本機介面時，記錄FD_ROUTING_INTERFACE_CHANGE網路事件。

FD_ADDRESS_LIST_CHANGE網路事件會在發出 WSAIoctl SIO_ADDRESS_LIST_CHANGE 之後，Windows Sockets SPI 用戶端可以繫結變更 的套接字通訊協定系列清單時，會記錄FD_ADDRESS_LIST_CHANGE網路事件。

要求

要求 價值
最低支援的用戶端 Windows 10 組建 20348
支援的最低伺服器 Windows 10 組建 20348
標頭 ws2spi.h

另請參閱

LPWSPEnumNetworkEvents