PartyNetwork::AuthenticateLocalUser
排队异步操作,对指定的本地用户在网络中进行身份验证。
语法
PartyError AuthenticateLocalUser(
const PartyLocalUser* localUser,
PartyString invitationIdentifier,
void* asyncIdentifier
)
参数
localUser
PartyLocalUser*
要在网络中进行身份验证的本地用户。
invitationIdentifier
PartyString
允许 localUser
在网络中进行身份验证的邀请的标识符。
asyncIdentifier
void*
可选
一个可选应用定义的指针大小的上下文值,可用于将完成状态更改与此调用关联起来。
返回值
PartyError
如果对本地用户进行身份验证的异步操作已开始,则为 c_partyErrorSuccess
,否则为错误代码。 如果此方法失败,则不会生成任何相关的状态更改。 可通过 PartyManager::GetErrorMessage() 检索错误代码的可读形式。
备注
虽然任何具有适当网络描述符的设备都可以建立与网络的连接,但无法执行任何有用的操作,并且无需先对设备上的本地用户进行身份验证,也无法收集任何有用的信息。 因此,身份验证是确保网络完整性以及参与网络的设备和用户的隐私的重要安全措施。 对用户进行身份验证是让透明云中继服务器验证用户的身份,并允许用户加入网络。
此调用启动的异步操作成功完成后,用户被视为已通过网络身份验证。 完成由 PartyAuthenticateLocalUserCompletedStateChange指示。 身份验证成功要求本地用户的 PlayFab 实体令牌有效,并与本地用户的 PlayFab 实体 ID 相关联。 身份验证成功还需要提供的邀请允许提供的本地用户加入网络。 如果所提供的用户的身份验证违反网络配置中的某个限制,身份验证将失败。 这些要求由透明云中继服务器强制执行。 如果异步操作失败,PartyAuthenticateLocalUserCompletedStateChange 将提供诊断结果和错误详细信息,并且将生成 PartyLocalUserRemovedStateChange。 由于连接到没有经过身份验证的用户的网络不是过渡期之外的有用状态,因此参与方库将自动断开长时间没有经过身份验证的用户的设备。
用户需要 invitationIdentifier
来调用此方法并在网络中进行身份验证。 最常见的情况是,另一台设备必须共享通过 PartyManager::CreateNewNetwork() 生成的初始邀请的标识符,或共享它通过 CreateInvitation()生成的邀请的标识符。
用户身份验证还确定设备身份验证。 如果至少有一个本地用户在网络中进行了身份验证,则会将设备视为已通过网络身份验证。 如果设备在网络中进行了身份验证,则它将对所有其他经过身份验证的设备可见。 如果设备已连接到网络但未通过身份验证,则不会显示远程设备、终结点或聊天控件。 同样,设备将不对连接到网络的任何其他设备可见。
调用此方法后,可以调用将异步操作加入队列但要求本地用户或本地设备在网络中进行身份验证的所有其他方法。 此类操作将排队,直到身份验证操作完成。 身份验证操作完成后,将处理排队操作。 如果身份验证操作失败,排队操作也将失败,并且其各自的完成状态更改将指示此类操作。
如果本地设备进入没有经过身份验证的用户且没有正在进行的身份验证操作的状态,则所有终结点(包括尚未完全创建的终结点)将被自动销毁。 这将由 PartyEndpointDest权限StateChange发出信号。
成功返回时,此方法会使以前由 PartyNetwork::GetLocalUsers()返回的任何数组的内存失效,因为它会将新用户同步添加到数组中。 PartyManager::StartProcessingStateChanges() 也会使数组的内存无效。
如果指定的 localUser
正在对网络进行身份验证、已在网络中进行身份验证、已通过身份验证,但在删除过程中,由于之前调用了 PartyNetwork::RemoveLocalUser(),或者设备由于上次从网络中删除经过身份验证的用户而处于未经身份验证的进程中,则此方法将失败。
失败时重试
如果与此调用完成关联的 PartyAuthenticateLocalUserCompletedStateChange 指示失败,则可能会在延迟后重试该操作。 正确的重试行为取决于状态更改中提供的 PartyStateChangeResult。
结果 | 重试行为 |
---|---|
InternetConnectivityError | 以不小于 10 秒的小延迟重试。 对于应用,可能更适合立即向用户显示错误,而不是自动重试。 |
PartyServiceError | 使用指数退避重试。 从最小延迟(不小于 10 秒)开始,每次重试时将延迟增加一倍。 |
UserNotAuthorized | 此结果可能意味着用户的实体令牌无效、已过期或用户因其他原因未获得授权。 这也可能意味着指定的邀请不再有效,或者邀请不包含此用户。 请重试不超过一次,并且仅在获取用户的新实体令牌并调用 PartyLocalUser::UpdateEntityToken()。 |
FailedToBindToLocalUdpSocket | 此结果表示库无法绑定到在 PartyOption::LocalUdpSocketBindAddress 选项中指定的本地 UDP 套接字。 游戏必须清理其库的实例,将 PartyOption::LocalUdpSocketBindAddress 选项更新为有效的可用绑定地址,并重新初始化库。 |
要求
标题: Party.h
另请参阅
PartyNetwork
PartyAuthenticateLocalUserCompletedStateChange
PartyEndpointDestroyedStateChange
PartyLocalUserRemovedStateChange
PartyNetworkConfiguration
PartyManager::CreateLocalUser
PartyNetwork::RemoveLocalUser
PartyNetwork::GetLocalUsers
PartyManager::CreateNewNetwork
PartyNetwork::CreateInvitation