Skip to main content

XUserAddAsync

异步将用户添加到游戏会话。

Syntax

Parameters

options   _In_
类型:XUserAddOptions
用于将用户添加到游戏会话的选项。 async   _Inout_
类型:XAsyncBlock*
用于轮询调用状态和检索调用结果的 XAsyncBlock

Return value

类型:HRESULT HRESULT 成功或错误代码。 有关错误代码列表,请参阅错误代码

Remarks

XUserAddAsync 启动异步操作,将用户添加到游戏。使用 XUserAddResult 检索操作结果。 除非将 XUserAddOptions::AddDefaultUserSilentlyXUserAddOptions::AddDefaultUserAllowingUI 传递给 options 参数,否则 XUserAddAsync 始终显示帐户选取器 UI。 如果使用 XUserAddOptions::AddDefaultUserSilently,则 XUserAddAsync 不显示 UI。 使用简化用户模型(NDA 主题)时,此函数存在一些注意事项:
  • 使用简化用户模型时,开发者应确保 options 设置为 XUserAddOptions::AddDefaultUserSilently
  • 在主机上,除非默认用户已经登录,否则不允许启动使用简化用户模型的松散部署游戏。
  • 在 PC 上,可以在没有用户的情况下启动使用简化用户模型的松散部署游戏;但是,当游戏调用 XUserAddAsync 时,如果没有人登录,游戏将被终止,PC Bootstrapper 将启动以帮助用户登录。只要用户完全登录到 XBOX Live,后续启动就能正常工作。
如果开发者反复调用 XUserAddAsync 并将 options 设置为 XUserAddOptions::AddDefaultUserSilently,则应了解一些边缘情况:
  • 如果反复调用此项,并且我们知道启动游戏的默认用户,它将返回相同的用户。
  • 如果先前已知的默认用户已注销,并且只有一个用户登录设备,它会将该用户标记为新的“默认”用户并返回。
  • 如果先前已知的默认用户已注销,并且有多个用户登录设备,它将返回 E_GAMEUSER_NO_DEFAULT_USER。
如果默认用户不可用,XUserAddResult 将返回 E_GAMEUSER_NO_DEFAULT_USER。必须调用 XUserAddAsync,并且 options 不设置为 XUserAddOptions::AddDefaultUserSilently 如果开发者反复调用 XUserAddAsync 并将 options 设置为 XUserAddOptions::AddDefaultUserAllowingUI,也应了解一些边缘情况。这些情况与静默 UI 情况非常相似(但不完全相同):
  • 如果反复调用此项,并且我们知道启动游戏的默认用户,它将返回相同的用户。
  • 如果先前已知的默认用户已注销,并且只有一个用户登录设备,它会将该用户标记为新的“默认”用户并返回。
  • 如果最初启动游戏的用户已注销,并且用户数为 0 或多于 1,则系统将显示 UI 以获取用户,然后将该用户设置为默认。
不能将 XUserAddOptions::AllowGuestsXUserAddOptions::AddDefaultUserSilently 一起使用。来宾不能是默认用户。无论当前平台是否支持来宾,都可以安全地使用 XUserAddOptions::AllowGuests 必须通过调用 XUserCloseHandle 仅关闭一次从 XUsers API 检索到的每个 XUserHandle 句柄。 输入设备配对是在 XUserAddAsync 成功完成后执行的。如果由于 XUserAddOptions::AddDefaultUserSilentlyXUserAddOptions::AddDefaultUserAllowingUI 选项而自动登录且无 UI,则将系统中分配给该用户的输入设备传播到标题。如果显示了登录 UI,则选定该用户的输入设备将分配给该用户。 可以通过 XUserRegisterForDeviceAssociationChanged 方法跟踪设备关联。 以下示例演示了如何异步地将用户添加到游戏会话。

Requirements

头文件: XUser.h 库: xgameruntime.lib 受支持的平台: Windows、Steam Deck、XBOX One 系列主机和 XBOX Series 主机

Conceptual documentation

See also

XUser XUserAddOptions XUserCloseHandle
最后修改于 2026年8月24日