> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 慣用本機 UDP 多人遊戲連接埠網路 API

> 慣用本機使用者資料包通訊協定 (UDP) 多人遊戲連接埠網路 API

使用本主題了解如何使用慣用本機使用者資料包通訊協定 (UDP) 多人遊戲連接埠 API 來提升多人遊戲的可靠性。所有世代的 XBOX 主機都允許您使用 *UDP 3074*。這是公開註冊、用於多人遊戲網路流量的知名連接埠。Microsoft Game Development Kit (GDK) 遊戲也不例外，可以使用慣用本機 UDP 多人遊戲連接埠網路 API 來存取此特殊連接埠。

慣用本機 UDP 多人遊戲連接埠是在後續 [通訊端繫結](https://learn.microsoft.com/windows/desktop/api/winsock/nf-winsock-bind)作業中使用的本機連接埠，而不是遠端裝置可能用來連線到本機裝置的公用連接埠。前者只對 UDP 流量有意義，而對傳輸控制通訊協定 (TCP) 和 HTTP 流量則沒有意義，因為它專門針對多人遊戲、即時遊戲網路流量。

過去，此連接埠僅限於 UDP 3074。不過，近年來已引進後援邏輯，以提高此連接埠的可靠性。此外，使用者也能夠手動設定連接埠，以搭配他們自己獨特的網路設定運作。這就是為什麼在 Microsoft Game Development Kit (GDK) 遊戲中將 UDP 3074 硬式編碼已不再安全。Microsoft Game Development Kit (GDK) 遊戲應改為動態查詢目前設定的連接埠。

有三種方式可以擷取慣用本機 UDP 多人遊戲連接埠。

* **封鎖：** [XNetworkingQueryPreferredLocalUdpMultiplayerPort](/zh-TW/reference/networking/xnetworking/functions/xnetworkingquerypreferredlocaludpmultiplayerport)
* **非同步：** [XNetworkingQueryPreferredLocalUdpMultiplayerPortAsync](/zh-TW/reference/networking/xnetworking/functions/xnetworkingquerypreferredlocaludpmultiplayerportasync)
* **以通知為基礎：** [XNetworkingRegisterPreferredLocalUdpMultiplayerPortChanged](/zh-TW/reference/networking/xnetworking/functions/xnetworkingregisterpreferredlocaludpmultiplayerportchanged)

這三種變體都提供相同的基本功能。Microsoft Game Development Kit (GDK) 遊戲可以依照其特定需求和使用案例，呼叫其中任何一種 (或任何組合)。

強烈建議所有 Microsoft Game Development Kit (GDK) 遊戲將慣用連接埠用於其主要遊戲流量。此連接埠已針對點對點網路拓撲和用戶端/伺服器網路拓撲進行最佳化。Microsoft Game Development Kit (GDK) 平台會確保此特定連接埠最有可能在每位使用者的特定網路環境中運作。使用此特定連接埠可充分利用平台的客戶支援和診斷流程、提高標準化網路位址轉譯 (NAT) 相容性、提供標準化的 UPnP™ 認證裝置功能，並將封包識別為對服務品質 (QoS) 路由器和 ISP 演算法具有即時敏感性。

此慣用連接埠與依賴點對點網路拓撲的遊戲特別相關。它是唯一允許輸入 UDP 封包在不執行防火牆穿透的情況下通過防火牆的連接埠。在 Microsoft Game Development Kit (GDK) 中依賴點對點網路拓撲的遊戲，仍應提供自己的公用 IP 位址和連接埠探索，以及為具有中等或嚴格 NAT 類型的用戶端提供 NAT 穿透解決方案。慣用連接埠可提高這些技術的成功率，但無法取代這些技術。

使用用戶端/伺服器網路拓撲的遊戲也能從使用此連接埠中獲益。對於醫院、飯店和大學宿舍中常見的受限制入口網站和其他以來源為基礎的篩選方法，疑難排解、UPnP™ 和封包識別仍然相關。

慣用連接埠應與任何其他連接埠同等看待。它應與 [Windows Sockets 2 (Winsock)](https://learn.microsoft.com/windows/desktop/WinSock/windows-sockets-start-page-2) API 搭配使用。遊戲應在此連接埠上同時繫結 IPv4 和 IPv6，或使用雙堆疊通訊端，並且應繫結至 `INADDR_ANY`/`in6addr_any` 位址。

## 處理通訊端失敗

無法保證傳回的連接埠可用來與特定伺服器或對等裝置建立成功的通訊端連線。應執行一般的遊戲重試和後援邏輯。每當通訊端關閉並重新開啟時，遊戲都應再次查詢最新的慣用本機 UDP 多人遊戲連接埠，因為連接埠可能會隨時間變更。

## 網路初始化

`XNetworkingQueryPreferredLocalUdpMultiplayerPort` API 的所有三種變體 (封鎖、非同步和以通知為基礎) 都會在遊戲啟動和繼續時封鎖或延遲完成/通知，直到網路初始化為止。您可以依照[偵測網路初始化狀態](/zh-TW/build/console-features/networking/initialization-connectivity-networking)概觀另外等待網路初始化，也可以呼叫這些 API 並等待它們傳回。

<a id="SuspendResume" />

## 暫停與繼續

就像任何其他通訊端一樣，繫結至慣用本機 UDP 多人遊戲連接埠的通訊端應在暫停時關閉，並在繼續時等待網路初始化後重新建立。您應該透過 `RegisterAppStateChangeNotification` 註冊暫停和繼續事件。繼續時，您應假設慣用本機 UDP 多人遊戲連接埠已變更，並接聽慣用本機 UDP 多人遊戲連接埠的變更，或在建立新的通訊端時重新查詢。如需 WinSock 暫停和繼續處理的詳細資訊，請參閱 [Winsock 中的暫停與繼續](/zh-TW/build/console-features/networking/game-mesh/winsock-intro-networking#SuspendResume)。

## 慣用本機 UDP 多人遊戲連接埠的變更

遊戲可以使用 [XNetworkingRegisterPreferredLocalUdpMultiplayerPortChanged](/zh-TW/reference/networking/xnetworking/functions/xnetworkingregisterpreferredlocaludpmultiplayerportchanged) API 接聽慣用本機 UDP 多人遊戲連接埠的變更。

系統會盡一切努力確保慣用本機 UDP 多人遊戲連接埠在遊戲執行期間不會變更。不過，在某些無法避免的情況下，由於使用者的外部網路狀況變更，連接埠會變更並使任何現有的通訊端流量失效。當[網路連線層級](/zh-TW/build/console-features/networking/initialization-connectivity-networking)變更時，或在遊戲的暫停/繼續週期中，連接埠特別有可能變更。

當慣用本機 UDP 多人遊戲連接埠變更時，來自未來對等裝置的其他輸入連線可能會在任何先前的慣用連接埠上遭到封鎖。這可能不會在通訊端層造成失敗。不過，遊戲最終可能會停止在繫結至任何先前慣用連接埠的任何通訊端上接收封包。

與現有對等裝置之間傳送的封包可能會繼續運作。慣用本機 UDP 多人遊戲連接埠變更的通知，對任何進行中的遊戲工作階段可能並不致命。

發生變更通知時，遊戲應移轉至繫結在新慣用連接埠上的新通訊端。此移轉應盡早進行，且不中斷任何現有的遊戲玩法。若要偵測連線中斷並重試通訊端連線，遊戲應一律使用最新的慣用連接埠。

### 測試慣用本機 UDP 多人遊戲連接埠的變更

使用下列步驟變更慣用本機 UDP 多人遊戲連接埠。

1. 在遊戲執行時，開啟 **XBOX 指南**。前往 **設定** 應用程式。
2. 在 **一般** 索引標籤上，選取 **網路設定**。
3. 選取 **進階設定**，然後選取 **替代連接埠選取**。
4. 將連接埠選取設定為 **手動**。若要選取連接埠，請使用下拉式功能表。
5. 連接埠選取會立即生效，並對您的遊戲發出對應的通知。
6. 完成測試後，將連接埠選取設定回 **自動**，讓連接埠行為恢復為預設值。

<Note>
  在設定應用程式中時，您的遊戲處於受限狀態但仍在執行，即使您的遊戲不可見，也會立即收到連接埠變更通知。如果您讓設定應用程式保持開啟超過 10 分鐘而未切換回您的遊戲，您的遊戲就會暫停。
</Note>

## 安全性

繫結至慣用本機 UDP 多人遊戲連接埠的通訊端，其行為與任何其他通訊端相同。特別是，該通訊端不會提供任何額外的安全性。遊戲應依照通訊安全性最佳做法的規定，在繫結至慣用本機 UDP 多人遊戲連接埠的通訊端之上，使用自己的安全通訊協定。如需詳細資訊，請參閱[通訊安全性概觀 (NDA 主題)](/zh-TW/build/game-principles/security/communication-security-overview)。

## 點對點

慣用本機 UDP 多人遊戲連接埠提供可用來建置點對點網狀架構的最佳已知連接埠。它已經以最佳方式設定，允許輸入連線通過使用者的 NAT 層。不過，執行 NAT 周遊是遊戲的責任，包括下列各項。

* 偵測 NAT 類型
* 偵測並交換裝置的公用 IP 位址和連接埠
* NAT 穿透和周遊

## Azure PlayFab Party

在內部，[PlayFab Party](/zh-TW/build/console-features/networking/game-mesh/playfab-party-intro-networking) 預設會使用慣用本機 UDP 多人遊戲連接埠。這可透過 PlayFab Party API 設定。除非變更 PlayFab Party 連接埠，否則遊戲不應直接繫結至慣用本機 UDP 多人遊戲連接埠。

## 使用範例

下列範例示範如何將雙堆疊通訊端繫結至慣用本機 UDP 多人遊戲連接埠。為求簡潔，此範例使用封鎖的 [XNetworkingQueryPreferredLocalUdpMultiplayerPort](/zh-TW/reference/networking/xnetworking/functions/xnetworkingquerypreferredlocaludpmultiplayerport) 呼叫，並假設遊戲先前已等待網路就緒，且已呼叫 [WSAStartup](https://learn.microsoft.com/windows/desktop/api/winsock/nf-winsock-wsastartup)。

```cpp theme={null}
HRESULT
CreateAndBindMultiplayerSocket(
    _Out_ SOCKET* multiplayerSocket
    )
{
    HRESULT hr;
    SOCKET resultSocket = INVALID_SOCKET;

    uint16_t port;
    hr = XNetworkingQueryPreferredLocalUdpMultiplayerPort(&port);
    if (FAILED(hr))
    {
        goto Failure;
    }

    resultSocket = socket(AF_INET6, SOCK_DGRAM, IPPROTO_UDP);
    if (resultSocket == INVALID_SOCKET)
    {
        hr = HRESULT_FROM_WIN32(WSAGetLastError());
        goto Failure;
    }

    // Enable both IPv4 and IPv6 on this socket.
    int v6only = 0;
    if (setsockopt(resultSocket, IPPROTO_IPV6, IPV6_V6ONLY, (char*)&v6only, sizeof(v6only)) == SOCKET_ERROR)
    {
        hr = HRESULT_FROM_WIN32(WSAGetLastError());
        goto Failure;
    }

    sockaddr_in6 sa;
    ZeroMemory(&sa, sizeof(sa));
    sa.sin6_family = AF_INET6;
    sa.sin6_port = htons(port);
    sa.sin6_addr = in6addr_any;
    if (bind(resultSocket, (const sockaddr*)&sa, sizeof(sa)) == SOCKET_ERROR)
    {
        hr = HRESULT_FROM_WIN32(WSAGetLastError());
        goto Failure;
    }

    *multiplayerSocket = resultSocket;

Exit:

    return hr;

Failure:

    if (resultSocket != INVALID_SOCKET)
    {
        (void)closesocket(resultSocket);
    }

    goto Exit;
}
```

## 參考 API 文件

* [Xnetworking (API 內容)](/zh-TW/reference/networking/xnetworking/xnetworking_members)
  * 函式
    * [XNetworkingQueryPreferredLocalUdpMultiplayerPort](/zh-TW/reference/networking/xnetworking/functions/xnetworkingquerypreferredlocaludpmultiplayerport)
    * [XNetworkingQueryPreferredLocalUdpMultiplayerPortAsync](/zh-TW/reference/networking/xnetworking/functions/xnetworkingquerypreferredlocaludpmultiplayerportasync)
    * [XNetworkingRegisterPreferredLocalUdpMultiplayerPortChanged](/zh-TW/reference/networking/xnetworking/functions/xnetworkingregisterpreferredlocaludpmultiplayerportchanged)

## 另請參閱

[慣用本機 UDP 多人遊戲連接埠 API 參考 (XNetworking)](/zh-TW/reference/networking/xnetworking/xnetworking_members)

[Windows Sockets 2 (Winsock)](https://learn.microsoft.com/windows/desktop/WinSock/windows-sockets-start-page-2)

[通訊安全性概觀 (NDA 主題)](/zh-TW/build/game-principles/security/communication-security-overview)


## Related topics

- [XBOX 遊戲的 XBOX 需求](/zh-TW/publishing/certification/xbox-requirements.md)
- [XR-045 XBOX 網路與帳戶權限](/zh-TW/publishing/certification/xr/xr-045.md)
- [XBOX 主機遊戲的認證測試 XBOX 需求](/zh-TW/publishing/certification/console-cert-tested-requirements.md)
- [認證主機 BVT 指南](/zh-TW/publishing/game-publishing/concepts/certification/certification-console-bvt-guide.md)
- [GDK 範例](/zh-TW/home/setup-install/samples.md)