PartyManager::CreateNewNetwork

项目
02/09/2024

对创建新网络的异步尝试进行排队。

语法

PartyError CreateNewNetwork(  
    const PartyLocalUser* localUser,  
    const PartyNetworkConfiguration* networkConfiguration,  
    uint32_t regionCount,  
    const PartyRegion* regions,  
    const PartyInvitationConfiguration* initialInvitationConfiguration,  
    void* asyncIdentifier,  
    PartyNetworkDescriptor* networkDescriptor,  
    char* appliedInitialInvitationIdentifier  
)

参数

localUserPartyLocalUser*

网络创建和中继分配归属于的本地用户。

networkConfigurationPartyNetworkConfiguration*

网络配置属性，例如最大用户计数和最大设备计数。这些属性在网络生存期内持续，无法更改。

regionCount uint32_t

通过 regions指定的首选区域数组中提供的区域数。如果为零，则库使用在其中配置游戏的所有区域，按此设备的最低往返延迟排序。

regionsPartyRegion*

应在其中创建网络的首选区域的数组。在第一个可用区域中创建网络。

initialInvitationConfigurationPartyInvitationConfiguration*
可选

初始邀请的可选指定配置。

如果此值为 null，则使用默认配置值。默认情况下，PlayFab Party 为游戏生成唯一的邀请标识符，可撤销性为将 PartyInvitationRevocability::Anyone，PlayFab 实体 ID 列表将为空，允许任何用户使用邀请加入。

如果提供了配置，则游戏可以选择指定配置上的标识符。如果标识符为 nullptr 或空字符串，则 PlayFab Party 库将为游戏生成一个标识符，该标识符保证与 PlayFab Party 库将在所有设备上针对此网络上的所有未来邀请生成的所有标识符不同。游戏可以通过在配置中提供非 null 的非空值来指定自己的标识符。如果游戏指定标识符，则游戏有责任确保此标识符不会与通过任何设备上的 PartyNetwork::CreateInvitation() 在此网络上创建的未来邀请的标识符冲突。

如果提供了配置，则其可撤销性必须为 PartyInvitationRevocability：：Anyone。

如果提供了配置并且 PlayFab 实体 ID 列表为空，则允许所有用户使用新邀请加入。

asyncIdentifier void*
可选

一个可选应用定义的指针大小的上下文值，可用于将完成状态更改与此调用关联起来。

networkDescriptorPartyNetworkDescriptor*
可选输出

可选的输出网络描述符，可用于通过 ConnectToNetwork（）立即将本地设备的连接排队到新创建的网络。

appliedInitialInvitationIdentifier char*
大小 c_maxInvitationIdentifierStringLength+1 的可选输出字符串缓冲区

初始邀请的标识符写入到的可选输出缓冲区。如果为 initialInvitationConfiguration 提供了非 null、非空标识符，则此缓冲区将填充相同的标识符。如果未提供初始配置或提供的配置具有空或 null 标识符，PlayFab Party 库将生成一个，并将其返回到此缓冲区中的游戏。

返回值

PartyError

如果创建新网络的异步操作已开始，则为 c_partyErrorSuccess，否则为错误代码。如果此方法失败，则不会生成任何相关的状态更改。可通过 GetErrorMessage() 检索错误代码的可读形式。

备注

PartyNetwork 是一组通过客户端服务器拓扑连接到透明云中继服务器的设备。网络中的每个设备都包含与网络关联的终结点集合;定向消息可以从本地设备上的终结点发送到任何终结点集，也可以广播到所有终结点。此方法将尝试分配中继的尝试排入队列，从而代表由 localUser 表示但不将本地设备连接到网络的用户创建新网络。

如果在中继创建后的 10 分钟内没有设备连接到网络，它将关闭。网络无限期保持活动状态，同时至少连接一台设备，如果需要，将迁移到新的中继。如果没有设备连接到网络，中继变为非活动状态并在一分钟的非活动状态后关闭。

本地设备可以通过立即将 networkDescriptor 传递到 ConnectToNetwork（），对连接到新网络的尝试进行排队。将此描述符与 SerializeNetworkDescriptor() 配合使用会导致失败，因为描述符未包含足够的信息，远程设备无法连接到网络。提供 PartyCreateNewNetworkCompletedStateChange 并指示成功时，网络描述符将更改并变为可序列化。更新后的网络描述符作为 PartyCreateNewNetworkCompletedStateChange 中的字段提供。使用 PartyNetwork::GetNetworkDescriptor() 连接到网络后，还可以检索描述符。

