> ## 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 程式碼範例，包括取得頂端結果、分頁，以及以指定排名或玩家為中心。

本主題提供基本排行榜顯示、取得指定結果頁面、跳至排行榜中的指定玩家，以及取得排行榜下一頁的範例程式碼。

本主題涵蓋下列內容：

* [取得排行榜頂端](#gttoal)
* [取得指定排名周圍的排行榜](#galaasr)
* [取得指定玩家周圍的排行榜](#galaasp)
* [取得排行榜的下一頁](#gtnpol)

## 取得排行榜頂端

使用 [XblLeaderboardGetLeaderboardAsync](/zh-TW/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardgetleaderboardasync) 從排行榜頂端開始傳回指定排行榜的值。查詢以事件型使用者統計資料為基礎的排行榜時，請務必將 `queryType` 欄位設定為 `XblLeaderboardQueryType::UserStatBacked`。

### 基本排行榜顯示 (flat C API)

#### 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*.
    size_t resultSize;
    HRESULT hr = XblLeaderboardGetLeaderboardResultSize(asyncBlock, &resultSize);

    if (SUCCEEDED(hr))
    {
        leaderboardBuffer.resize(resultSize);
        XblLeaderboardResult* leaderboard{};

        hr = XblLeaderboardGetLeaderboardResult(asyncBlock, resultSize, leaderboardBuffer.data(), &leaderboard, nullptr);

        if (SUCCEEDED(hr))
        {
            // Use XblLeaderboardResult in result.
            for (auto row = 0u; row < leaderboard->rowsCount; ++row)
            {
                std::stringstream rowText;
                rowText << leaderboard->rows[row].xboxUserId << "\t";

                for (auto column = 0u; column < leaderboard->rows[row].columnValuesCount; ++column)
                {
                    rowText << leaderboard->rows[row].columnValues[column] << "\t";
                }
            }
        }
    }
};

// Instantiate and configure the leaderboard query.
XblLeaderboardQuery leaderboardQuery = {}; 
pal::strcpy(leaderboardQuery.scid, sizeof(leaderboardQuery.scid), scid.c_str()) 
leaderboardQuery.leaderboardName = leaderboardName.c_str(); 
leaderboardQuery.queryType = XblLeaderboardQueryType::UserStatBacked;
// For more leaderboard query options, replace the 4-line code block 
// that precedes this comment as indicated in other examples.

HRESULT hr = XblLeaderboardGetLeaderboardAsync(
    xboxLiveContext,
    leaderboardQuery,
    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)
* [XblLeaderboardGetLeaderboardAsync](/zh-TW/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardgetleaderboardasync)
* [XblLeaderboardGetLeaderboardResult](/zh-TW/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardgetleaderboardresult)
* [XblLeaderboardGetLeaderboardResultSize](/zh-TW/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardgetleaderboardresultsize)
* [XblLeaderboardQuery](/zh-TW/reference/live/xsapi-c/leaderboard_c/structs/xblleaderboardquery)
* [XblLeaderboardResult](/zh-TW/reference/live/xsapi-c/leaderboard_c/structs/xblleaderboardresult)

## 取得指定排名周圍的排行榜

將先前「基本排行榜查詢 (flat C API)」範例中，具現化並設定排行榜查詢的 4 行程式碼區塊替換為下列程式碼區塊，即可從排行榜查詢取得指定的結果頁面。

### 取得指定的結果頁面 (C)

#### Flat C API

```cpp theme={null}
XblLeaderboardQuery leaderboardQuery = {};
pal::strcpy(leaderboardQuery.scid, sizeof(leaderboardQuery.scid), scid.c_str());
leaderboardQuery.leaderboardName = leaderboardName.c_str();
leaderboardQuery.skipResultToRank = 100;
leaderboardQuery.maxItems = 100;
leaderboardQuery.queryType = XblLeaderboardQueryType::UserStatBacked;
```

如需詳細資訊，請參閱 [XblLeaderboardQuery](/zh-TW/reference/live/xsapi-c/leaderboard_c/structs/xblleaderboardquery)。

## 取得指定玩家周圍的排行榜

將先前「基本排行榜查詢 (flat C API)」範例中，具現化並設定排行榜查詢的 4 行程式碼區塊替換為下列程式碼區塊，即可取得指定玩家周圍的排行榜。

#### Flat C API

```cpp theme={null}
XblLeaderboardQuery leaderboardQuery = {};
pal::strcpy(leaderboardQuery.scid, sizeof(leaderboardQuery.scid), scid.c_str());
leaderboardQuery.leaderboardName = leaderboardName.c_str();
leaderboardQuery.skipToXboxUserId = xboxUserId;
leaderboardQuery.maxItems = 100;
leaderboardQuery.queryType = XblLeaderboardQueryType::UserStatBacked;
```

如需詳細資訊，請參閱 [XblLeaderboardQuery](/zh-TW/reference/live/xsapi-c/leaderboard_c/structs/xblleaderboardquery)。

## 取得排行榜的下一頁

若要取得先前排行榜結果的下一頁，請依下列範例程式碼所示呼叫 [XblLeaderboardResultGetNextAsync](/zh-TW/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardresultgetnextasync)。

#### 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*.
    size_t resultSize;
    HRESULT hr = XblLeaderboardResultGetNextResultSize(asyncBlock, &resultSize);

    if (SUCCEEDED(hr))
    {
        std::vector<char> buffer(resultSize, 0);
        XblLeaderboardResult* result{};

        hr = XblLeaderboardResultGetNextResult(asyncBlock, resultSize, buffer.data(), &result, nullptr);
        // Use result to read the leaderboard results.
    }
};

HRESULT hr = XblLeaderboardResultGetNextAsync(
    xboxLiveContext,
    leaderboardResult,
    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)
* [XblLeaderboardResult](/zh-TW/reference/live/xsapi-c/leaderboard_c/structs/xblleaderboardresult)
* [XblLeaderboardResultGetNextAsync](/zh-TW/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardresultgetnextasync)
* [XblLeaderboardResultGetNextResult](/zh-TW/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardresultgetnextresult)
* [XblLeaderboardResultGetNextResultSize](/zh-TW/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardresultgetnextresultsize)


## Related topics

- [事件型統計資料與排行榜範例程式碼 (內容)](/zh-TW/services/xbox-services/player-data/stats-leaderboards/event-based/how-to/live-statslb-eb-howto-nav.md)
- [遊戲管理型統計資料與排行榜範例程式碼 (內容)](/zh-TW/services/xbox-services/player-data/stats-leaderboards/title-managed/how-to/live-statslb-tm-howto-nav.md)
- [事件型排行榜的入口網站設定](/zh-TW/services/xbox-services/player-data/stats-leaderboards/event-based/config/live-eb-leaderboards-portal.md)
- [事件型成就範例程式碼](/zh-TW/services/xbox-services/player-data/achievements/event-based/how-to/live-achievements-eb-howto-nav.md)
- [事件型統計資料與排行榜 (內容)](/zh-TW/services/xbox-services/player-data/stats-leaderboards/event-based/live-statslb-eb-nav.md)