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

# Mise à jour de la présence d'un utilisateur via XSAPI C

> Exemple en C plat utilisant XblPresenceSetPresenceAsync pour mettre à jour l'état de présence en ligne d'un utilisateur des services XBOX et indiquer son activité en cours dans le jeu.

Cette rubrique fournit un exemple de code pour définir l'état de présence en ligne d'un utilisateur. La présence enrichie des services XBOX fournit des fonctionnalités permettant d'indiquer l'activité en cours d'un joueur aux autres joueurs.

Pour plus d'informations, consultez [Vue d'ensemble de la présence enrichie](https://docs.xbox.com/fr/services/xbox-services/community/presence/live-presence-overview.md).

## Mise à jour de l'état de présence en ligne d'un utilisateur

Cet exemple de code définit l'état de présence en ligne d'un utilisateur.

L'exemple suivant utilise l'API C plate.

```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*.
    HRESULT hr = XAsyncGetStatus(asyncBlock, false);
    if (FAILED(hr))
    {
        // Log the failure. To choose how to handle it, call XblGetErrorCondition(hr).
    }
};

HRESULT hr = XblPresenceSetPresenceAsync(xboxLiveContext, true, nullptr, 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();
}
```

Pour plus d'informations, consultez les rubriques suivantes :

* [XAsyncBlock](https://docs.xbox.com/fr/reference/system/xasync/structs/xasyncblock.md)
* [XAsyncGetStatus](https://docs.xbox.com/fr/reference/system/xasync/functions/xasyncgetstatus.md)
* [XblPresenceSetPresenceAsync](https://docs.xbox.com/fr/reference/live/xsapi-c/presence_c/functions/xblpresencesetpresenceasync.md)

## Mise à jour de l'état de présence enrichie

L'exemple suivant définit la chaîne de présence enrichie `playingMap` pour l'utilisateur. Dans cet exemple, `playingMap` est configurée comme une chaîne statique sans jeton. `xboxLiveContext` est le `XblContextHandle` de l'utilisateur, et `queue` est la file d'attente de tâches de votre jeu, ou `nullptr` pour utiliser la file d'attente de tâches par défaut du processus.

```cpp theme={null}
#include <memory>
#include <string.h>
#include <xsapi-c/services_c.h>

HRESULT SetRichPresence(XblContextHandle xboxLiveContext, XTaskQueueHandle queue)
{
    // Get the SCID that you passed to XblInitialize.
    const char* scid = nullptr;
    HRESULT hr = XblGetScid(&scid);
    if (FAILED(hr))
    {
        return hr;
    }

    XblPresenceRichPresenceIds ids{};
    if (strcpy_s(ids.scid, sizeof(ids.scid), scid) != 0)
    {
        return E_INVALIDARG;
    }
    ids.presenceId = "playingMap";

    // Use a new XAsyncBlock for each call.
    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*.
        HRESULT result = XAsyncGetStatus(asyncBlock, false);
        if (FAILED(result))
        {
            // Log every failure. To choose how to handle it, call XblGetErrorCondition(result).
            // For XblErrorCondition::Http429TooManyRequests, don't retry right away.
        }
    };

    hr = XblPresenceSetPresenceAsync(xboxLiveContext, true, &ids, asyncBlock.get());
    if (SUCCEEDED(hr))
    {
        // The callback now owns the XAsyncBlock.
        asyncBlock.release();
    }
    return hr;
}
```

Si la chaîne de présence configurée nécessite des chaînes de remplacement explicites, définissez `presenceTokenIds` sur leurs ID de chaîne configurés dans l'ordre des espaces réservés, et définissez `presenceTokenIdsCount` sur la longueur du tableau.

Si le membre `scid` ou `presenceId` est vide, la requête inclut uniquement l'état actif ou inactif et n'inclut pas de chaîne de présence enrichie.

Pour plus d'informations, consultez les rubriques suivantes :

* [XblGetErrorCondition](https://docs.xbox.com/fr/reference/live/xsapi-c/errors_c/functions/xblgeterrorcondition.md)
* [XblGetScid](https://docs.xbox.com/fr/reference/live/xsapi-c/xbox_live_global_c/functions/xblgetscid.md)
* [XblPresenceRichPresenceIds](https://docs.xbox.com/fr/reference/live/xsapi-c/presence_c/structs/xblpresencerichpresenceids.md)
* [XblPresenceSetPresenceAsync](https://docs.xbox.com/fr/reference/live/xsapi-c/presence_c/functions/xblpresencesetpresenceasync.md)

## Limites de débit et certification

Le service de présence autorise, pour chaque utilisateur et chaque titre, 3 écritures en 15 secondes et 30 écritures en 300 secondes. Mettez à jour la présence enrichie lorsque l'activité du joueur change, et regroupez les changements rapides en une seule mise à jour. Si vous actualisez également la présence enrichie périodiquement, maintenez le débit combiné dans les deux limites.

Si un appel échoue avec `HTTP_E_STATUS_429_TOO_MANY_REQUESTS` (`XblErrorCondition::Http429TooManyRequests`), ne réessayez pas en boucle. La réponse du service inclut un en-tête Retry-After, que XSAPI respecte.

Le test de certification [XR-132](https://docs.xbox.com/fr/publishing/certification/xr/xr-132.md) fait échouer un titre dont le débit de requêtes est supérieur ou égal à 10 fois la limite soutenue, soit 300 écritures de présence en 300 secondes. Ce seuil ne constitue pas une marge de fonctionnement sûre. Pour plus d'informations, consultez [Limitation du débit précise](https://docs.xbox.com/fr/services/xbox-services/develop/best-practices/live-fine-grained-rate-limiting.md).


## Related topics

- [Exemple de code de présence enrichie (contenu)](https://docs.xbox.com/fr/services/xbox-services/community/presence/how-to/live-presence-howto-nav.md)
- [Vue d'ensemble de la présence enrichie](https://docs.xbox.com/fr/services/xbox-services/community/presence/live-presence-overview.md)
- [Procédures](https://docs.xbox.com/fr/services/xbox-services/community/presence/how-to/index.md)
- [Bonnes pratiques pour la présence enrichie](https://docs.xbox.com/fr/services/xbox-services/community/presence/concepts/live-presence-best-practices.md)
- [XblPresenceSetPresenceAsync](https://docs.xbox.com/fr/reference/live/xsapi-c/presence_c/functions/xblpresencesetpresenceasync.md)