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

# Mode hors connexion de Game Saves

> Utilisez le mode hors connexion de PlayFab Game Saves pour permettre aux joueurs de poursuivre leur progression sans connectivité et synchroniser les sauvegardes cloud au retour du réseau.

Game Saves est conçu pour fonctionner aussi bien en ligne qu'hors connexion, ce qui permet aux joueurs de continuer à jouer même lorsque la connectivité réseau n'est pas disponible. Le système fonctionne selon deux modes distincts en fonction de la disponibilité du réseau et des choix de l'utilisateur.

## Modes de connexion

### Mode connecté au cloud

Lorsque le réseau est disponible et que `PFGameSaveFilesAddUserWithUiAsync()` se termine correctement, le système fonctionne en mode connecté au cloud. Dans ce mode :

* Toutes les API fonctionnent normalement avec une synchronisation cloud complète
* Les chargements des données de sauvegarde fonctionnent comme prévu
* Les informations de quota de stockage sont disponibles
* La surveillance de l'appareil actif fonctionne correctement

### Mode hors connexion (non connecté au cloud)

Lorsque le réseau n'est pas disponible ou que l'utilisateur choisit de jouer hors connexion, le système passe en mode hors connexion avec des fonctionnalités limitées. Vous pouvez vérifier l'état actuel de la connexion à l'aide de `PFGameSaveFilesIsConnectedToCloud()` pour déterminer dans quel mode fonctionne le système.

## Gestion des défaillances réseau lors de la synchronisation initiale

Lorsque `PFGameSaveFilesAddUserWithUiAsync()` est appelée sans connectivité réseau, elle déclenche un `PFGameSaveFilesUiSyncFailedCallback`. Le rappel `XAsyncBlock` ne se déclenche pas tant que le système attend la réponse de l'utilisateur : l'opération asynchrone est suspendue jusqu'à ce que l'utilisateur sélectionne une action finale.

```cpp theme={null}
// Handle sync failure callback
void MyPFGameSaveFilesUiSyncFailedCallback(PFLocalUserHandle localUserHandle, PFGameSaveFilesSyncState syncState, HRESULT error, void* context)
{
    // Tell the user something like this:
    std::cout << "We couldn't sync your data with the cloud just now" << std::endl;
    std::cout << "Try syncing again or use this game offline" << std::endl;
    std::cout << "[Try Again]" << std::endl;
    std::cout << "[Use Offline]" << std::endl;

    // if user chooses [Try Again], call PFGameSaveFilesSetUiSyncFailedResponse(localUserHandle, PFGameSaveFilesUiSyncFailedUserAction::Retry);
    // if user chooses [Use Offline], call PFGameSaveFilesSetUiSyncFailedResponse(localUserHandle, PFGameSaveFilesUiSyncFailedUserAction::UseOffline);

    // These API calls can happen inside or outside of this callback
}
```

**Options de réponse de l'utilisateur :**

* **Try Again (`Retry`)** : retente l'appel réseau. Si la nouvelle tentative échoue également, ce rappel se déclenche à nouveau et l'utilisateur doit répondre de nouveau. Le rappel `XAsyncBlock` reste différé à chaque boucle de nouvelle tentative.
* **Use Offline (`UseOffline`)** : le rappel `XAsyncBlock` se déclenche avec `S_OK`, mais le système passe en mode hors connexion (détectable avec `PFGameSaveFilesIsConnectedToCloud()`).
* **Cancel** : le rappel `XAsyncBlock` se déclenche avec `E_PF_GAMESAVE_USER_CANCELLED`.

## Comportement des API en mode hors connexion

En mode hors connexion, les API se comportent différemment :

### API qui fonctionnent normalement

* `PFGameSaveFilesGetFolder()` : renvoie le chemin du dossier de sauvegarde local

### API aux fonctionnalités limitées

* `PFGameSaveFilesUploadWithUiAsync()` : renvoie immédiatement `S_OK`, mais l'achèvement asynchrone renvoie `E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD`
* `PFGameSaveFilesGetRemainingQuota()` : renvoie `E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD`
* `PFGameSaveFilesSetActiveDeviceChangedCallback()` : peut être défini, mais ne se déclenchera jamais

### Retour au mode en ligne

* Appelez de nouveau `PFGameSaveFilesAddUserWithUiAsync()` pour tenter de vous reconnecter
* Il n'est pas nécessaire de réinitialiser complètement le système Game Saves
* L'interface utilisateur d'échec s'affichera à nouveau si le réseau n'est toujours pas disponible
* Utilisez `PFGameSaveFilesIsConnectedToCloud()` pour vérifier l'état de la connexion après les nouvelles tentatives

## Quand Game Saves passe en mode hors connexion ou renvoie une erreur

