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

# Devoluciones de llamada de la interfaz de usuario de Game Saves

> Implemente una interfaz de usuario de sincronización personalizada para PlayFab Game Saves registrando devoluciones de llamada, controlando la máquina de estados y llamando a las API de respuesta para conflictos y reintentos.

Game Saves proporciona un conjunto de devoluciones de llamada de la interfaz de usuario que permiten a su juego responder a los eventos durante las operaciones de sincronización. En XBOX y Windows, la plataforma proporciona una interfaz de usuario integrada para estos eventos. En otras plataformas (como Steam Deck), su juego debe implementar su propia interfaz de usuario controlando estas devoluciones de llamada.

Establecer devoluciones de llamada en XBOX y Windows reemplaza la interfaz de usuario proporcionada por la plataforma por su implementación. Esto resulta útil si su juego necesita una experiencia de jugador coherente en todas las plataformas: registre las mismas devoluciones de llamada en todas partes y la interfaz de usuario integrada no aparecerá.

## Cómo funciona la máquina de estados

Game Saves usa una máquina de estados interna para coordinar las devoluciones de llamada de la interfaz de usuario con el ciclo de vida de la operación asincrónica. Cuando se activa una devolución de llamada de la interfaz de usuario, la operación asincrónica se pausa: la devolución de llamada de `XAsyncBlock` no se activa hasta que se resuelve la devolución de llamada. La máquina de estados no avanza hasta que el juego llama a la API de respuesta correspondiente o se cancela la operación asincrónica.

Esto significa que:

* Cada tipo de devolución de llamada tiene una API de respuesta correspondiente. Llame a la API de respuesta para indicar al sistema qué hacer a continuación.
* Las API de respuesta se pueden llamar dentro o fuera de la función de devolución de llamada.
* Si una acción de respuesta es `Retry`, la operación se reintenta y puede desencadenar de nuevo la misma devolución de llamada.
* La devolución de llamada de `XAsyncBlock` solo se activa una vez que la operación alcanza un estado terminal: éxito, cancelación o una alternativa sin conexión.

Por ejemplo, si una carga falla debido a los límites de frecuencia:

1. `PFGameSaveFilesUiSyncFailedCallback` se activa con el error.
2. La devolución de llamada de `XAsyncBlock` aún no se activa: la máquina de estados espera una respuesta.
3. Si el usuario selecciona `Retry` y el reintento también falla, la devolución de llamada de error de sincronización se activa de nuevo.
4. Si el usuario selecciona `Cancel`, la devolución de llamada de `XAsyncBlock` se activa con `E_PF_GAMESAVE_USER_CANCELLED`.
5. Si un reintento se realiza correctamente, la devolución de llamada de `XAsyncBlock` se activa con `S_OK`.

## Cuándo se desencadenan las devoluciones de llamada

Las devoluciones de llamada de la interfaz de usuario solo se activan durante dos operaciones asincrónicas:

| Operación                           | Devoluciones de llamada que pueden desencadenarse                                                             |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `PFGameSaveFilesAddUserWithUiAsync` | Progreso, error de sincronización, contención de dispositivo activo, conflicto, sin espacio de almacenamiento |
| `PFGameSaveFilesUploadWithUiAsync`  | Progreso, error de sincronización                                                                             |

## Registro de devoluciones de llamada

Registre todas las devoluciones de llamada antes de llamar a `PFGameSaveFilesAddUserWithUiAsync` o `PFGameSaveFilesUploadWithUiAsync`:

```cpp theme={null}
PFGameSaveUICallbacks callbacks{};
callbacks.progressCallback = MyProgressCallback;
callbacks.progressContext = nullptr;
callbacks.syncFailedCallback = MySyncFailedCallback;
callbacks.syncFailedContext = nullptr;
callbacks.activeDeviceContentionCallback = MyActiveDeviceContentionCallback;
callbacks.activeDeviceContentionContext = nullptr;
callbacks.conflictCallback = MyConflictCallback;
callbacks.conflictContext = nullptr;
callbacks.outOfStorageCallback = MyOutOfStorageCallback;
callbacks.outOfStorageContext = nullptr;

HRESULT hr = PFGameSaveFilesSetUiCallbacks(&callbacks);
```

