Devoluciones de llamada de la interfaz de usuario de Game Saves

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:

PFGameSaveFilesUiSyncFailedCallback se activa con el error.
La devolución de llamada de XAsyncBlock aún no se activa. La máquina de estados espera una respuesta.
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.
Si el usuario selecciona Cancel, la devolución de llamada de XAsyncBlock se activa con E_PF_GAMESAVE_USER_CANCELLED.
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:

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

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.

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.

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 en Game Saves.

Conflicto

Se activa durante PFGameSaveFilesAddUserWithUiAsync cuando los datos de guardado locales y en 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 en la nube.

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.

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.

En proceso frente a fuera de proceso (interfaz de usuario del sistema)

El lugar donde se ejecuta Game Saves depende de la plataforma, y esto afecta a cómo se controlan los eventos de la interfaz de usuario:

Fuera de proceso (XBOX y Windows): en XBOX y Windows, Game Saves siempre se ejecuta fuera de proceso. La plataforma (Connected Storage / GRTS) realiza la sincronización y proporciona cuadros de diálogo integrados de la interfaz de usuario del sistema para errores de sincronización, conflictos, contención de dispositivo activo y falta de espacio de almacenamiento. El jugador interactúa directamente con esos cuadros de diálogo, y la plataforma traduce el resultado a los mismos códigos de finalización asincrónica que recibe su juego en proceso. Aun así, puede registrar devoluciones de llamada para reemplazar la interfaz de usuario integrada.
En proceso (otras plataformas, como Steam Deck): donde el servicio de la plataforma no está disponible, su juego hospeda el motor de sincronización de Game Saves y controla los eventos de la interfaz de usuario mediante las devoluciones de llamada descritas anteriormente. Su juego controla por completo la máquina de estados con las API de respuesta.

La cancelación siempre es un resultado posible

Independientemente de la ruta, todos los flujos de la interfaz de usuario pueden terminar con el usuario saliendo sin una sincronización correcta, por lo que su juego siempre debe controlar una cancelación definitiva:

Intención del usuario	Finalización asincrónica	`IsConnectedToCloud()`	¿Carpeta de guardado?
Continuar en línea (correcto)	`S_OK`	`true`	Sí
Jugar sin conexión	`S_OK`	`false`	Sí
Cancelar / Salir (jugador)	`E_PF_GAMESAVE_USER_CANCELLED` (`0x800704C7`)	n/a	No
Cancelar (el juego llamó a `XAsyncCancel`)	`E_ABORT` (`0x80004004`)	n/a	No

La única acción de “salir” que aún permite al jugador continuar es Use Offline en el mensaje de error de sincronización (un resultado correcto). Cualquier otra cancelación es definitiva y no deja ninguna carpeta de guardado. Trátela como no permitir jugar. Consulte Modo sin conexión de Game Saves. En la interfaz de usuario del sistema integrada (fuera de proceso), estas opciones aparecen con el texto de la plataforma. Por ejemplo, el cuadro de diálogo de error de sincronización ofrece “Try again” / “Play offline”, y el cuadro de diálogo de contención ofrece “Stop sync & continue” / “Quit game”. “Play offline” corresponde al modo sin conexión (S_OK, no conectado); “Quit game” corresponde a E_PF_GAMESAVE_USER_CANCELLED. Cancelar un mensaje de conflicto es definitivo en ambas rutas. Se completa con E_PF_GAMESAVE_USER_CANCELLED y no pasa en cascada a un mensaje de error de sincronización. Para una interfaz de usuario multiplataforma personalizada (por ejemplo, que coincida con su implementación de Steam Deck), registre devoluciones de llamada en todas partes y valide los flujos fuera de proceso en su hardware de destino. Independientemente de la ruta, condicione el juego al resultado de la finalización: S_OK + conectado → jugar en línea; S_OK + no conectado → jugar sin conexión (advierta al jugador); cancelación o error sin carpeta → bloquear el juego.

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 (por ejemplo, Steam Deck)	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.

XBOX Services

PlayFab

Devoluciones de llamada de la interfaz de usuario de Game Saves

Cómo funciona la máquina de estados

Cuándo se desencadenan las devoluciones de llamada

Registro de devoluciones de llamada

Referencia de devoluciones de llamada

Progreso

Estados de sincronización

Error de sincronización

Contención de dispositivo activo

Conflicto

Sin espacio de almacenamiento

En proceso frente a fuera de proceso (interfaz de usuario del sistema)

La cancelación siempre es un resultado posible

Requisitos de plataforma

Contenido relacionado

​Cómo funciona la máquina de estados

​Cuándo se desencadenan las devoluciones de llamada

​Registro de devoluciones de llamada

​Referencia de devoluciones de llamada

​Progreso

​Estados de sincronización

​Error de sincronización

​Contención de dispositivo activo

​Conflicto

​Sin espacio de almacenamiento

​En proceso frente a fuera de proceso (interfaz de usuario del sistema)

​La cancelación siempre es un resultado posible

​Requisitos de plataforma

​Contenido relacionado

Cómo funciona la máquina de estados

Cuándo se desencadenan las devoluciones de llamada

Registro de devoluciones de llamada

Referencia de devoluciones de llamada

Progreso

Estados de sincronización

Error de sincronización

Contención de dispositivo activo

Conflicto

Sin espacio de almacenamiento

En proceso frente a fuera de proceso (interfaz de usuario del sistema)

La cancelación siempre es un resultado posible

Requisitos de plataforma

Contenido relacionado