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

# Código de exemplo para leaderboards baseados em eventos

> Exemplos de código da XSAPI para leaderboards baseados em eventos do XBOX Live, incluindo os primeiros resultados, paginação e centralização em torno de uma posição ou jogador especificado.

Este tópico fornece código de exemplo para exibição básica de leaderboard, obtenção de uma página especificada de resultados, salto para um jogador especificado no leaderboard e obtenção da próxima página de leaderboards.

Este tópico aborda o seguinte:

* [Obter o topo de um leaderboard](#gttoal)
* [Obter um leaderboard em torno de uma posição especificada](#galaasr)
* [Obter um leaderboard em torno de um jogador especificado](#galaasp)
* [Obter a próxima página de leaderboards](#gtnpol)

<a id="gttoal" />

## Obter o topo de um leaderboard

Use [XblLeaderboardGetLeaderboardAsync](/pt-BR/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardgetleaderboardasync) para retornar os valores do leaderboard especificado, começando pelo topo do leaderboard. Ao consultar um leaderboard baseado em uma estatística de usuário baseada em eventos, defina o campo `queryType` como `XblLeaderboardQueryType::UserStatBacked`.

### Exibição básica de leaderboard (API C simples)

#### API C simples

```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();
}
```

Para obter mais informações, veja o seguinte:

* [XAsyncBlock](/pt-BR/reference/system/xasync/structs/xasyncblock)
* [XblLeaderboardGetLeaderboardAsync](/pt-BR/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardgetleaderboardasync)
* [XblLeaderboardGetLeaderboardResult](/pt-BR/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardgetleaderboardresult)
* [XblLeaderboardGetLeaderboardResultSize](/pt-BR/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardgetleaderboardresultsize)
* [XblLeaderboardQuery](/pt-BR/reference/live/xsapi-c/leaderboard_c/structs/xblleaderboardquery)
* [XblLeaderboardResult](/pt-BR/reference/live/xsapi-c/leaderboard_c/structs/xblleaderboardresult)

<a id="galaasr" />

## Obter um leaderboard em torno de uma posição especificada

Substitua o bloco de código de 4 linhas que instancia e configura a consulta de leaderboard no exemplo anterior de consulta básica de leaderboard (API C simples) pelo bloco de código a seguir para obter uma página especificada de resultados de uma consulta de leaderboard.

### Obter uma página especificada de resultados (C)

#### API C simples

```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;
```

Para obter mais informações, veja [XblLeaderboardQuery](/pt-BR/reference/live/xsapi-c/leaderboard_c/structs/xblleaderboardquery).

<a id="galaasp" />

## Obter um leaderboard em torno de um jogador especificado

Substitua o bloco de código de 4 linhas que instancia e configura a consulta de leaderboard no exemplo anterior de consulta básica de leaderboard (API C simples) pelo bloco de código a seguir para obter um leaderboard em torno de um jogador especificado.

#### API C simples

```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;
```

Para obter mais informações, veja [XblLeaderboardQuery](/pt-BR/reference/live/xsapi-c/leaderboard_c/structs/xblleaderboardquery).

<a id="gtnpol" />

## Obter a próxima página de leaderboards

Para obter a próxima página de um resultado de leaderboard anterior, chame [XblLeaderboardResultGetNextAsync](/pt-BR/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardresultgetnextasync) conforme mostrado no código de exemplo a seguir.

#### API C simples

```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();
}
```

Para obter mais informações, veja o seguinte:

* [XAsyncBlock](/pt-BR/reference/system/xasync/structs/xasyncblock)
* [XblLeaderboardResult](/pt-BR/reference/live/xsapi-c/leaderboard_c/structs/xblleaderboardresult)
* [XblLeaderboardResultGetNextAsync](/pt-BR/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardresultgetnextasync)
* [XblLeaderboardResultGetNextResult](/pt-BR/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardresultgetnextresult)
* [XblLeaderboardResultGetNextResultSize](/pt-BR/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardresultgetnextresultsize)


## Related topics

- [Código de exemplo de estatísticas e leaderboards baseados em eventos](/pt-BR/services/xbox-services/player-data/stats-leaderboards/event-based/how-to/live-statslb-eb-howto-nav.md)
- [Configuração no portal de leaderboards baseados em eventos](/pt-BR/services/xbox-services/player-data/stats-leaderboards/event-based/config/live-eb-leaderboards-portal.md)
- [Configuração no portal de estatísticas e leaderboards baseados em eventos](/pt-BR/services/xbox-services/player-data/stats-leaderboards/event-based/config/live-statslb-eb-config-nav.md)
- [Código de exemplo de conquistas baseadas em eventos](/pt-BR/services/xbox-services/player-data/achievements/event-based/how-to/live-achievements-eb-howto-nav.md)
- [Estatísticas e leaderboards baseados em eventos](/pt-BR/services/xbox-services/player-data/stats-leaderboards/event-based/live-statslb-eb-nav.md)