## Referencia de devoluciones de llamada

### Progreso

Notifica el progreso de la carga o descarga. Use `PFGameSaveFilesUiProgressGetProgress` dentro de la devolución de llamada para recuperar el `PFGameSaveFilesSyncState` actual, los bytes completados y los bytes totales.

**Devolución de llamada**: `PFGameSaveFilesUiProgressCallback`

**API de respuesta**: `PFGameSaveFilesSetUiProgressResponse`

| Acción   | Efecto                                                                                                        |
| -------- | ------------------------------------------------------------------------------------------------------------- |
| `Cancel` | Cancela la operación. La devolución de llamada de `XAsyncBlock` se activa con `E_PF_GAMESAVE_USER_CANCELLED`. |

<Note>
  La devolución de llamada de progreso no requiere una respuesta para continuar: la operación sigue avanzando por sí sola. Llame a la API de respuesta solo si el usuario quiere cancelar.
</Note>

#### Estados de sincronización

La enumeración `PFGameSaveFilesSyncState` indica en qué fase se encuentra la operación:

| Estado                 | Descripción                                             | ¿Es seguro escribir en la carpeta de guardado? |
| ---------------------- | ------------------------------------------------------- | ---------------------------------------------- |
| `NotStarted`           | La operación no ha comenzado                            | Sí                                             |
| `PreparingForDownload` | Preparándose para descargar desde la nube               | Sí                                             |
| `Downloading`          | Descargando desde la nube                               | No                                             |
| `PreparingForUpload`   | Leyendo y comprimiendo los archivos locales             | No                                             |
| `Uploading`            | Carga en la nube en curso (archivos locales capturados) | Sí                                             |
| `SyncComplete`         | Operación finalizada                                    | Sí                                             |

### Error de sincronización

Se activa cuando falla una operación de sincronización, por ejemplo debido a problemas de red o límites de frecuencia.

**Devolución de llamada**: `PFGameSaveFilesUiSyncFailedCallback`

**Parámetros**: Recibe `PFGameSaveFilesSyncState` (la fase que falló) y `HRESULT` (el código de error).

**API de respuesta**: `PFGameSaveFilesSetUiSyncFailedResponse`

| Acción       | Efecto                                                                                                                                                                                                                                       |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Cancel`     | Cancela la operación. La devolución de llamada de `XAsyncBlock` se activa con `E_PF_GAMESAVE_USER_CANCELLED`.                                                                                                                                |
| `Retry`      | Reintenta la operación con error. Si el reintento falla, esta devolución de llamada se activa de nuevo.                                                                                                                                      |
| `UseOffline` | Solo es válida durante `PFGameSaveFilesAddUserWithUiAsync`. La devolución de llamada de `XAsyncBlock` se activa con `S_OK`, pero el sistema entra en modo sin conexión. Use `PFGameSaveFilesIsConnectedToCloud()` para detectar este estado. |

Para obtener más detalles sobre el comportamiento del modo sin conexión, consulte [Modo sin conexión de Game Saves](/services/playfab/player-progression/game-saves/offline).

### Contención de dispositivo activo

Se activa durante `PFGameSaveFilesAddUserWithUiAsync` cuando otro dispositivo ya es el dispositivo activo para este usuario. La devolución de llamada recibe estructuras `PFGameSaveDescriptor` de los datos de guardado locales y remotos, que incluyen nombres de dispositivo, marcas de tiempo y tamaños de guardado que puede mostrar para ayudar al usuario a decidir.

**Devolución de llamada**: `PFGameSaveFilesUiActiveDeviceContentionCallback`

**API de respuesta**: `PFGameSaveFilesSetUiActiveDeviceContentionResponse`

| Acción              | Efecto                                                                                                                                                                     |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Cancel`            | Cancela la operación. La devolución de llamada de `XAsyncBlock` se activa con `E_PF_GAMESAVE_USER_CANCELLED`.                                                              |
| `Retry`             | Reintenta: resulta útil si el usuario espera que el otro dispositivo se libere pronto. Si el otro dispositivo sigue activo, esta devolución de llamada se activa de nuevo. |
| `SyncLastSavedData` | Convierte el dispositivo local en activo y sincroniza. El dispositivo remoto ya no puede cargar y recibe una notificación de cambio de dispositivo activo.                 |

