共用方式為

LPWSPJOINLEAF 回呼函式 (ws2spi.h)

  • 發行項

WSPJoinLeaf函式會將分葉節點聯結至多點會話、交換連線資料，並根據提供的流程規格指定所需的服務品質。

語法

LPWSPJOINLEAF Lpwspjoinleaf;

SOCKET Lpwspjoinleaf(
  [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,
  [out] LPINT lpErrno
)
{...}

參數

[in] s

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

[in] name

要聯結 sockaddr 結構中通訊端的對等名稱。

[in] namelen

名稱的長度，以位元組為單位。

[in] lpCallerData

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

[out] lpCalleeData

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

[in] lpSQOS

通訊端 的流程規格指標，每個方向各一個。

[in] lpGQOS

保留的。

[in] dwFlags

表示通訊端做為傳送者、接收者或兩者的旗標。

[out] lpErrno

錯誤碼的指標。

傳回值

如果沒有發生錯誤， WSPJoinLeaf 會傳回 SOCKET 類型的值，這是新建立之多點通訊端的描述項。 否則，會傳回INVALID_SOCKET的值，並在 lpErrno中提供特定的錯誤碼。

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

使用非封鎖通訊端時，聯結作業的成功初始化是由有效通訊端描述元的傳回值來表示。 接著，聯結作業順利或成功完成時，會指定FD_CONNECT指示。 與FD_CONNECT相關聯的錯誤碼表示 WSPJoinLeaf的成功或失敗。

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

如果傳回錯誤碼指出多點會話聯結嘗試失敗 (亦即 WSAECONNREFUSED、 WSAENETUNREACH、 WSAETIMEDOUT) Windows Sockets SPI 用戶端可以針對相同的通訊端再次呼叫 WSPJoinLeaf 。

錯誤碼 意義
WSAENETDOWN
 網路子系統失敗。
WSAEADDRINUSE
 通訊端的本機位址已在使用中，且通訊端未標示為允許使用SO_REUSEADDR重複使用位址。 此錯誤通常會在 系結時發生，但如果 **bind** 是部分萬用字元位址， (涉及ADDR_ANY) ，而且此函式時需要「認可」特定位址，可能會延遲到此函式為止。
WSAEINTR
 (透過 WSPCancelBlockingCall取消封鎖) 呼叫。
WSAEINPROGRESS
 封鎖 Windows Sockets 呼叫正在進行中，或服務提供者仍在處理回呼函式。
WSAEALREADY
 在指定的通訊端上正在進行非封鎖 WSPJoinLeaf 呼叫。
WSAEADDRNOTAVAIL
 例如，遠端位址不是有效的位址 (，ADDR_ANY) 。
WSAEAFNOSUPPORT
 指定之系列中的位址無法用於此通訊端。
WSAECONNREFUSED
 嘗試聯結已強制拒絕。
WSAEFAULT
 name或namelen參數不是使用者位址空間的有效部分、namelen參數太小、lpCalleeData、lpSQOS和lpGQOS的緩衝區長度太小，或lpCallerData的緩衝區長度太大。
WSAEISCONN
 Socket 已經是多點會話的成員。
WSAENETUNREACH
 此時無法透過此主機連接網路。
WSAENOBUFS
 沒有可用的緩衝區空間。 無法聯結通訊端。
WSAENOTSOCK
 描述項不是通訊端。
WSAEOPNOTSUPP
 無法滿足 lpSQOS 中指定的流程規格。
WSAEPROTONOSUPPORT
 服務提供者不支援 lpCallerData 擴增。
WSAETIMEDOUT
 嘗試加入逾時，而不需建立多點會話。
 
 

備註

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

WSPJoinLeaf 的參數和語意與 LPWSPConnect 相同，不同之處在于它會傳回通訊端描述元 (，如同 在 LPWSPAccept) ，而且有額外的 dwFlags 參數。 只有使用 LPWSPSocket 與適當多點旗標集所建立的多點通訊端，才能用於此函 式中的輸入 參數。 如果通訊端處於非封鎖模式，在收到 原始通訊端的 對應FD_CONNECT指示之後，才能使用傳回的通訊端描述元，但在此新的通訊端描述元上可以叫用 closesocket 來解除擱置聯結作業。 多點會話中的根節點可以呼叫 WSPJoinLeaf 一或多次，以新增一些分葉節點，不過一次最多可以處理一個多點連線要求。 如需詳細資訊，請參閱 SPI 中的通訊協定獨立多播和多點 。

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

WSPJoinLeaf所傳回的通訊端描述元會根據輸入通訊端描述元s是c_root還是c_leaf而有所不同。 搭配c_root通訊端使用時， name 參數會指定要新增的特定分葉節點，而傳回的通訊端描述項是對應至新加入分葉節點的c_leaf通訊端。 (如描述 元配置一節所述，配置新的通訊端描述項時，IFS 提供者必須呼叫 WPUModifyIFSHandle ，且非 IFS 提供者必須呼叫 WPUCreateSocketHandle) 。 新建立的通訊端具有與 相同的屬性 ， 包括向 LPWSPAsyncSelect 或 LPWSPEventSelect註冊的非同步事件。 它並非用於交換多點資料，而是用來接收網路事件指示 (例如，FD_CLOSE) 存在於特定c_leaf的連線。 有些多點實作也可以允許此通訊端用於根節點與個別分葉節點之間的「側邊聊天」。 如果對應的分葉節點呼叫 LPWSPCloseSocket 來卸載多點會話，將會收到此通訊端的FD_CLOSE指示。 對稱方式，在從WSPJoinLeaf傳回的c_leaf通訊端上叫用WSPCloseSocket會導致對應分葉節點中的通訊端收到FD_CLOSE通知。

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

Windows Sockets SPI 用戶端負責配置它所指定任何參數直接或間接指向的任何記憶體空間。

lpCallerData是一個值參數，其中包含要連同多點會話聯結要求一起傳送的任何使用者資料。 如果 lpCallerData 為 Null，則不會將使用者資料傳遞給對等。 lpCalleeData是結果參數，其中包含從對等傳回的任何使用者資料，作為多點會話建立的一部分。 lpCalleeData-len> 最初包含 Windows Sockets SPI 用戶端所配置的緩衝區長度，並由lpCalleeData-buf> 指向。 如果未傳回任何使用者資料，lpCalleeData-len> 將會設定為零。 當多點聯結作業完成時， lpCalleeData 資訊將會有效。 針對封鎖通訊端，這會是 WSPJoinLeaf 函式傳回時。 對於非封鎖通訊端，這會在 原始通訊端上發生FD_CONNECT通知之後。 如果 lpCalleeData 為 Null，則不會傳回任何使用者資料。 使用者資料的確切格式專屬於通訊端所屬的位址系列和/或涉及的應用程式。

在建立多點會話時，Windows Sockets SPI 用戶端可以使用 lpSQOS 參數，透過 LPWSPIoctl 覆寫透過 LPWSPIoctl 針對通訊端所做的任何先前 QoS 規格，並搭配 SIO_SET_QOS opcode。

lpSQOS 會指定通訊端 的流程規格，每個方向各指定一個，後面接著任何其他提供者特定的參數。 如果一般相關聯的傳輸提供者或特定類型的通訊端無法接受 QoS 要求，則會傳回錯誤，如下所示。 對於任何單向通訊端，將會分別忽略傳送或接收流程規格值。 如果未提供提供者特定的參數，則 lpSQOS-ProviderSpecific> 的buf和len成員應該分別設定為Null和零。 lpSQOS的Null值表示沒有應用程式提供服務品質。

dwFlags參數用來指出通訊端是否只做為傳送者 (JL_SENDER_ONLY) 、接收者 (JL_RECEIVER_ONLY) 或兩者 (JL_BOTH) 。

**注意** 當連線的通訊端中斷 (即因為任何原因而關閉) 時，應該捨棄並重新建立它們。 最安全的方式是假設當連線通訊端上發生任何原因時，Windows Sockets SPI 用戶端必須捨棄並重新建立所需的通訊端，才能回到穩定點。
 

規格需求

   
最低支援的用戶端 Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器 Windows 2000 Server [僅限桌面應用程式]
目標平台 Windows
標頭 ws2spi.h

另請參閱

LPWSPAccept

LPWSPAsyncSelect

LPWSPBind

LPWSPEventSelect

LPWSPSelect

LPWSPSocket