> ## 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. # Vue d'ensemble de l'API XGameSave > Référence de l'API XBOX XGameSave couvrant le modèle de conteneurs et de blobs, l'initialisation du fournisseur, les handles de mise à jour, les mises à jour atomiques et les diagrammes du flux de synchronisation. Cet article explique le modèle de conteneurs et de blobs, et couvre l'initialisation du fournisseur, la fermeture du fournisseur et le cycle de vie du handle de mise à jour. Il décrit le comportement des mises à jour atomiques et comprend des diagrammes du flux de synchronisation. Cet article présente également les contraintes de taille de fichier et de quota, ainsi que les pratiques exemplaires et la FAQ. L'API `XGameSave` vous permet de gérer des blobs et des conteneurs pour gérer les données de Game Saves. Nous recommandons [XGameSaveFiles](/fr-CA/build/core-features/common/game-save/xgamesavefiles) pour Game Saves dans les titres du Microsoft Game Development Kit (GDK). Utilisez `XGameSave` si `XGameSaveFiles` n'est pas une option. Pour la référence de l'API système de XGameSave, consultez [XGameSave (contenu de l'API)](/fr-CA/reference/system/xgamesave/xgamesave_members). Les termes suivants reviennent souvent dans `XGameSave`. * **Verrou** : Mécanisme qui accorde un accès exclusif aux Game Saves d'un titre pour un utilisateur donné sur l'appareil qu'il utilise activement. Il garantit qu'aucun autre appareil ne peut modifier les Game Saves de l'utilisateur pendant que le verrou est détenu. * Par exemple, si un utilisateur joue au titre T sur l'appareil A, celui-ci détient un verrou sur le titre T pour cet utilisateur. * **Fournisseur** : Processus intermédiaire qui communique avec le système Game Save et qui est responsable de la gestion des données du titre. Le fournisseur gère également le verrou d'un utilisateur sur un appareil. * **Conteneurs** : Équivalents des dossiers. * **Blobs** : Équivalents des fichiers individuels. ## Gestion du fournisseur Pour acquérir un espace de stockage, le jeu doit initialiser un fournisseur. Après la connexion, le titre tente d'acquérir un verrou sur le stockage infonuagique du titre en appelant `XGameSaveInitializeProvider` ou `XGameSaveInitializeProviderAsync`. Si le titre ne parvient pas à se synchroniser à partir du nuage en raison d'une perte de connexion, déterminez si les utilisateurs peuvent continuer à jouer en mode hors ligne. Le titre doit fermer le fournisseur avec [XGameSaveCloseProvider](/fr-CA/reference/system/xgamesave/functions/xgamesavecloseprovider) lorsqu'il est suspendu ou arrêté. Le fournisseur ne peut pas être réutilisé d'un cycle de suspension-reprise à l'autre. Ce problème s'applique uniquement à `XGameSave`. `XGameSaveFiles` ferme automatiquement le fournisseur. ## Gestion des conteneurs Pour éviter la perte de données lors de l'accès aux conteneurs, par exemple en créant des conteneurs avant la fin de la synchronisation, appelez `XGameSaveEnumerateContainerInfo` ou `XGameSaveEnumerateContainerInfoByName` pour afficher les conteneurs d'un utilisateur. Utilisez `XGameSaveCreateContainer` pour obtenir un handle de conteneur vers un conteneur nouveau ou existant. Si le conteneur existe déjà, son handle est fourni. Si le conteneur n'existe pas, un nouveau conteneur est créé et son handle est fourni. Utilisez `XGameSaveDeleteContainer` pour supprimer un conteneur. Tous les blobs du conteneur sont également supprimés. Pour éviter les fuites de handles, fermez tous les handles de conteneur avec `XGameSaveCloseContainer` lorsque le conteneur n'est plus utilisé ou lorsque le titre est suspendu ou arrêté. ## Gestion des blobs La manipulation des données d'un conteneur s'effectue en appelant `XGameSaveCreateUpdate`. Les détails suivants décrivent comment `XGameSaveUpdate` gère les modifications de blobs dans un conteneur et comment chaque mise à jour est créée, modifiée et soumise. * Une mise à jour s'applique à un seul conteneur. * Une mise à jour peut écrire au plus GS\_MAX\_BLOB\_SIZE (16 Mo). * Plusieurs blobs peuvent être modifiés en une seule mise à jour. * Un même blob ne peut faire l'objet que d'une seule modification par mise à jour. * La soumission d'une mise à jour consomme le handle `XGameSaveUpdate`. Fermez le handle, que la soumission ait réussi ou échoué. * Les mises à jour sont atomiques. Si une partie échoue, la mise à jour entière échoue. * `XGameSaveCreateUpdate` crée un contexte de mise à jour pour stocker toutes vos modifications de blobs. * `XGameSaveSubmitBlobWrite` écrit des données dans un blob nouveau ou existant et nécessite un contexte de mise à jour. * `XGameSaveSubmitBlobDelete` supprime le blob. * `XGameSaveSubmitUpdate` soumet le contexte de mise à jour. * `XGameSaveCloseUpdate` ferme le handle de mise à jour. Le titre l'appelle après chaque soumission pour éviter les fuites. * Utilisez `XGameSaveEnumerateBlobInfo` ou `XGameSaveEnumerateBlobInfoByName` pour accéder à tous les blobs d'un conteneur. Les données écrites dans les blobs sont représentées en `Base64` lorsqu'elles sont exportées en XML. ## Implémentation Les étapes suivantes présentent le flux général d'une implémentation de `XGameSave`. 1. Au démarrage ou à la reprise du titre, initialisez le fournisseur. 2. Énumérez et créez des handles de conteneur. 3. Soumettez périodiquement des `XGameSaveUpdates` contenant des modifications de blobs et nettoyez le handle de mise à jour à la soumission. 4. Fermez les handles de conteneur et de fournisseur lors de la suspension ou de l'arrêt du titre. Appelez `XGameSaveInitializeProvider` au démarrage du titre et lors de sa reprise. Cet appel garantit que le fournisseur s'initialise correctement et reste actif pendant l'exécution du titre. S'il n'est pas appelé, le titre peut se comporter de façon imprévisible. ### Exemple de code Pour un exemple de code qui montre comment utiliser les API `XGameSave`, consultez [GameSaveCombo](https://learn.microsoft.com/samples/microsoft/xbox-gdk-samples/gamesavecombo/). ## Flux de Game Saves Voici un organigramme du flux simplifié de Game Saves. Il est expliqué ci-dessous. Organigramme du processus de synchronisation simplifié de Game Saves. ### Démarrage du titre Le démarrage du titre a lieu lorsque l'utilisateur lance ou reprend le titre. ### Connexion de l'utilisateur Le titre lance la connexion de l'utilisateur. C'est également à ce moment que vous appelez `XGameSaveInitializeProvider`. Pour en savoir plus sur la configuration des utilisateurs, consultez [Modèles d'utilisateur](/fr-CA/build/core-features/common/game-save/game-saves-developer-guide#user-models). ### Vérification de la connexion Le titre détermine s'il peut se connecter au réseau XBOX. S'il ne le peut pas, il vous revient d'activer le [mode hors ligne](/fr-CA/build/core-features/common/game-save/game-saves-syncing#connection-check) pour votre titre. ### Vérification de la propriété des données L'appareil vérifie si l'utilisateur joue actuellement sur d'autres appareils. Un seul appareil à la fois peut accéder aux données de l'utilisateur pour un titre donné. ### Synchronisation des données avec le nuage L'appareil synchronise les données du stockage local de Game Saves avec le nuage. En cas de conflit, le système affiche à l'utilisateur une boîte de dialogue de résolution de conflit. Boîte de dialogue : [Laquelle voulez-vous utiliser?](/fr-CA/build/core-features/common/game-save/game-saves-dialogues#which-one-do-you-want-to-use) Lorsque les données de l'appareil sont plus récentes que celles du nuage, le titre invite l'utilisateur à choisir entre les données locales et les données du nuage. ### Boucle de jeu Le titre peut librement lire et écrire dans le stockage local de Game Saves. ### Fin de la session de jeu Lorsque la session de jeu prend fin, le système tente automatiquement de téléverser les données dans le nuage. Assurez-vous que votre titre appelle `XGameSaveUninitializeProvider` pendant son flux de fermeture afin de ne pas laisser de fournisseur initialisé. Un arrêt structuré garantit que les données sont sauvegardées proprement avant la fermeture. Pour des renseignements détaillés sur la synchronisation, consultez [Comprendre le flux de synchronisation de Game Saves](/fr-CA/build/core-features/common/game-save/game-saves-syncing). ## Limites et quotas ### Limites `XGameSaveUpdate` limite chaque mise à jour à 16 Mo. Par conséquent, `XGameSave` ne peut gérer que des mises à jour de fichiers individuels d'au plus 16 Mo. Cette limite diffère de celle de `XGameSaveFiles`, qui prend en charge des fichiers d'au plus 64 Mo. ### Quotas La quantité maximale de données qu'un utilisateur peut sauvegarder par titre est de 256 Mo. Utilisez [XGameSaveGetRemainingQuota](/fr-CA/reference/system/xgamesave/functions/xgamesavegetremainingquota) pour obtenir le quota restant. Pour obtenir une extension de stockage pour votre titre, communiquez avec votre gestionnaire de partenaires développeurs (DPM). ## Pratiques exemplaires * Ne sauvegardez pas des données pour ensuite interroger et redemander immédiatement les mêmes données. * Les dépendances de données entre conteneurs ne sont pas fiables. Chaque appel à `XGameSaveSubmitUpdate` applique toutes les modifications de façon atomique, ou aucune. * Plus vous utilisez de blobs par appel de mise à jour, plus il faut de temps pour effectuer les opérations atomiques du système de fichiers nécessaires au stockage des données. ## FAQ ### Je mets à niveau mon implémentation de Game Saves. Quelle est la bonne approche? Utilisez [XGameSaveFiles](/fr-CA/build/core-features/common/game-save/xgamesavefiles). ### Puis-je utiliser XGameSave avec XGameSaveFiles? Oui. Toutefois, faites-le uniquement pour des migrations. Pour des renseignements détaillés, consultez [Interopérabilité entre XGameSave et XGameSaveFiles](/fr-CA/build/core-features/common/game-save/game-saves-walkthroughs-and-samples#interop-between-xgamesave-and-xgamesavefiles). ### Dans quel chemin de fichier XGameSave sauvegarde-t-il? **Console** : Un chemin temporaire est fourni pendant que le titre est actif. Les fichiers de la console ne sont pas accessibles au moyen de l'Explorateur de fichiers. **PC** : `%AppData%\Local\Packages\\SystemAppData\wgs\_\` Sachez que le chemin PC de `XGameSave` est différent de celui de `XGameSaveFiles`. Ce dernier utilise `xgs`. ### Puis-je indiquer le chemin où les données doivent être sauvegardées? Oui, mais uniquement sur PC. Nous recommandons cette approche seulement si vous portez votre solution à partir d'un autre titre. Cette solution utilise les [sauvegardes infonuagiques sans code](/fr-CA/build/core-features/common/game-save/game-saves-walkthroughs-and-samples#porting-previous-titles-to-pc-game-saves-with-no-code-cloud-saves). ### Y a-t-il une situation où j'utiliserais Sync on Demand? Non. Cette fonctionnalité existe pour des raisons de prise en charge héritée. ## Documentation de référence de l'API * [XGameSave (contenu de l'API)](/fr-CA/reference/system/xgamesave/xgamesave_members) * Fonctions * [XGameSaveCloseProvider](/fr-CA/reference/system/xgamesave/functions/xgamesavecloseprovider) * [XGameSaveGetRemainingQuota](/fr-CA/reference/system/xgamesave/functions/xgamesavegetremainingquota) ## Voir aussi [Table des matières de Game Saves](/fr-CA/build/core-features/common/game-save/game-saves-toc) ## Related topics - [Vue d'ensemble de l'API C Services - PFLocalization.h](/fr/services/playfab/api-references/c/pflocalization/pflocalization_members.md) - [Vue d'ensemble de l'API C Services - PFLeaderboards.h](/fr/services/playfab/api-references/c/pfleaderboards/pfleaderboards_members.md) - [Vue d'ensemble de l'API C Services - PFStatistics.h](/fr-CA/services/playfab/api-references/c/pfstatistics/pfstatistics_members.md) - [Vue d'ensemble de l'API C Services - PFPlatformSpecific.h](/fr-CA/services/playfab/api-references/c/pfplatformspecific/pfplatformspecific_members.md) - [Vue d'ensemble de l'API C Services - PFPushNotifications.h](/fr/services/playfab/api-references/c/pfpushnotifications/pfpushnotifications_members.md)