LPWSPACCEPT 回呼函式（ws2spi.h）

發行項
07/16/2024

LPWSPAccept 函式會根據條件函式的傳回值，有條件地接受連接。

語法

LPWSPACCEPT Lpwspaccept;

SOCKET Lpwspaccept(
  [in]      SOCKET s,
  [out]     sockaddr *addr,
  [in, out] LPINT addrlen,
  [in]      LPCONDITIONPROC lpfnCondition,
  [in]      DWORD_PTR dwCallbackData,
  [out]     LPINT lpErrno
)
{...}

參數

[in] s

識別接聽 LPWSPListen之後之連線的套接字描述元。

[out] addr

接收連線實體位址之緩衝區的選擇性指標，稱為服務提供者。 載入宏 參數的確切格式是由建立 sockaddr 結構中的套接字時所建立的位址系列所決定。

[in, out] addrlen

整數的選擇性指標，其中包含 載入宏 參數的長度，以位元組為單位。

[in] lpfnCondition

Windows Sockets 所提供之選擇性條件函式的程序實例位址。此函式會根據傳入做為參數的呼叫端資訊，在接受或拒絕決策中使用。

[in] dwCallbackData

要傳回至 Windows Socket 2 用戶端的回呼數據，做為條件函式 dwCallbackData 參數的值。服務提供者不會解譯此參數。

[out] lpErrno

錯誤碼的指標。

傳回值

如果沒有發生錯誤，LPWSPAccept 會傳回 SOCKET 類型的值，這是接受套接字的描述項。否則，會傳回 INVALID_SOCKET的值，而且 lpErrno中提供特定的錯誤碼。

錯誤碼	意義
WSAECONNREFUSED	條件函式的傳回值（CF_REJECT）中已強制拒絕連線要求。
WSAECONNRESET	已指出連入連線，但在接受呼叫之前，遠端對等已終止。
WSAENETDOWN	網路子系統失敗。
WSAEFAULT	addrlen 參數太小，或 lpfnCondition 參數不是使用者地址空間的一部分。
WSAEINTR	已透過 LPWSPCancelBlockingCall取消呼叫。
WSAEINPROGRESS	封鎖的 Windows Sockets 呼叫正在進行中。
WSAEINVAL	LPWSPListen 在 LPWSPAccept 之前未叫用參數 g，條件函式的傳回值不是有效的值，或是指定套接字處於無效狀態的任何案例。
WSAEMFILE	佇列在輸入 LPWSPAccept 時是空的，而且沒有可用的套接字描述元。
WSAENOBUFS	沒有可用的緩衝區空間。
WSAENOTSOCK	描述元不是套接字。
WSAEOPNOTSUPP	參考的套接字不是支援連線導向服務的型別。
WSATRY_AGAIN	已延遲接受連接要求，如條件函式的傳回值（CF_DEFER）所示。
WSAEWOULDBLOCK	套接字標示為非封鎖，且未接受任何連線。
WSAEACCES	提供的連線要求已逾時或已撤銷。

言論

LPWSPAccept 函式會擷取套接字上暫止連線佇列上的第一個連線，並根據條件函式檢查它，前提是指定條件函式（也就是非 Null）。條件函式必須在與這個例程相同的線程中執行。如果條件函式傳回CF_ACCEPT，LPWSPAccept 會建立新的套接字。

新建立的套接字具有與套接字相同的屬性，包括向 LPWSPAsyncSelect 註冊的網路事件，或使用 LPWSPEventSelect註冊的網路事件。如 描述元Allocation中所述，配置新的套接字描述元時，IFS 提供者必須呼叫 WPUModifyIFSHandle 和非 IFS 提供者必須呼叫 WPUCreateSocketHandle。

如果條件函式傳回CF_REJECT，LPWSPAccept 會拒絕連線要求。如果無法立即做出應用程式的接受/拒絕決策，條件函式會傳回CF_DEFER，表示尚未做出任何決策。服務提供者不會採取此連線要求的相關動作。當應用程式準備好對連線要求採取動作時，它會再次叫用 LPWSPAccept，並傳回CF_ACCEPT或CF_REJECT作為條件函式的傳回值。

