用户身份与 XUser

XBOX One 使用 XUser 对象管理与游戏交互的用户身份。每个 XUser 实例代表一个已登录到游戏的用户。每个用户由 XUserHandle 表示。游戏可以使用 XUserHandle 完成以下操作。

• 查询 XBOX 服务登录状态。
• 获取用户的 gamertag(玩家代号)。
• 获取用户的玩家头像。
• 确定用户的年龄组。
• 确定用户被允许进行实时通信或参与多人会话的权限。
• 获取已认证的令牌。

​

XUser 标识符

与给定的 XUser 相关联的有两种不同的标识符:本地 ID 和 XBOX 服务 ID(XUID)。 本地 ID 是在游戏会话内伴随用户整个生命周期的标识符。在游戏派生的任何进程之间使用本地 ID,或者在游戏调用 XLaunchNewGame 时使用。但是,不要使用
本地 ID 跨游戏会话标识用户。 要获取用户的本地 ID,请使用 XUserGetLocalId 函数。 Xbox 服务 ID(XUID) 是与 XBOX 服务通信或调用游戏可调用 UI(TCUI)时必须使用的标识符。要获取用户的 XUID,请使用 XUserGetId 函数。获取 XUID 可能需要用户同意。如果需要该同意但未被授予,则 XUserGetId 会返回 E_GAMEUSER_RESOLVE_USER_ISSUE_REQUIRED。要解决此问题并收集同意,游戏应调用 XUserResolveIssueWithUiAsync。

​

XUser 状态

用户可以处于以下三种状态之一:已登录 XBOX 服务、正在从 XBOX 服务注销,或已完全注销。游戏可以使用 XUserGetState 函数查询指定用户的此状态。游戏还可以使用 XUserRegisterForChangeEvent 函数注册变更通知。 不要根据 XUser 状态判断网络连接。如果 XUserState 为 SignedIn,则表明该用户在某个时间点已通过 XBOX 服务的认证,可以被视为活动用户。然而,网络可能并未连接。

​

向游戏添加或移除用户

与 XBOX One ERA 的模型不同,游戏只能与其通过调用 XUserAddAsync 函数请求的用户进行交互。例如,假设主机上有两个用户已登录:用户 A 和用户 B。

1. 有人启动游戏。在此场景中,是谁启动的并不重要。
2. 游戏使用 XUserRegisterForChangeEvent 注册用户状态变化。
3. 游戏调用 XUserAddAsync,用户 A 登录到游戏。
4. 游戏现在拥有一个代表用户 A 的 XUserHandle。
5. 从指南中,用户 B 选择注销。
6. 游戏不会收到登录状态变化事件。游戏从未知晓用户 B。
7. 从指南中,用户 A 选择注销。
8. 游戏首先收到一个变化事件,表明用户 A 正在注销;最终收到另一个不同的事件,表明用户 A 现在已注销。

尽管游戏能够向其游戏中添加用户,但只有几种方式可以通过下列方法之一移除用户。

• 游戏可以使用 XUserCloseHandle 函数关闭所有代表该用户的句柄。
• 用户使用指南从主机注销。
• 用户登录到另一台设备。

​

用户类型

XBOX One 支持两种用户类型:XBOX 玩家和访客。 Xbox 玩家 在系统上作为用户具有全部功能。他们最初是通过在 Account Picker(系统提供的用于登录用户的 UI)中添加新账户创建的。XBOX 玩家会一直保留在主机上,直到通过 Settings 应用显式移除为止。 Xbox 访客 在主机上仅有一个会话。当他们在 Account Picker 中选择以访客身份游玩,并由另一位已登录的 XBOX 玩家做出赞助时被创建。访客会一直保留,直到他们注销、赞助的 XBOX 玩家注销,或主机关闭为止。 希望允许访客的游戏在调用 XUserAddAsync 时必须指定 AllowGuest 选项。

​

添加用户的模式

游戏必须始终尝试建立初始用户。有两种主要方式来实现这一点。

​

选项 1:在不显示 UI 的情况下尽快确定用户

1. 使用 AddDefaultUserSilently 调用 XUserAddAsync。此函数会在不显示任何 UI 的情况下尝试确定是谁启动了游戏。
2. 对 XUserAddAsync 的调用可能会以 E\_GAMEUSER\_NO\_DEFAULT\_USER 失败。如果发生这种情况,则说明游戏首次启动时没有用户登录。要建立初始用户,游戏需要在不使用 AddDefaultUserSilently 标志的情况下调用 XUserAddAsync。与“静默”选项不同,此调用会确保所有同意相关的问题被完全解决,并且如果调用成功,则用户已登录到 XBOX 服务。游戏可以为该用户创建 XBOX 上下文。

​

选项 2:允许显示 UI 的情况下确定用户

使用 AddDefaultUserAllowingUI 调用 XUserAddAsync。就像前一个选项(“静默”)一样,此函数会尝试确定是谁启动了游戏。与前一个选项不同,如果无法确定默认用户,它会显示 UI 以允许玩家登录或选择自己。如果 XUserAddResult 成功,则游戏有一个完全登录到 XBOX 服务的用户,游戏可以为该用户创建 XBOX 上下文。 有关演示这些步骤的示例代码,请参见 如何:登录用户的最佳实践。

​

管理 XUserHandle

每个 XUserHandle 代表一个用户。然而,可能有多个此类句柄同时代表同一个用户。游戏应遵循以下基本模式。

1. 维护一个 XUserHandle 实例的集合,代表游戏关心的用户集合。
2. 通过调用 XUserRegisterForChangeEvent 注册 XUser 状态变化。当你看到某个用户正在被注销时,更新你的用户集合。
3. 当你从 XUserAddAsync 获得新的 XUserHandle 时,请务必检查它是否代表一个新用户。你可以直接使用 XUserCompare 比较句柄。你也可以通过调用 XUserGetLocalId 获得的本地 ID 进行比较。
4. 如果你有多个代表同一用户的 XUserHandle 实例,请使用 XUserCloseHandle 移除多余的实例。

本地 ID 是在游戏会话内伴随用户整个生命周期的标识符。在游戏派生的任何进程之间使用本地 ID,或者在游戏调用 XLaunchNewGame 时使用。但是,不要使用本地 ID 跨游戏会话标识用户。