XUserAddOptions
指定用于添加用户的选项。
语法
enum class XUserAddOptions : uint32_t
{
None = 0x00,
AddDefaultUserSilently = 0x01,
AllowGuests = 0x02,
AddDefaultUserAllowingUI = 0x04,
}
常量
| 常量 | 说明 |
|---|---|
| None | 无选项。 |
| AddDefaultUserSilently | 获取启动游戏的用户，无需弹出任何 UI。 |
| AllowGuests | 来宾将包含在用户选择器 UI 中。 |
| AddDefaultUserAllowingUI | 尝试无提示获取启动游戏的初始用户。 如果系统可以在不弹出任何 UI 的情况下获取该用户，则将尝试执行该操作。 如果该用户需要同意或解决帐户问题，则将显示 UI 来解决问题。 |
备注
在某些极端情况下，开发者应该知道是否在将 options 设置为 XUserAddOptions::AddDefaultUserSilently 的情况下重复调用 XUserAddAsync：
- 如果反复调用此操作，并且我们知道启动游戏的默认用户，它将返回该用户。
- 如果先前已知的默认用户已注销，并且只有一个用户登录到设备，则会将该用户标记为新的“默认”用户并返回该用户。
- 如果先前已知的默认用户已注销，并且有多个用户登录到设备，它将返回 E_GAMEUSER_NO_DEFAULT_USER。
- 在开发人员启动时，将成为默认用户的用户是自动登录用户，可通过将该用户设置为 DevHome 中的自动登录用户或使用 xbconfig（NDA 主题）要求授权DefaultUser 来指定。
如果默认用户不可用，XUserAddResult 将返回 E_GAMEUSER_NO_DEFAULT_USER。 必须在 options 未设置为 XUserAddOptions::AddDefaultUserSilently 的情况下调用 XUserAddAsync。
在某些极端情况下，开发者应该知道是否在将 options 设置为 XUserAddOptions::AddDefaultUserAllowingUI 的情况下重复调用 XUserAddAsync。 这些与无提示 UI 情况非常相似（但不完全相同）：
- 如果反复调用此操作，并且我们知道启动游戏的默认用户，它将返回该用户。
- 如果先前已知的默认用户已注销，并且只有一个用户登录到设备，则会将该用户标记为新的“默认”用户并返回该用户。
- 如果最初启动游戏的用户注销，并且用户数为 0 或大于 1，则系统将显示 UI 来获取用户，然后将该用户设置为默认用户。
在 XUserAddAsync 中，不能将 XUserAddOptions::AllowGuests 与 XUserAddOptions::AddDefaultUserSilently 一起使用。 访客不能是默认用户。
您可以使用 XUserAddOptions::AllowGuests，即使当前平台不支持访客。
下面的示例演示如何将用户异步添加到游戏会话。
HRESULT AddUserComplete(XAsyncBlock* ab)
{
unique_user_handle user;
RETURN_IF_FAILED(XUserAddResult(ab, &user));
XUserLocalId userLocalId;
XUserGetLocalId(user.get(), &userLocalId);
auto iter = std::find_if(
_users.begin(),
_users.end(),
[&userLocalId](const User& candidate)
{
XUserLocalId candidateUserLocalId;
XUserGetLocalId(candidate.Handle(), &candidateUserLocalId);
return candidateUserLocalId == userLocalId;
});
// User already known
if (iter != _users.end())
{
appLog.AddLog("User already in list\n");
return S_OK;
}
try
{
_users.emplace_back(user.get());
_users.back().LoadGamerPicAsync(_queue);
}
CATCH_RETURN();
return S_OK;
}
HRESULT AddUser(bool allowGuests, bool silent)
{
auto asyncBlock = std::make_unique<XAsyncBlock>();
ZeroMemory(asyncBlock.get(), sizeof(*asyncBlock));
asyncBlock->queue = _queue;
asyncBlock->context = this;
asyncBlock->callback = [](XAsyncBlock* ab)
{
auto asyncBlock = std::unique_ptr<XAsyncBlock>(ab);
LOG_IF_FAILED(static_cast<UserWindow*>(ab->context)->AddUserComplete(ab));
};
XUserAddOptions options = XUserAddOptions::None;
if (allowGuests)
{
WI_SET_FLAG(options, XUserAddOptions::AllowGuests);
}
if (silent)
{
WI_SET_FLAG(options, XUserAddOptions::AddDefaultUserSilently);
}
if (SUCCEEDED_LOG(XUserAddAsync(
options,
asyncBlock.get())))
{
// The call succeeded, so release the std::unique_ptr ownership of XAsyncBlock* since the callback will take over ownership.
// If the call fails, the std::unique_ptr will keep ownership and delete the XAsyncBlock*
asyncBlock.release();
}
return S_OK;
}
要求
头文件：XUser.h
支持平台：Windows、Xbox One 系列主机和 Xbox Series 主机