針對處於（預設）封鎖模式的套接字，如果佇列中沒有暫止連線，LPWSPAccept 封鎖呼叫端，直到連線存在為止。針對非封鎖模式中的套接字，如果在佇列中沒有暫止連線時呼叫此函式，LPWSPAccept 會傳回錯誤碼 WSAEWOULDBLOCK。接受的套接字無法用來接受更多連線。原始套接字會保持開啟狀態。

參數 載入宏 是一個結果參數，會填入連線實體的位址，稱為服務提供者。 載入宏 參數的確切格式是由通訊發生所在的位址系列所決定。 addrlen 是 value-result 參數;它一開始會包含 載入宏所指向的空間量，。在傳回時，它必須包含服務提供者所傳回地址的實際長度（以位元組為單位）。此呼叫會與連線導向的套接字類型搭配使用，例如SOCK_STREAM。如果 載入宏 和/或 addrlen 等於 null，則不會傳回所接受套接字遠端地址的相關信息。否則，無論指定條件函式還是傳回什麼，這兩個參數都應該填入。

條件函式的原型如下所示。

int CALLBACK 
ConditionFunc( 
  IN     LPWSABUF    lpCallerId, 
  IN     LPWSABUF    lpCallerData, 
  IN OUT LPQOS       lpSQOS, 
  IN OUT LPQOS       lpGQOS,
  IN     LPWSABUF    lpCalleeId, 
  IN     LPWSABUF    lpCalleeData, 
  OUT    GROUP FAR * g, 	
  IN     DWORD_PTR   dwCallbackData
);

lpCallerId 和 lpCallerData 是值參數，必須包含連接實體的位址，以及隨連線要求一起傳送的任何用戶數據。如果沒有可用的呼叫端標識碼或呼叫端數據，對應的參數會是 Null。許多網路協定不支援連線時間呼叫端數據。大部分的傳統網路協定都可以在連線要求時間支援呼叫端標識符資訊。 lpCaller Id 所指向 WSABUFbuf 部分指向 sockaddr。襪子會根據其位址系列來解譯（通常是將襪子轉換成位址系列特定的某種類型）。

lpSQOS 參數會參考呼叫者所指定的套接字流程規格，每個方向各有一個，後面接著任何其他提供者特定參數。針對任何單向套接字，傳送或接收流程規格值將會視需要忽略。 lpSQOS 的 Null 值表示沒有呼叫端提供的 QoS，而且不可能進行交涉。非NULLlpSQOS 指標表示會發生 QoS 交涉，或提供者準備接受 QoS 要求而不交涉。

lpCalleeId 是值參數，其中包含連線實體的本機位址。 WSABUF 所指向 buf 部分，lpCalleeId 指向 sockaddr。襪子會根據其位址系列來解譯（通常是將襪子轉換成位址系列特定的某種類型）。

lpCalleeData 是條件函式用來提供用戶數據給連接實體的結果參數。此數據的記憶體必須由服務提供者提供。 lpCalleeData->len 一開始包含服務提供者配置的緩衝區長度，並由 lpCalleeData所指向 ->buf。值為零表示不支援將用戶數據傳回給呼叫端。條件函式最多會將 lpCalleeData->len 位元組的數據複製到 lpCalleeData->buf，然後更新 lpCalleeData->len，以指出傳輸的實際位元組數目。如果未將用戶數據傳回給呼叫者，條件函式會將 lpCalleeData-len 設為零。所有地址和用戶數據的格式都專屬於套接字所屬的位址系列。

傳遞至 condition 函式 dwCallbackData 參數值是傳遞為原始 LPWSPAccept 呼叫中 dwCallbackData 參數的值。這個值只會由 Windows Sockets 2 用戶端解譯。這可讓用戶端將某些內容資訊從 LPWSPAccept 呼叫月臺傳遞至 condition 函式，以提供條件函式所需的任何其他資訊，以判斷是否接受連線。典型的用法是將（適當轉型）指標傳遞至數據結構，其中包含與這個套接字相關聯之應用程式定義對象的參考。

要求

要求	價值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
支援的最低伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平臺	窗戶
標頭	ws2spi.h