> ## 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 infonuagiques lorsque le réseau est rétabli.

Game Saves est conçu pour fonctionner aussi bien en ligne que 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 nuage

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

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

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

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 le mode dans lequel le système fonctionne.

## Gestion des défaillances réseau pendant 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 pendant 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 de 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()` - Retourne le chemin du dossier de sauvegarde local

### API aux fonctionnalités limitées

* `PFGameSaveFilesUploadWithUiAsync()` - Retourne `S_OK` immédiatement, mais la fin de l'opération asynchrone retourne `E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD`
* `PFGameSaveFilesGetRemainingQuota()` - Retourne `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 une reconnexion
* Il n'est pas nécessaire de réinitialiser complètement le système Game Saves
* L'interface utilisateur d'échec s'affichera de 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 retourne 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? | Traitement recommandé |
| - | - | - | - | - | - |
| **Connecté** | La synchronisation s'est terminée avec succès | `S_OK` | `true` | Oui | Permettez de jouer; les sauvegardes sont synchronisées avec le nuage. |
| **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 | Permettez de jouer avec les sauvegardes locales; informez le 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`) | s.o. | **Non** | **Bloquez le jeu** ou revenez à un menu sécuritaire; il n'y a aucun dossier pour sauvegarder ou charger. |
| **Annulé par le jeu** | Le jeu a appelé `XAsyncCancel` sur le `XAsyncBlock` | `E_ABORT` (`0x80004004`) | s.o. | **Non** | Comme pour une annulation par le joueur; il n'y a aucun dossier pour sauvegarder ou charger. |

Points clés :

* **Le mode hors connexion est un résultat réussi, et non une erreur.** On n'y accède 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 ou techniques sont signalées par l'interface utilisateur d'échec de synchronisation**, et ne sont pas retournées directement par `PFGameSaveFilesAddUserWithUiAsync`. L'utilisateur (ou votre réponse automatique) choisit alors `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 tout échec qui ne laisse aucun dossier) comme *ne pas permettre de jouer*.
* **L'annulation par le joueur et l'annulation par le jeu retournent 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`, celle-ci 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 mène pas automatiquement à une invite d'échec de synchronisation « Use Offline ». Si vous souhaitez offrir une expérience du type « rejeter le conflit tout en continuant à 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-CA/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 retourné |
| - | - | - |
| `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` | Retourné par `PFGameSaveFilesUploadWithUiAsync()` et `PFGameSaveFilesGetRemainingQuota()` lorsque la session est en mode hors connexion. |
| `E_PF_GAMESAVE_NETWORK_FAILURE` | `0x89237005` | Retourné par `PFGameSaveFilesUploadWithUiAsync()` après une défaillance réseau temporaire alors que la connexion au nuage est maintenue. Il est sécuritaire de réessayer plus tard. |
| `E_PF_GAMESAVE_DEVICE_NO_LONGER_ACTIVE` | `0x89237007` | Retourné 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 contradictoire est déjà en cours pour cet utilisateur : `PFGameSaveFilesUploadWithUiAsync()` a été appelée alors qu'un autre téléversement ou une réinitialisation infonuagique est en cours, `PFGameSaveFilesAddUserWithUiAsync()` a été appelée alors qu'une réinitialisation infonuagique est en cours, ou `PFGameSaveFilesResetCloudAsync()` a été appelée alors qu'une autre réinitialisation, un téléversement ou un téléchargement est 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` | Retourné par `PFGameSaveFilesUploadWithUiAsync()` lorsqu'un fichier de sauvegarde local ne peut pas être lu pendant le téléversement, par exemple parce que le titre l'a toujours ouvert en écriture. Rien n'a été validé dans le nuage. 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()` ait terminé la synchronisation initiale. |
| `E_PF_GAMESAVE_USER_NOT_ADDED` | `0x89237003` | Une API a été appelée avant que `PFGameSaveFilesAddUserWithUiAsync()` soit terminée 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-CA/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 infonuagiques afin de fournir une rétroaction appropriée à l'utilisateur.

## Pratiques exemplaires pour la prise en charge hors connexion

1. **Implémentez toujours les rappels d'échec de synchronisation** pour gérer les problèmes réseau de façon appropriée
2. **Vérifiez régulièrement l'état de la connexion** à l'aide de `PFGameSaveFilesIsConnectedToCloud()` avant de tenter des opérations infonuagiques
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. **Offrez 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 téléversements en mode connecté

Même en mode connecté, les téléversements 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 au moyen de la [machine à états des rappels d'interface utilisateur](/fr-CA/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 téléversement est retenté. S'il échoue de 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()` plus tard, lorsque le réseau est rétabli.

<Note>
  **En processus, n'offrez pas `Use Offline` dans l'invite d'échec de synchronisation pendant qu'un téléversement est en cours.** Le téléversement déclenche le même `PFGameSaveFilesUiSyncFailedCallback` que la synchronisation initiale, de sorte que le SDK ne restreint pas les choix. Toutefois, si votre jeu répond par `UseOffline` à un échec de téléversement, le téléversement échoue avec `E_ABORT` (et les builds de débogage déclenchent une assertion). N'offrez que `Retry` et `Cancel` dans ce cas.
</Note>

## Lorsqu'un téléversement met la session hors connexion

Un téléversement 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 téléversement se termine avec `E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD`, et `PFGameSaveFilesIsConnectedToCloud()` retourne ensuite `false`.

* **La session était déjà hors connexion.** Le téléversement 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 nuage contient une sauvegarde plus récente.** Si le service signale, lors de la finalisation du téléversement, qu'une sauvegarde plus récente a été validée à partir d'un autre appareil, Game Saves met la session hors connexion, déclenche le rappel de changement d'appareil actif et termine le téléversement avec `E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD`.
* **Le joueur choisit `Use Offline` dans l'invite de reverrouillage.** Si un téléversement antérieur a validé ses données, mais a échoué par la suite, le téléversement suivant doit d'abord réacquérir le verrou de sauvegarde. Une invite d'échec de synchronisation pendant cette étape peut recevoir la réponse `UseOffline`, ce qui met la session hors connexion et termine le téléversement avec `E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD`.

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

## Annulation d'un téléversement

Un téléversement 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 que le téléversement est en cours, ou sélectionner `Cancel` dans l'invite d'**échec de synchronisation** si le téléversement a rencontré une erreur. Dans les deux cas, `PFGameSaveFilesUploadWithUiAsync()` se termine avec `E_PF_GAMESAVE_USER_CANCELLED` (`0x800704C7`) et la sauvegarde n'est pas téléversé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 [Lorsqu'un téléversement met la session hors connexion](#when-an-upload-takes-the-session-offline)). Traitez `E_PF_GAMESAVE_USER_CANCELLED` séparément des autres échecs afin de pouvoir distinguer « le joueur a annulé » de « le téléversement a échoué ». Si votre jeu annule lui-même le téléversement 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-CA/services/playfab/player-progression/game-saves/quickstart.md)
- [FAQ sur la gestion des erreurs de Game Saves](/fr-CA/services/playfab/player-progression/game-saves/error-handling-faq.md)
- [Rappels d'interface utilisateur de Game Saves](/fr-CA/services/playfab/player-progression/game-saves/ui-callbacks.md)
- [Comprendre le flux de synchronisation de Game Saves](/fr-CA/build/core-features/common/game-save/game-saves-syncing.md)
- [Vue d'ensemble de Game Saves](/fr-CA/build/core-features/common/game-save/game-saves-overview.md)