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

# Actualización de la presencia de un usuario mediante XSAPI C

> Ejemplo de C plano que usa XblPresenceSetPresenceAsync para actualizar el estado de presencia en línea de un usuario de los servicios de XBOX y anunciar la actividad actual dentro del juego.

Este tema proporciona código de ejemplo para establecer el estado de presencia en línea de un usuario. La presencia enriquecida de los servicios XBOX proporciona características para anunciar la actividad actual de un jugador a otros jugadores.

Para obtener más información, consulte [Información general de la presencia enriquecida](https://docs.xbox.com/es/services/xbox-services/community/presence/live-presence-overview.md).

## Actualización del estado de presencia en línea de un usuario

Este código de ejemplo establece el estado de presencia en línea de un usuario.

En el ejemplo siguiente se usa la API plana de 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*.
    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();
}
```

Para obtener más información, consulte lo siguiente:

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

## Actualización del estado de presencia enriquecida

En el ejemplo siguiente se establece la cadena de presencia enriquecida `playingMap` para el usuario. En este ejemplo, `playingMap` está configurada como una cadena estática sin tokens. `xboxLiveContext` es el `XblContextHandle` del usuario y `queue` es la cola de tareas del juego, o `nullptr` para usar la cola de tareas predeterminada del proceso.

```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 cadena de presencia configurada requiere cadenas de reemplazo explícitas, establezca `presenceTokenIds` en sus identificadores de cadena configurados en el orden de los marcadores de posición y establezca `presenceTokenIdsCount` en la longitud de la matriz.

Si el miembro `scid` o `presenceId` está vacío, la solicitud solo incluye el estado activo o inactivo y no incluye ninguna cadena de presencia enriquecida.

Para obtener más información, consulte lo siguiente:

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

## Límites de velocidad y certificación

El servicio de presencia permite a cada usuario y título 3 escrituras en 15 segundos y 30 escrituras en 300 segundos. Actualice la presencia enriquecida cuando cambie la actividad del jugador y combine los cambios rápidos en una sola actualización. Si también actualiza la presencia enriquecida periódicamente, mantenga la velocidad combinada dentro de ambos límites.

Si una llamada produce un error `HTTP_E_STATUS_429_TOO_MANY_REQUESTS` (`XblErrorCondition::Http429TooManyRequests`), no la reintente en un bucle. La respuesta del servicio incluye un encabezado Retry-After y XSAPI lo respeta.

La prueba de certificación [XR-132](https://docs.xbox.com/es/publishing/certification/xr/xr-132.md) rechaza un título cuya tasa de solicitudes es igual o superior a 10 veces el límite sostenido, es decir, 300 escrituras de presencia en 300 segundos. Este umbral no es un margen de funcionamiento seguro. Para obtener más información, consulte [Limitación de velocidad específica](https://docs.xbox.com/es/services/xbox-services/develop/best-practices/live-fine-grained-rate-limiting.md).


## Related topics

- [Código de ejemplo de presencia enriquecida (contenido)](https://docs.xbox.com/es/services/xbox-services/community/presence/how-to/live-presence-howto-nav.md)
- [Información general de la presencia enriquecida](https://docs.xbox.com/es/services/xbox-services/community/presence/live-presence-overview.md)
- [Procedimientos](https://docs.xbox.com/es/services/xbox-services/community/presence/how-to/index.md)
- [Procedimientos recomendados para la presencia enriquecida](https://docs.xbox.com/es/services/xbox-services/community/presence/concepts/live-presence-best-practices.md)
- [Actualización de la presencia de un usuario mediante REST](https://docs.xbox.com/es/services/xbox-services/community/presence/how-to/live-updating-presence-rest.md)