> ## 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.

# 取得遊戲管理型成就

> 擷取玩家的遊戲管理型 XBOX Live 成就清單、逐頁瀏覽結果，以及依識別碼擷取單一成就的 XSAPI 範例程式碼。

<a id="top" />

本主題涵蓋下列內容：

* [取得成就清單](#getting-the-achievements-list)
* [取得下一頁的成就結果](#getting-the-next-page-of-achievements-results)
* [取得單一成就](#getting-a-single-achievement)

<a id="getting-the-achievements-list" />

## 取得成就清單

若要取得執行中遊戲的成就，請呼叫 [XblAchievementsGetAchievementsForTitleIdAsync](/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsgetachievementsfortitleidasync)，如下所示。

### 呼叫 XblAchievementsGetAchievementsForTitleIdAsync

**C++**

```cpp theme={null}
auto asyncBlock = std::make_unique<XAsyncBlock>();
asyncBlock->queue = queue;
asyncBlock->context = nullptr;
asyncBlock->callback = [](XAsyncBlock* asyncBlock)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ asyncBlock }; // Take over ownership of XAsyncBlock*.

    XblAchievementsResultHandle resultHandle;
    auto hr = XblAchievementsGetAchievementsForTitleIdResult(asyncBlock, &resultHandle);

    if (SUCCEEDED(hr))
    {
        const XblAchievement* achievements = nullptr;
        size_t achievementsCount = 0;
        hr = XblAchievementsResultGetAchievements(resultHandle, &achievements, &achievementsCount);

        for (size_t i = 0; i < achievementsCount; i++)
        {
            LogToScreen("Achievement %s: %s = %s", 
                achievements[i].id, 
                achievements[i].name,
                (achievements[i].progressState == XblAchievementProgressState::Achieved) ? "Achieved" : "Not achieved");
        }

        XblAchievementsResultCloseHandle(resultHandle); // When you're done with the handle, close it.
        achievements = nullptr; // Clear the array after calling XblAchievementsResultCloseHandle to the pointer to freed memory.
        // Instead, you couldn't close the handle and store it. Then, 
        // if you needed to copy the handle, call XblAchievementsResultDuplicateHandle().
    }
};

HRESULT hr = XblAchievementsGetAchievementsForTitleIdAsync(
    xboxLiveContext,
    xboxUserId,
    titleId,
    achievementType,
    unlockedOnly,
    orderBy,
    skipItems,
    maxItems,
    asyncBlock.get()
);
if (SUCCEEDED(hr))
{
    // The call succeeded, so release the std::unique_ptr ownership of XAsyncBlock* because the callback will take over ownership.
    // If the call fails, std::unique_ptr will keep ownership and delete XAsyncBlock*.
    asyncBlock.release(); 
}
```

如需詳細資訊，請參閱下列內容：

* [XAsyncBlock](/zh-TW/reference/system/xasync/structs/xasyncblock)
* [XblAchievement](/zh-TW/reference/live/xsapi-c/achievements_c/structs/xblachievement)
* [XblAchievementProgressState](/zh-TW/reference/live/xsapi-c/achievements_c/enums/xblachievementprogressstate)
* [XblAchievementsGetAchievementsForTitleIdAsync](/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsgetachievementsfortitleidasync)
* [XblAchievementsGetAchievementsForTitleIdResult](/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsgetachievementsfortitleidresult)
* [XblAchievementsResultCloseHandle](/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsresultclosehandle)
* [XblAchievementsResultDuplicateHandle](/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsresultduplicatehandle)
* [XblAchievementsResultGetAchievements](/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsresultgetachievements)

[返回本主題頂端。](#top)

<a id="getting-the-next-page-of-achievements-results" />

## 取得下一頁的成就結果

成就可能還有更多頁面。若要檢查，請呼叫 [XblAchievementsResultHasNext](/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsresulthasnext)，然後呼叫 [XblAchievementsResultGetNextAsync](/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsresultgetnextasync)。

### 呼叫 XblAchievementsResultHasNext

**Flat C API**

```cpp theme={null}
HRESULT hr = S_OK;
bool hasNext = false;
if (achievementsResult != nullptr)
{
    hr = XblAchievementsResultHasNext(achievementsResult, &hasNext);
}
```

如需詳細資訊，請參閱 [XblAchievementsResultHasNext](/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsresulthasnext)。

### 呼叫 XblAchievementsResultGetNextAsync

若要取得下一頁的成就，請呼叫 [XblAchievementsResultGetNextAsync](/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsresultgetnextasync)，如下所示。

**C++**

```cpp theme={null}
auto asyncBlock = std::make_unique<XAsyncBlock>();
asyncBlock->queue = queue;
asyncBlock->context = nullptr;
asyncBlock->callback = [](XAsyncBlock* asyncBlock)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ asyncBlock }; // Take over ownership of XAsyncBlock*.
    XblAchievementsResultHandle resultHandle;
    auto hr = XblAchievementsResultGetNextResult(asyncBlock, &resultHandle);

    if (SUCCEEDED(hr))
    {
        const XblAchievement* achievements = nullptr;
        size_t achievementsCount = 0;
        hr = XblAchievementsResultGetAchievements(resultHandle, &achievements, &achievementsCount);

        for (size_t i = 0; i < achievementsCount; i++)
        {
            LogToScreen("Achievement %s: %s = %s",
                achievements[i].id,
                achievements[i].name,
                (achievements[i].progressState == XblAchievementProgressState::Achieved) ? "Achieved" : "Not achieved");
        }

        XblAchievementsResultCloseHandle(resultHandle); // When you're done with the handle, close it.
        achievements = nullptr; // Clear the array after calling XblAchievementsResultCloseHandle to the pointer to freed memory.
    }
};

HRESULT hr = XblAchievementsResultGetNextAsync(
    achievementsResult,
    maxItems,
    asyncBlock.get()
);
if (SUCCEEDED(hr))
{
    // The call succeeded, so release the std::unique_ptr ownership of XAsyncBlock* because the callback will take over ownership.
    // If the call fails, std::unique_ptr will keep ownership and delete XAsyncBlock*.
    asyncBlock.release();
}
```

如需詳細資訊，請參閱下列內容：

* [XAsyncBlock](/zh-TW/reference/system/xasync/structs/xasyncblock)
* [XblAchievement](/zh-TW/reference/live/xsapi-c/achievements_c/structs/xblachievement)
* [XblAchievementProgressState](/zh-TW/reference/live/xsapi-c/achievements_c/enums/xblachievementprogressstate)
* [XblAchievementsResultCloseHandle](/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsresultclosehandle)
* [XblAchievementsResultGetAchievements](/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsresultgetachievements)
* [XblAchievementsResultGetNextAsync](/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsresultgetnextasync)
* [XblAchievementsResultGetNextResult](/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsresultgetnextresult)

[返回本主題頂端。](#top)

<a id="getting-a-single-achievement" />

## 取得單一成就

若要取得單一成就，請呼叫 [XblAchievementsGetAchievementAsync](/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsgetachievementasync)，如下所示。

**Flat C API**

```cpp theme={null}
auto asyncBlock = std::make_unique<XAsyncBlock>();
asyncBlock->queue = queue;
asyncBlock->context = nullptr;
asyncBlock->callback = [](XAsyncBlock* asyncBlock)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ asyncBlock }; // Take over ownership of XAsyncBlock*.
    XblAchievementsResultHandle resultHandle;
    auto hr = XblAchievementsGetAchievementResult(asyncBlock, &resultHandle);

    if (SUCCEEDED(hr))
    {
        const XblAchievement* achievements = nullptr;
        size_t achievementsCount = 0;
        hr = XblAchievementsResultGetAchievements( resultHandle, &achievements, &achievementsCount );

        // Use the achievements array to read the achievement data.

        XblAchievementsResultCloseHandle(resultHandle); // When you're done with the handle, close it.
        achievements = nullptr; // Clear the array after calling XblAchievementsResultCloseHandle to avoid the pointer to freed memory.
    }
};

HRESULT hr = XblAchievementsGetAchievementAsync(
    xboxLiveContext,
    xboxUserId,
    scid,
    achievementId.c_str(),
    asyncBlock.get()
);
if (SUCCEEDED(hr))
{
    // The call succeeded, so release the std::unique_ptr ownership of XAsyncBlock* because the callback will take over ownership.
    // If the call fails, std::unique_ptr will keep ownership and delete XAsyncBlock*.
    asyncBlock.release();
}
```

如需詳細資訊，請參閱下列內容：

* [XAsyncBlock](/zh-TW/reference/system/xasync/structs/xasyncblock)
* [XblAchievement](/zh-TW/reference/live/xsapi-c/achievements_c/structs/xblachievement)
* [XblAchievementsGetAchievementAsync](/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsgetachievementasync)
* [XblAchievementsGetAchievementResult](/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsgetachievementresult)
* [XblAchievementsResultCloseHandle](/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsresultclosehandle)
* [XblAchievementsResultGetAchievements](/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsresultgetachievements)

[返回本主題頂端。](#top)


## Related topics

- [遊戲管理型成就範例程式碼](/zh-TW/services/xbox-services/player-data/achievements/title-managed/how-to/live-achievements-howto-nav.md)
- [取得事件型成就](/zh-TW/services/xbox-services/player-data/achievements/event-based/how-to/live-getting-event-based-achievements.md)
- [操作說明](/zh-TW/services/xbox-services/player-data/achievements/title-managed/how-to/index.md)
- [遊戲管理型成就](/zh-TW/services/xbox-services/player-data/achievements/title-managed/live-achievements-tm-nav.md)
- [事件型成就與遊戲管理型成就](/zh-TW/services/xbox-services/player-data/achievements/live-achievements-eb-vs-tm.md)