Une question d'intégration courante est la suivante : *quand la synchronisation initiale (`PFGameSaveFilesAddUserWithUiAsync`) fait-elle passer le joueur en mode hors connexion, et quand échoue-t-elle avec un code d'erreur ?* Il existe trois résultats finaux (connecté, hors connexion ou annulé), et une annulation peut provenir du joueur ou du jeu :

| Résultat | Comment il est atteint | Résultat asynchrone | `IsConnectedToCloud()` | Dossier de sauvegarde disponible ? | Gestion recommandée |
| - | - | - | - | - | - |
| **Connecté** | La synchronisation s'est terminée correctement | `S_OK` | `true` | Oui | Autorisez le jeu ; les sauvegardes sont synchronisées avec le cloud. |
| **Hors connexion** | L'utilisateur a sélectionné **Use Offline** dans l'invite d'échec de synchronisation (ou un autre appareil est devenu l'appareil actif) | `S_OK` | `false` | Oui | Autorisez le jeu avec les sauvegardes locales ; indiquez au joueur que les sauvegardes ne seront pas synchronisées. |
| **Annulé par le joueur** | L'utilisateur a sélectionné **Cancel** dans une invite | `E_PF_GAMESAVE_USER_CANCELLED` (`0x800704C7`) | n/a | **Non** | **Bloquez le jeu** ou revenez à un menu sûr : il n'y a aucun dossier pour enregistrer ou charger. |
| **Annulé par le jeu** | Le jeu a appelé `XAsyncCancel` sur le `XAsyncBlock` | `E_ABORT` (`0x80004004`) | n/a | **Non** | Comme pour une annulation par le joueur : il n'y a aucun dossier pour enregistrer ou charger. |

Points clés :

* **Le mode hors connexion est un résultat de réussite, et non une erreur.** Il n'est activé que par un choix explicite de **Use Offline**, et l'opération asynchrone se termine avec `S_OK`. Détectez-le avec `PFGameSaveFilesIsConnectedToCloud()`.
* **Les défaillances temporaires/techniques sont signalées via l'interface utilisateur d'échec de synchronisation**, et ne sont pas renvoyées directement par `PFGameSaveFilesAddUserWithUiAsync`. L'utilisateur (ou votre réponse automatique) choisit ensuite `Retry`, `UseOffline` ou `Cancel`, ce qui aboutit à l'un des trois résultats ci-dessus.
* **L'annulation est finale et ne produit aucun dossier de sauvegarde.** Traitez « annulé » (ou toute défaillance qui ne laisse aucun dossier) comme *ne pas autoriser le jeu*.
* **L'annulation par le joueur et l'annulation par le jeu renvoient des codes différents.** Seul le choix de **Cancel** par le joueur dans une invite produit `E_PF_GAMESAVE_USER_CANCELLED`. Si votre jeu annule lui-même l'opération avec `XAsyncCancel`, elle se termine avec `E_ABORT`. Vérifiez les deux si vous souhaitez les traiter de la même manière.

<Note>
  L'annulation d'une invite de **conflit** est également finale : elle se termine avec `E_PF_GAMESAVE_USER_CANCELLED` et ne bascule pas automatiquement vers une invite d'échec de synchronisation « Use Offline ». Si vous souhaitez une expérience « rejeter le conflit mais continuer à jouer hors connexion », concevez-la explicitement (par exemple, relancez `PFGameSaveFilesAddUserWithUiAsync` et sélectionnez Use Offline lors de l'échec qui en résulte). Consultez [Conflits de Game Saves](/fr/services/playfab/player-progression/game-saves/conflicts).
</Note>

## Codes d'erreur de Game Saves

Les HRESULT suivants sont définis par le SDK Game Saves. Les codes de la plage `0x8923xxxx` sont propres à Game Saves ; `0x800704C7` correspond à `HRESULT_FROM_WIN32(ERROR_CANCELLED)`.

