WSAJoinLeaf 函式 (winsock2.h)

WSAJoinLeaf函式會將分葉節點聯結至多點會話、交換連接資料,並根據指定的FLOWSPEC結構指定所需的服務品質。

語法

SOCKET WSAAPI WSAJoinLeaf(
  [in]  SOCKET         s,
  [in]  const sockaddr *name,
  [in]  int            namelen,
  [in]  LPWSABUF       lpCallerData,
  [out] LPWSABUF       lpCalleeData,
  [in]  LPQOS          lpSQOS,
  [in]  LPQOS          lpGQOS,
  [in]  DWORD          dwFlags
);

參數

[in] s

識別多點通訊端的描述項。

[in] name

要加入通訊端之對等的名稱。

[in] namelen

名稱長度,以位元組為單位。

[in] lpCallerData

在建立多點會話期間要傳送至對等的使用者資料指標。

[out] lpCalleeData

在建立多點會話期間,要從對等傳輸回的使用者資料指標。

[in] lpSQOS

通訊端FLOWSPEC結構的指標,每個方向各一個。

[in] lpGQOS

保留供未來與通訊端群組搭配使用。 如果適用的話,通訊端群組之 FLOWSPEC 結構的指標 () 。

[in] dwFlags

表示通訊端做為傳送者 (JL_SENDER_ONLY) 、接收者 (JL_RECEIVER_ONLY) 或兩者 (JL_BOTH) 的旗標。

傳回值

如果沒有發生錯誤, WSAJoinLeaf 會傳回 SOCKET 類型的值,這是新建立之多點通訊端的描述項。 否則,會傳回INVALID_SOCKET的值,並呼叫 WSAGetLastError來擷取特定的錯誤碼。

在封鎖通訊端上,傳回值表示聯結作業的成功或失敗。

使用非封鎖通訊端時,聯結作業的成功初始化是由傳回有效的通訊端描述元來表示。 之後,聯結作業順利完成或 失敗時, 原始通訊端上將會提供FD_CONNECT指示。 應用程式必須使用 WSAAsyncSelectWSAEventSelect 來註冊FD_CONNECT事件,以判斷聯結作業何時完成,並檢查相關聯的錯誤碼來判斷作業的成功或失敗。 select函式無法用來判斷聯結作業何時完成。

此外,在多點會話聯結嘗試完成相同通訊端上 WSAJoinLeaf 的所有後續呼叫都會失敗,並出現錯誤碼 WSAEALREADYWSAJoinLeaf作業成功完成之後,後續嘗試通常會失敗,並出現錯誤碼WSAEISCONN。 WSAEISCONN 規則的例外狀況發生在允許根起始聯結的c_root通訊端。 在這種情況下,在先前的 WSAJoinLeaf 作業完成之後,可能會起始另一個聯結。

如果傳回錯誤碼指出多點會話聯結嘗試失敗 (亦即 WSAECONNREFUSEDWSAENETUNREACHWSAETIMEDOUT) 應用程式可以針對相同的通訊端再次呼叫 WSAJoinLeaf

錯誤碼 意義
WSANOTINITIALISED
使用這個函式之前,必須先進行成功的 WSAStartup 呼叫。
WSAEADDRINUSE
通訊端的本機位址已在使用中,且通訊端未標示為允許與SO_REUSEADDR重複使用位址。 此錯誤通常會在 系結時發生,但如果系 是部分萬用字元位址 (牽涉到ADDR_ANY) ,而且必須在此函式時認可特定位址,則可能會延遲到此函式為止。
WSAEADDRNOTAVAIL
遠端位址不是 (的有效位址,例如ADDR_ANY) 。
WSAEAFNOSUPPORT
指定之系列中的位址無法用於此通訊端。
WSAEALREADY
在指定的通訊端上正在進行非封鎖 WSAJoinLeaf 呼叫。
WSAECONNREFUSED
嘗試聯結已強制拒絕。
WSAEFAULT
namenamelen參數不是使用者位址空間的有效部分、namelen參數太小、lpCalleeDatalpSQOSlpGQOS的緩衝區長度太小,或lpCallerData的緩衝區長度太大。
WSAEINVAL
WSAJoinLeaf函式呼叫是在未設定其WSA_FLAG_MULTIPOINT_C_LEAF或WSA_FLAG_MULTIPOINT_D_LEAF多重點旗標的情況下開啟的 UDP 通訊端上執行。
WSAEISCONN
通訊端已經是多點會話的成員。
WSAEINTR
封鎖的 Windows Socket 1.1 呼叫已透過 WSACancelBlockingCall取消。
WSAEINPROGRESS
封鎖的 Windows Sockets 1.1 呼叫正在進行中,或服務提供者仍在處理回呼函式。
WSAENETDOWN
網路子系統失敗。
WSAENETUNREACH
此時無法透過此主機連接網路。
WSAENOBUFS
沒有可用的緩衝區空間。 無法聯結通訊端。
WSAENOTSOCK
描述項不是通訊端。
WSAEOPNOTSUPP
無法滿足lpSQOSlpGQOS中指定的FLOWSPEC結構。
WSAEPROTONOSUPPORT
服務提供者不支援 lpCallerData 擴增。
WSAETIMEDOUT
嘗試加入逾時,而不需建立多點會話。