Para obtener más detalles sobre el comportamiento del dispositivo activo, consulte [Cambios de dispositivo activo de Game Saves](/services/playfab/player-progression/game-saves/activedevicechanges).

### Conflicto

Se activa durante `PFGameSaveFilesAddUserWithUiAsync` cuando los datos de guardado locales y de la nube han divergido. La devolución de llamada recibe estructuras `PFGameSaveDescriptor` de los datos de guardado locales y remotos.

**Devolución de llamada**: `PFGameSaveFilesUiConflictCallback`

**API de respuesta**: `PFGameSaveFilesSetUiConflictResponse`

| Acción       | Efecto                                                                                                        |
| ------------ | ------------------------------------------------------------------------------------------------------------- |
| `Cancel`     | Cancela la operación. La devolución de llamada de `XAsyncBlock` se activa con `E_PF_GAMESAVE_USER_CANCELLED`. |
| `TakeLocal`  | Conserva los datos de guardado locales y los carga en la nube.                                                |
| `TakeRemote` | Descarta los cambios locales y descarga los datos de guardado de la nube.                                     |

<Info>
  La resolución de conflictos se aplica a todo el guardado, no a archivos o carpetas individuales. Para obtener detalles sobre cómo se detectan los conflictos en el nivel de unidad atómica y se resuelven globalmente, consulte [Conflictos de Game Saves](/services/playfab/player-progression/game-saves/conflicts).
</Info>

### Sin espacio de almacenamiento

Se activa durante `PFGameSaveFilesAddUserWithUiAsync` cuando el dispositivo local no tiene suficiente espacio en disco para descargar los datos de guardado desde la nube. La devolución de llamada recibe `requiredBytes`, que indica cuánto espacio se necesita.

**Devolución de llamada**: `PFGameSaveFilesUiOutOfStorageCallback`

**API de respuesta**: `PFGameSaveFilesSetUiOutOfStorageResponse`

| Acción   | Efecto                                                                                                                                                            |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Cancel` | Cancela la operación. La devolución de llamada de `XAsyncBlock` se activa con `E_PF_GAMESAVE_USER_CANCELLED`.                                                     |
| `Retry`  | Reintenta después de que el usuario libere espacio de almacenamiento local. Si sigue sin haber suficiente espacio, esta devolución de llamada se activa de nuevo. |

## Requisitos de plataforma

| Plataforma                               | Devoluciones de llamada de la interfaz de usuario                                                                             |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **XBOX y Windows**                       | Opcionales. Establezca devoluciones de llamada para reemplazar la interfaz de usuario integrada.                              |
| **Otras plataformas** (Steam Deck, etc.) | **Obligatorias**. No hay interfaz de usuario integrada disponible; su juego debe controlar todas las devoluciones de llamada. |

Para obtener detalles de implementación en Steam Deck, consulte la [guía de implementación en Steam Deck](/services/playfab/player-progression/game-saves/steam-deck-implementation).

## Contenido relacionado

* [Inicio rápido de Game Saves](/services/playfab/player-progression/game-saves/quickstart)
* [Modo sin conexión de Game Saves](/services/playfab/player-progression/game-saves/offline)
* [Conflictos de Game Saves](/services/playfab/player-progression/game-saves/conflicts)
* [Cambios de dispositivo activo de Game Saves](/services/playfab/player-progression/game-saves/activedevicechanges)


## Related topics

- [Inicio rápido de Game Saves](/es/services/playfab/player-progression/game-saves/quickstart.md)
- [Guía de implementación en Steam Deck para PlayFab Game Saves](/es/services/playfab/player-progression/game-saves/steam-deck-implementation.md)
- [Información general de Game Saves](/es/services/playfab/player-progression/game-saves/overview.md)
- [Implementación de Game Saves con el GDK de octubre de 2025](/es/services/playfab/player-progression/game-saves/october-2025-gdk-changes.md)
- [Devoluciones de llamada de GameInput](/es/build/core-features/common/input/advanced/input-callbacks.md)