| Code | Valeur | Quand il est renvoyé |
| - | - | - |
| `E_PF_GAMESAVE_USER_CANCELLED` | `0x800704C7` | L'utilisateur a sélectionné **Cancel** dans une invite de l'interface utilisateur. Final ; aucun dossier de sauvegarde. (Si le jeu annule le `XAsyncBlock` avec `XAsyncCancel`, l'opération se termine plutôt avec le code standard `E_ABORT` (`0x80004004`).) |
| `E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD` | `0x89237004` | Renvoyé par `PFGameSaveFilesUploadWithUiAsync()` et `PFGameSaveFilesGetRemainingQuota()` lorsque la session est en mode hors connexion. |
| `E_PF_GAMESAVE_NETWORK_FAILURE` | `0x89237005` | Renvoyé par `PFGameSaveFilesUploadWithUiAsync()` après une défaillance réseau temporaire alors que la session est toujours connectée au cloud. Une nouvelle tentative ultérieure est sans risque. |
| `E_PF_GAMESAVE_DEVICE_NO_LONGER_ACTIVE` | `0x89237007` | Renvoyé par `PFGameSaveFilesUploadWithUiAsync()` lorsque cet appareil n'est plus l'appareil actif (un autre appareil a pris le relais). |
| `E_PF_GAMESAVE_DISK_FULL` | `0x89237008` | Espace disque local insuffisant pour télécharger les données de sauvegarde. Invitez l'utilisateur à libérer de l'espace et à réessayer. |
| `E_PF_GAMESAVE_OPERATION_IN_PROGRESS` | `0x89237009` | Une opération en conflit est déjà en cours pour cet utilisateur : `PFGameSaveFilesUploadWithUiAsync()` a été appelée alors qu'un autre chargement ou une réinitialisation du cloud était en cours, `PFGameSaveFilesAddUserWithUiAsync()` a été appelée alors qu'une réinitialisation du cloud était en cours, ou `PFGameSaveFilesResetCloudAsync()` a été appelée alors qu'une autre réinitialisation, un chargement ou un téléchargement était en cours. Rien n'a été démarré ni modifié ; attendez la fin de l'opération en cours, puis réessayez. Disponible à partir du GDK d'octobre 2026 (2610). |
| `E_PF_GAMESAVE_LOCAL_FILE_UNAVAILABLE` | `0x8923700A` | Renvoyé par `PFGameSaveFilesUploadWithUiAsync()` lorsqu'un fichier de sauvegarde local ne peut pas être lu pendant le chargement, par exemple parce que le titre l'a encore ouvert en écriture. Rien n'a été validé dans le cloud. Temporaire : réessayez une fois que le titre a cessé d'écrire dans ce fichier. Disponible dans le GDK d'octobre 2025 (2510) QFE5, le GDK d'avril 2026 (2604) QFE6 et le GDK d'octobre 2026 (2610). |
| `E_PF_GAMESAVE_DOWNLOAD_IN_PROGRESS` | `0x89237006` | `PFGameSaveFilesUploadWithUiAsync()` a été appelée avant que `PFGameSaveFilesAddUserWithUiAsync()` n'ait terminé la synchronisation initiale. |
| `E_PF_GAMESAVE_USER_NOT_ADDED` | `0x89237003` | Une API a été appelée avant que `PFGameSaveFilesAddUserWithUiAsync()` ne se termine pour cet utilisateur. |
| `E_PF_GAMESAVE_USER_ALREADY_ADDED` | `0x89237002` | `PFGameSaveFilesAddUserWithUiAsync()` a été appelée de nouveau pour un utilisateur déjà ajouté. |
| `E_PF_GAMESAVE_ALREADY_INITIALIZED` | `0x89237001` | `PFGameSaveFilesInitialize()` a été appelée deux fois sans appel intermédiaire à `PFGameSaveFilesUninitializeAsync()`. |
| `E_PF_GAMESAVE_NOT_INITIALIZED` | `0x89237000` | Une API a été appelée avant `PFGameSaveFilesInitialize()`. |

Pour savoir comment ces résultats sont produits par l'interface utilisateur système intégrée (hors processus) par rapport à vos propres rappels, consultez [Rappels d'interface utilisateur de Game Saves](/fr/services/playfab/player-progression/game-saves/ui-callbacks#in-process-vs-out-of-process-system-ui).

## Autres scénarios d'état de connexion

L'API `PFGameSaveFilesIsConnectedToCloud()` est particulièrement utile, car la déconnexion peut se produire de plusieurs façons :

* **Réseau indisponible pendant la synchronisation** : l'utilisateur choisit explicitement de jouer hors connexion
* **Changement d'appareil actif** : un autre appareil devient l'appareil actif, ce qui fait automatiquement passer cet appareil en mode hors connexion

Utilisez cette API avant de tenter des opérations cloud afin de fournir des retours appropriés à l'utilisateur.

## Bonnes pratiques pour la prise en charge du mode hors connexion

1. **Implémentez toujours des rappels d'échec de synchronisation** pour gérer correctement les problèmes réseau
2. **Vérifiez régulièrement l'état de la connexion** à l'aide de `PFGameSaveFilesIsConnectedToCloud()` avant de tenter des opérations cloud
3. **Informez les joueurs** lorsque le jeu fonctionne en mode hors connexion afin qu'ils comprennent que les sauvegardes ne seront pas synchronisées
4. **Proposez des options de nouvelle tentative** lorsque la connectivité réseau est rétablie
5. **Les sauvegardes locales fonctionnent toujours** : les joueurs peuvent continuer à jouer quel que soit l'état du réseau
6. **Surveillez les déconnexions** : n'oubliez pas que des appareils peuvent être déconnectés lorsqu'un autre appareil devient actif

## Comportement des chargements en mode connecté

Même en mode connecté, les chargements peuvent échouer en raison de problèmes réseau ou de limites de débit. Dans ce cas, le rappel `XAsyncBlock` ne se déclenche pas immédiatement : l'opération asynchrone est suspendue pendant que le système attend la réponse de l'utilisateur via la [machine à états des rappels d'interface utilisateur](/fr/services/playfab/player-progression/game-saves/ui-callbacks#how-the-state-machine-works) :

1. Le `PFGameSaveFilesUiSyncFailedCallback` se déclenche avec les détails de l'erreur.
2. Le rappel `XAsyncBlock` ne se déclenche pas encore : l'opération est suspendue pendant que le système attend une réponse.
3. Si l'utilisateur sélectionne `Retry`, le chargement est retenté. S'il échoue à nouveau, le rappel se déclenche de nouveau et l'utilisateur doit répondre de nouveau.
4. Si l'utilisateur sélectionne `Cancel`, le rappel `XAsyncBlock` se déclenche avec `E_PF_GAMESAVE_USER_CANCELLED`.
5. Si une nouvelle tentative réussit, le rappel `XAsyncBlock` se déclenche avec `S_OK`.

Le jeu peut appeler de nouveau `PFGameSaveFilesUploadWithUiAsync()` ultérieurement, une fois le réseau rétabli.

<Note>
  **En mode in-process, ne proposez pas `Use Offline` dans l'invite d'échec de synchronisation pendant un chargement.** Le chargement déclenche le même `PFGameSaveFilesUiSyncFailedCallback` que la synchronisation initiale ; le SDK ne restreint donc pas les choix. Cependant, si votre jeu répond `UseOffline` à un échec de chargement, le chargement échoue avec `E_ABORT` (et les builds de débogage déclenchent une assertion). Ne proposez que `Retry` et `Cancel` dans ce cas.
</Note>

## Quand un chargement met la session hors connexion

Un chargement ne modifie normalement pas le mode de connexion, mais il peut se terminer avec la session hors connexion dans les cas suivants. Dans chacun d'eux, le chargement se termine avec `E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD`, et `PFGameSaveFilesIsConnectedToCloud()` renvoie ensuite `false`.

* **La session était déjà hors connexion.** Le chargement ne s'exécute pas et se termine avec `E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD`, même si le réseau a été rétabli.
* **Le cloud contient une sauvegarde plus récente.** Si le service signale, lors de la finalisation du chargement, qu'une sauvegarde plus récente a été validée depuis un autre appareil, Game Saves met la session hors connexion, déclenche le rappel de changement d'appareil actif et termine le chargement avec `E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD`.
* **Le joueur choisit `Use Offline` dans l'invite de reverrouillage.** Si un chargement précédent a validé ses données mais a échoué ensuite, le chargement suivant doit d'abord réacquérir le verrou de sauvegarde. Une invite d'échec de synchronisation survenant pendant cette étape peut recevoir la réponse `UseOffline`, ce qui met la session hors connexion et termine le chargement avec `E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD`.

Pour vous reconnecter, appelez de nouveau `PFGameSaveFilesAddUserWithUiAsync()`.

## Annulation d'un chargement

Un chargement peut être annulé de la même manière que la synchronisation initiale : l'utilisateur peut sélectionner `Cancel` dans l'interface utilisateur de **progression** pendant le chargement, ou dans l'invite d'**échec de synchronisation** si le chargement a rencontré une erreur. Dans les deux cas, `PFGameSaveFilesUploadWithUiAsync()` se termine avec `E_PF_GAMESAVE_USER_CANCELLED` (`0x800704C7`) et la sauvegarde n'est pas chargée. Ses résultats finaux sont **réussite**, **annulé** ou **échec** (où `E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD` signifie que la session est désormais hors connexion ; consultez [Quand un chargement met la session hors connexion](#when-an-upload-takes-the-session-offline)). Traitez `E_PF_GAMESAVE_USER_CANCELLED` séparément des autres défaillances afin de distinguer « le joueur a annulé » de « le chargement a échoué ». Si votre jeu annule lui-même le chargement avec `XAsyncCancel`, celui-ci se termine avec `E_ABORT` plutôt qu'avec `E_PF_GAMESAVE_USER_CANCELLED`.


## Related topics

- [Démarrage rapide de Game Saves](/fr/services/playfab/player-progression/game-saves/quickstart.md)
- [FAQ sur la gestion des erreurs de Game Saves](/fr/services/playfab/player-progression/game-saves/error-handling-faq.md)
- [Rappels d'interface utilisateur de Game Saves](/fr/services/playfab/player-progression/game-saves/ui-callbacks.md)
- [Comprendre le flux de synchronisation de Game Saves](/fr/build/core-features/common/game-save/game-saves-syncing.md)
- [Vue d'ensemble de l'API XGameSave](/fr/build/core-features/common/game-save/xgamesave.md)