備註

WSAJoinLeaf函式可用來將分葉節點聯結至多點會話,以及執行一些在會話聯結時間發生的其他輔助作業。 如果通訊端 系結,系統會將唯一值指派給本機關聯,而且通訊端會標示為系結。

WSAJoinLeaf函式的參數和語意與WSAConnect相同,不同之處在于它會傳回通訊端描述元 (,如同WSAAccept) ,而且有額外的dwFlags參數。 只有使用 WSASocket 與適當多點旗標集所建立的多點通訊端,才能用於此函 式中的輸入 參數。 在聯結作業完成之前,傳回的通訊端描述元將無法使用。 例如,如果在從原始通訊端上的WSAAsyncSelectWSAEventSelect收到對應的FD_CONNECT指示之後,通訊端處於非封鎖模式,但這個新的通訊端描述元可能會叫用closesocket來解除擱置聯結作業。 多點會話中的根應用程式可能會呼叫 WSAJoinLeaf 一或多次,以新增數個分葉節點,不過一次最多可能會有一個多點連線要求未處理。 如需其他資訊,請參閱 多點和多播語意

對於非封鎖通訊端,通常無法立即完成連線。 在這種情況下,此函式會傳回尚未無法使用的通訊端描述項,並繼續進行作業。 在此情況下沒有錯誤碼,例如 WSAEWOULDBLOCK ,因為函式已有效地傳回成功的啟動指示。 當最終結果成功或失敗變成已知時,可能會透過 WSAAsyncSelectWSAEventSelect 回報,視用戶端在 原始通訊端上註冊通知的方式而定。 不論是哪一種情況,通知都會以FD_CONNECT宣告,而與FD_CONNECT相關聯的錯誤碼表示成功或失敗的特定原因。 select函式無法用來偵測WSAJoinLeaf的完成通知。

WSAJoinLeaf所傳回的通訊端描述元會根據輸入通訊端描述元s是c_root還是c_leaf而有所不同。 搭配c_root通訊端使用時, name 參數會指定要新增的特定分葉節點,而傳回的通訊端描述項是對應至新加入分葉節點的c_leaf通訊端。 新建立的通訊端具有與 s相同的屬性,包括向 WSAAsyncSelectWSAEventSelect註冊的非同步事件。 它並非用於交換多點資料,而是用來接收網路事件指示 (例如,FD_CLOSE) 存在於特定c_leaf的連線。 某些多點實作也可以允許此通訊端用於根節點與個別分葉節點之間的側邊聊天。 如果對應的分葉節點呼叫 closesocket 來卸載多點會話,則會收到此通訊端的FD_CLOSE指示。 對稱地,在從WSAJoinLeaf傳回的c_leaf通訊端上叫用closesocket會導致對應分葉節點中的通訊端收到FD_CLOSE通知。

使用c_leaf通訊端叫用 WSAJoinLeaf 時, name 參數會包含根應用程式 (根應用程式的位址,) 或現有的多點會話 (非根目錄控制配置) ,而傳回的通訊端描述元與輸入通訊端描述項相同。 換句話說,不會配置新的通訊端描述元。 在根控制配置中,根應用程式會藉由呼叫 listen,將其c_root通訊端放在接 模式中。 當分葉節點要求將本身加入多點會話時,將會傳遞標準FD_ACCEPT通知。 根應用程式會使用一般 acceptWSAAccept 函式來允許新的分葉節點。 從 acceptWSAAccept 傳回的值也是c_leaf通訊端描述元,就像從 WSAJoinLeaf傳回的值一樣。 為了容納允許根起始和分葉起始聯結的多點配置,可接受已在接聽模式中做為 WSAJoinLeaf輸入的c_root通訊端。

