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指示。 應用程式必須使用 WSAAsyncSelect 或 WSAEventSelect 來註冊FD_CONNECT事件，以判斷聯結作業完成的時間，並檢查相關聯的錯誤碼，以判斷作業成功或失敗。 select 函式無法用來判斷聯結作業何時完成。

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

如果傳回錯誤碼指出多點會話聯結嘗試失敗 (亦即 WSAECONNREFUSED、 WSAENETUNREACH、 WSAETIMEDOUT) 應用程式可以針對相同的套接字再次呼叫 WSAJoinLeaf 。

錯誤碼 意義
WSANOTINITIALISED
 使用此函式之前，必須先進行成功的 WSAStartup 呼叫。
WSAEADDRINUSE
 套接字的本機位址已在使用中，且套接字未標示為允許使用SO_REUSEADDR重複使用位址。 這個錯誤通常會在 系結時發生，但如果系 結 至涉及ADDR_ANY) 的部分通配符地址 (，而且需要在此函式期間認可特定位址，則可能會延遲到此函式。
WSAEADDRNOTAVAIL
 遠程位址不是有效的位址 (，例如 ADDR_ANY) 。
WSAEAFNOSUPPORT
 指定之系列中的位址無法用於此通訊端。
WSAEALREADY
 指定的套接字上正在進行非封鎖 WSAJoinLeaf 呼叫。
WSAECONNREFUSED
 嘗試加入的嘗試已強制拒絕。
WSAEFAULT
 名稱或 namelen 參數不是使用者位址空間的有效部分、namelen 參數太小、lpCalleeData、lpSQOS 和 lpGQOS 的緩衝區長度太小，或 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
 無法滿足 lpSQOS 和 lpGQOS 中指定的 FLOWSPEC 結構。
WSAEPROTONOSUPPORT
 服務提供者不支援 lpCallerData 擴增。
WSAETIMEDOUT
 嘗試加入逾時，而不需建立多點會話。

備註

WSAJoinLeaf 函式可用來將分葉節點聯結至多點會話，以及執行一些其他在會話聯結時間發生的輔助作業。 如果套接字 未 系結，則會將唯一值指派給系統的區域關聯，而套接字會標示為系結。

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

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

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

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

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

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

對於封鎖套接字，這會是 WSAJoinLeaf 函式傳回時。 針對非封鎖套接字，這會在聯結作業完成之後。 例如，這可能是在 原始套接字) 上FD_CONNECT通知之後發生。 如果 lpCalleeData 為 NULL，則不會傳回任何用戶數據。 用戶數據的確切格式專屬於套接字所屬的位址系列。

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

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

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

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

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

Windows 8.1和 Windows 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