通过

用户标识和 XUser

  • 项目

Xbox One 使用一个 XUser 对象管理与游戏交互的用户的标识。 每个 XUser 实例代表登录到游戏的一个用户。 每个用户由一个 XUserHandle 表示。 使用 XUserHandle，游戏可以执行以下操作。

  • 查询 Xbox 服务登录状态。
  • 提取用户的玩家代号。
  • 提取用户的玩家图片。
  • 确定用户的年龄组。
  • 确定允许用户享有哪些权限以便参与实时通信或者参与多人游戏会话。
  • 提取经过身份验证的令牌。

注意

不同的 XUserHandle 值可能指向同一个用户。 为比较两个不同的XUserHandle值是否指向不同用户，游戏可以使用 XUserCompare 函数。

XUser 标识符

对于某一给定 XUser，有两个不同的关联标识符：本地 ID 和 Xbox ID (XUID)。

本地 ID 是在游戏会话内用户的整个生命周期中与用户绑定在一起的标识符。 跨游戏生成的任何进程使用本地 ID，如果游戏调用 XLaunchNewGame，也可以使用本地 ID。 但是，请勿使用
本地 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 玩家 拥有作为系统用户的完整功能。 最初通过在帐户选取器（系统提供的用于用户登录的 UI）中添加新帐户来创建这些用户。 Xbox 玩家将一直保留在主机上，直到使用“设置”应用显式删除他们。

Xbox 来宾 在主机上有一个会话。 用户在帐户选取器中选择以访客身份玩另一个已登录 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 删除多余的实例。