應用程式負責配置它所指定任何參數直接或間接指向的任何記憶體空間。

lpCallerData是一個值參數,其中包含要連同多點會話聯結要求一起傳送的任何使用者資料。 如果 lpCallerDataNull,則不會將使用者資料傳遞至對等。 lpCalleeData是結果參數,其中包含從對等傳回的任何使用者資料,做為多點會話建立的一部分。 lpCalleeData參數所指向之WSABUF結構的len成員一開始包含應用程式所配置的緩衝區長度,並由WSABUF結構的buf成員所指向。 lpCalleeData參數所指向之 WSABUF結構的len成員將會在未傳回使用者資料時設定為零。 當多點聯結作業完成時 ,lpCalleeData 資訊將會有效。

對於封鎖通訊端,這會是 WSAJoinLeaf 函式傳回時。 針對非封鎖通訊端,這會在聯結作業完成之後。 例如,這可能是在 原始通訊端) 上FD_CONNECT通知之後發生。 如果 lpCalleeDataNull,則不會傳回任何使用者資料。 使用者資料的確切格式專屬於通訊端所屬的位址系列。

在多點會話建立期間,應用程式可以使用 lpSQOS 和/或 lpGQOS 參數來覆寫透過 WSAIoctl 透過 WSAIoctl 對通訊端所做的任何先前服務品質規格,搭配 SIO_SET_QOS 或 SIO_SET_GROUP_QOS opcode。

lpSQOS參數會指定通訊端FLOWSPEC結構,每個方向各有一個,後面接著任何其他提供者特定參數。 如果一般相關聯的傳輸提供者或特定類型的通訊端無法接受服務需求品質,則會傳回錯誤,如下列所示。 任何單向通訊端都會忽略個別的傳送或接收流程規格值。 如果未指定提供者特定的參數,則 lpCalleeData參數所指向之 WSABUF結構的buflen成員應該分別設定為Null和零。 lpSQOSNull值表示沒有應用程式提供的服務品質。

保留給未來的通訊端群組。 lpGQOS參數會指定通訊端群組的FLOWSPEC結構 (,如果適用) ,每個方向各指定一個,後面接著任何其他提供者特定參數。 如果未指定提供者特定的參數,則 lpCalleeData參數所指向之 WSABUF結構的buflen成員應該分別設定為Null和零。 lpGQOSNull值表示沒有應用程式提供的群組服務品質。 如果 s 不是通訊端群組的建立者,則會忽略此參數。

當連線的通訊端中斷 (即會因為任何原因而關閉) 時,應該捨棄並重新建立它們。 假設因為連線通訊端上任何原因而發生問題時,應用程式必須捨棄並重新建立所需的通訊端,才能返回穩定點。

注意 發出封鎖的 Winsock 呼叫,例如 WSAJoinLeaf 時,Winsock可能需要等候網路事件,才能完成呼叫。 Winsock 會在這種情況中執行可警示的等候,而非同步程序呼叫 (APC) 排程在同一個執行緒上,可能會中斷。 在 APC 內發出另一個封鎖 Winsock 呼叫,中斷相同執行緒上持續封鎖 Winsock 呼叫會導致未定義的行為,而且永遠不會由 Winsock 用戶端嘗試。
 
Windows Phone 8:Windows Phone 8 和更新版本Windows Phone市集應用程式支援此函式。

Windows 8.1Windows Server 2012 R2:Windows 市集應用程式支援此函式,Windows 8.1、Windows Server 2012 R2 及更新版本。

規格需求

   
最低支援的用戶端 Windows 8.1、Windows Vista [傳統型應用程式|UWP 應用程式]
最低支援的伺服器 Windows Server 2003 [傳統型應用程式|UWP 應用程式]
目標平臺 Windows
標頭 winsock2.h
程式庫 Ws2_32.lib
DLL Ws2_32.dll

另請參閱

WSAAccept

WSAAsyncSelect

WSABUF

WSAEventSelect

WSASocket

Winsock 函式

Winsock 參考

接受

bind

select