> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XUserAddResult

> XUserAddResult

# XUserAddResult

擷取 [XUserAddAsync](/zh-TW/reference/system/xuser/functions/xuseraddasync) 所建立之使用者的控制代碼。

## 語法

```cpp theme={null}
HRESULT XUserAddResult(  
         XAsyncBlock* async,  
         XUserHandle* newUser  
)  
```

### 參數

*async*   \_Inout\_\
類型：[XAsyncBlock\*](/zh-TW/reference/system/xasync/structs/xasyncblock)

傳送給 [XUserAddAsync](/zh-TW/reference/system/xuser/functions/xuseraddasync) 的非同步區塊。

*newUser*   \_Out\_\
類型：XUserHandle\*

包含新使用者的控制代碼。

### 傳回值

類型：HRESULT

HRESULT 成功或錯誤碼。

| 傳回碼 | 描述 |
| - | - |
| S\_OK | 作業成功。 |
| E\_GAMEUSER\_NO\_DEFAULT\_USER | 沒有可用的預設使用者。必須在不使用 [XUserAddOptions::AddDefaultUserSilently](/zh-TW/reference/system/xuser/enums/xuseraddoptions) 的情況下呼叫 [XUserAddAsync](/zh-TW/reference/system/xuser/functions/xuseraddasync)。 |
| E\_GAMEUSER\_RESOLVE\_USER\_ISSUE\_REQUIRED | 使用者必須使用 UI 來解決問題。請呼叫 [XUserResolveIssueWithUiAsync](/zh-TW/reference/system/xuser/functions/xuserresolveissuewithuiasync) 向使用者顯示 UI。 |
| E\_ABORT | 使用者已取消作業。 |

## 備註

**XUserAddAsync** 會啟動非同步作業，將使用者新增至遊戲。請使用
[XUserAddResult](/zh-TW/reference/system/xuser/functions/xuseraddresult) 來擷取作業的結果。

除非您將
[XUserAddOptions::AddDefaultUserSilently](/zh-TW/reference/system/xuser/enums/xuseraddoptions)
傳遞給 *options* 參數，否則 **XUserAddAsync** 一律會顯示帳戶選擇器 UI。

如果您使用 [XUserAddOptions::AddDefaultUserSilently](/zh-TW/reference/system/xuser/enums/xuseraddoptions)，**XUserAddAsync** 不會顯示
UI。**XUserAddOptions::AddDefaultUserSilently** 傳回的使用者會持續傳回，直到該使用者
登出為止。如果沒有可用的預設使用者，[XUserAddResult](/zh-TW/reference/system/xuser/functions/xuseraddresult) 會傳回
**E\_GAMEUSER\_NO\_DEFAULT\_USER**。這表示您必須在不使用
**XUserAddOptions::AddDefaultUserSilently** 的情況下呼叫 **XUserAddAsync** 來選取使用者。

如果使用者遭到 XBOX Live 封鎖，遊戲將無法取得該使用者的 XUserHandle。
如果使用了 **XUserAddOptions::AddDefaultUserSilently**，且遊戲是由遭封鎖的使用者啟動，
**XUserAddResult** 會傳回 E\_GAMEUSER\_NO\_DEFAULT\_USER。否則，如果顯示了 UI，則必須由未遭封鎖的
使用者登入，或使用者必須取消 UI，此時 **XUserAddResult** 會
傳回 E\_ABORT。

您無法將 [XUserAddOptions::AllowGuests](/zh-TW/reference/system/xuser/enums/xuseraddoptions) 與 **XUserAddOptions::AddDefaultUserSilently** 一起使用。來賓
不能是預設使用者。無論目前的平台是否支援來賓，您都可以放心使用
**XUserAddOptions::AllowGuests**。

您從 **XUsers** API 擷取的每個 **XUserHandle** 控制代碼，都必須呼叫
[XUserCloseHandle](/zh-TW/reference/system/xuser/functions/xuserclosehandle) 關閉一次。

下列範例示範如何以非同步方式將使用者新增至遊戲工作階段。

```cpp theme={null}
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

**程式庫：** xgameruntime.lib

**支援的平台：** Windows、Steam Deck、XBOX One 系列主機和 XBOX Series 主機

## 概念文件

* [執行 Microsoft Game Development Kit (GDK) API 工作](/zh-TW/build/core-features/common/async/async-libraries/async-library-xasync-example-run-gdk-task)
* [非同步程式設計的設計目標與改進](/zh-TW/build/core-features/common/async/async-whitepaper)

## 另請參閱

[XUser](/zh-TW/reference/system/xuser/xuser_members)

[XUserAddAsync](/zh-TW/reference/system/xuser/functions/xuseraddasync)

[XUserAddOptions](/zh-TW/reference/system/xuser/enums/xuseraddoptions)

[XUserCloseHandle](/zh-TW/reference/system/xuser/functions/xuserclosehandle)


## Related topics

- [XUserAddResult](/reference/system/xuser/functions/xuseraddresult.md)
- [XUserAddOptions](/reference/system/xuser/enums/xuseraddoptions.md)
- [User identity and XUser](/build/core-features/common/user/player-identity-xuser.md)
- [Run Microsoft Game Development Kit API task example](/build/core-features/common/async/async-libraries/async-library-xasync-example-run-gdk-task.md)
- [Microsoft Game Development Kit API タスクの実行例](/ja-jp/build/core-features/common/async/async-libraries/async-library-xasync-example-run-gdk-task.md)