网络是使用在 regions中指定的顺序在第一个可用区域中创建的。如果指定的区域都不可用，则不会创建网络。将 regionCount 默认值指定为 0 以使用配置游戏的所有区域，按此设备的最低延迟排序，这是 GetRegions() 返回的相同数组。

默认区域选择仅包括来自此设备的延迟度量，而不包括来自任何其他设备的延迟度量。具有一组预先已知会话参与者的游戏在创建网络之前从所有设备收集度量，并构造按整个组的最低聚合延迟排序的新 regions 数组。

对于支持加入正在进行的游戏，连接参与者组具有最佳整体延迟的区域可能会随着设备加入和离开而发生变化。游戏应利用参与方对同时连接到多个网络的支持，将设备无缝迁移到在具有更佳组聚合延迟的区域中创建的网络。游戏可以通过原始参与方网络上的消息或上传到外部名单服务的信息收集区域延迟度量，在聚合延迟较低的区域中创建新的群网络，并指示所有设备连接到更有利的网络，并与原始网络断开连接。

如果使用 PartyOption::RegionUpdateConfiguration 选项来配置 PartyRegionUpdateMode::D eferred的更新模式，则检索可用区域集并测量它们的连接质量可能尚未启动，或者上次更新可能已超过配置的刷新间隔期限。为 CreateNewNetwork() 的 regionCount 指定 0 可确保任何延迟的区域更新已启动，并且在此调用 PartyCreateNewNetworkCompletedStateChange 完成之前，会提供其关联 PartyRegionsChangedStateChange。

新创建的网络的初始邀请不归任何用户所有。因此，调用 PartyInvitation::GetCreatorEntityId() 为初始邀请返回 nullptr。初始邀请还会在网络的生存期内一直保留，直到通过 PartyNetwork::RevokeInvitation() 专门撤销。本地用户可以通过 PartyNetwork::CreateInvitation() 为网络创建新的邀请，这些邀请通过身份验证进入网络，并且这些邀请将持续存在，直到他们创建的本地用户从网络中删除。用户通过 PartyNetwork：：AuthenticateLocalUser（）通过提供成功创建的邀请的标识符加入网络，但尚未撤消，并允许他们加入。

失败时重试

当 CreateNewNetwork（）异步失败时， StartProcessingStateChanges 将提供 PartyCreateNewNetworkCompletedStateChange 指示结果。可能会在延迟后重试该操作，具体取决于提供的 PartyStateChangeResult。

结果	重试行为
InternetConnectivityError	以不小于 10 秒的小延迟重试。对于应用，可能更适合立即向用户显示错误，而不是自动重试。
PartyServiceError	使用指数退避重试。从最小延迟（不小于 10 秒）开始，每次重试时将延迟增加一倍。
NoServersAvailable	使用指数退避重试。从最小延迟（不小于 30 秒）开始，每次重试时将延迟增加一倍。对于应用，可能更适合立即向用户显示错误，而不是自动重试。
UserNotAuthorized	此结果可能意味着用户的实体令牌无效、已过期或用户因其他原因未获得授权。请重试不超过一次，并且仅在获取用户的新实体令牌并调用 PartyLocalUser：：UpdateEntityToken（）。
UserCreateNetworkThrottled	不要自动重试。而是向用户显示一条消息，并等待用户发起另一次尝试。
FailedToBindToLocalUdpSocket	此结果表示库无法绑定到在 PartyOption::LocalUdpSocketBindAddress 选项中指定的本地 UDP 套接字。游戏必须清理其库的实例，将 PartyOption::LocalUdpSocketBindAddress 选项更新为有效的可用绑定地址，并重新初始化库。

要求

标题： Party.h

另请参阅

PartyManager
PartyCreateNewNetworkCompletedStateChange
PartyManager::ConnectToNetwork
PartyNetwork::AuthenticateLocalUser
PartyNetwork::LeaveNetwork
PartyNetwork::RevokeInvitation
PartyNetwork::CreateInvitation
PartyInvitation
PartyInvitationConfiguration

通过

PartyManager::CreateNewNetwork

语法

参数

返回值

备注

失败时重试

要求

另请参阅

其他资源