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

# Identité de l'utilisateur et XUser

> Identité de l'utilisateur et XUser

XBOX One gère l'identité des utilisateurs qui interagissent avec le jeu au moyen d'un objet `XUser`. Chaque instance `XUser` représente un utilisateur connecté au jeu. Chaque utilisateur est représenté par `XUserHandle`. Les jeux peuvent effectuer les opérations suivantes à l'aide de `XUserHandle`.

* Interroger l'état de connexion aux services XBOX.
* Récupérer le gamertag des utilisateurs.
* Récupérer l'image de joueur des utilisateurs.
* Déterminer la tranche d'âge des utilisateurs.
* Déterminer les privilèges accordés à l'utilisateur, par exemple s'il est autorisé à participer à des communications en temps réel ou à des sessions multijoueurs.
* Récupérer un jeton authentifié.

## Identificateurs XUser

Deux identificateurs différents sont associés à un `XUser` donné : l'ID local et l'ID des services XBOX (XUID).

L'*ID local* est un identificateur qui reste associé à l'utilisateur pendant toute la durée de vie de cet utilisateur dans la session de jeu. Utilisez l'ID local dans tous les processus que le jeu lance ou si le jeu appelle `XLaunchNewGame`.  Toutefois, n'utilisez pas<br />l'ID local pour identifier un utilisateur d'une session de jeu à l'autre.

Pour obtenir l'ID local d'un utilisateur, utilisez la fonction `XUserGetLocalId`.

L'*ID des services XBOX (XUID)* est l'identificateur qui doit être utilisé lors des communications avec les services XBOX ou lors de l'appel d'une interface utilisateur appelable par le titre (TCUI). Pour obtenir le XUID d'un utilisateur, utilisez la fonction `XUserGetId`. Le consentement de l'utilisateur peut être nécessaire pour obtenir le XUID. Si ce consentement est requis et n'est pas accordé, `XUserGetId` renvoie E\_GAMEUSER\_RESOLVE\_USER\_ISSUE\_REQUIRED. Pour résoudre le problème et recueillir le consentement, les jeux doivent alors appeler `XUserResolveIssueWithUiAsync`.

## États XUser

Les utilisateurs peuvent se trouver dans l'un des trois états suivants : connectés aux services XBOX, en cours de déconnexion des services XBOX ou complètement déconnectés. Les jeux peuvent interroger cet état pour un utilisateur donné à l'aide de la fonction `XUserGetState`. Les jeux peuvent également s'inscrire aux notifications de modification à l'aide de la fonction `XUserRegisterForChangeEvent`.

Ne jugez pas la connectivité réseau en fonction de l'état `XUser`. Si `XUserState` est `SignedIn`, cela indique qu'à un moment donné, l'utilisateur a été authentifié auprès des services XBOX et peut être traité comme un utilisateur actif. Toutefois, le réseau peut ne pas être connecté.

## Ajout ou suppression d'utilisateurs dans le jeu

Contrairement au modèle de l'ERA XBOX One, un jeu ne peut interagir qu'avec les utilisateurs qu'il a demandés en appelant la fonction `XUserAddAsync`. Par exemple, supposons que deux utilisateurs sont connectés à la console : l'utilisateur A et l'utilisateur B.

1. Quelqu'un lance le jeu. Dans ce scénario, peu importe qui l'a fait.
2. Le jeu s'inscrit aux modifications d'état des utilisateurs à l'aide de `XUserRegisterForChangeEvent`.
3. Le jeu appelle `XUserAddAsync`, et l'utilisateur A se connecte au jeu.
4. Le jeu dispose maintenant d'un `XUserHandle` qui représente l'utilisateur A.
5. Depuis le guide, l'utilisateur B choisit de se déconnecter.
6. Aucun événement de modification de connexion n'est déclenché pour le jeu. Le jeu n'a jamais eu connaissance de l'utilisateur B.
7. Depuis le guide, l'utilisateur A choisit de se déconnecter.
8. Le jeu reçoit un événement de modification indiquant d'abord que l'utilisateur A est en cours de déconnexion, puis, finalement, un autre événement indiquant que l'utilisateur A est maintenant déconnecté.

Si les jeux ont la possibilité d'ajouter des utilisateurs, il n'existe que quelques façons de supprimer des utilisateurs, à l'aide de l'une des méthodes suivantes.

* Le jeu peut fermer tous les handles qui représentent l'utilisateur à l'aide de la fonction `XUserCloseHandle`.
* L'utilisateur utilise le guide pour se déconnecter de la console.
* L'utilisateur se connecte sur un autre appareil.

## Types d'utilisateurs

XBOX One prend en charge deux types d'utilisateurs : les joueurs XBOX et les invités.

Les *joueurs XBOX* disposent de toutes les fonctionnalités en tant qu'utilisateurs du système. Ils sont initialement créés en ajoutant un nouveau compte dans le sélecteur de compte, une interface utilisateur fournie par le système pour connecter les utilisateurs. Les joueurs XBOX restent sur la console jusqu'à ce qu'ils soient explicitement supprimés à l'aide de l'application Paramètres.

Les *invités XBOX* disposent d'une seule session sur une console. Ils sont créés lorsqu'ils choisissent de jouer en tant qu'invité dans le sélecteur de compte et sont parrainés par un autre joueur XBOX connecté. Les invités restent présents jusqu'à ce qu'ils se déconnectent, jusqu'à ce que le joueur XBOX parrain se déconnecte ou jusqu'à ce que la console soit éteinte.

Les jeux qui souhaitent autoriser les invités doivent spécifier l'option `AllowGuest` lorsqu'ils appellent `XUserAddAsync`.

## Modèles d'ajout d'utilisateurs<a id="pattern_for_adding" />

Les jeux doivent toujours tenter d'établir un utilisateur initial. Il existe deux façons principales d'y parvenir.

#### Option 1 : déterminer l'utilisateur le plus tôt possible sans afficher d'interface utilisateur

1. Appelez `XUserAddAsync` à l'aide de `AddDefaultUserSilently`. Cette fonction tente de déterminer qui a lancé le jeu sans afficher d'interface utilisateur.
2. L'appel à `XUserAddAsync` peut échouer avec `E\_GAMEUSER\_NO\_DEFAULT\_USER`. Dans ce cas, personne n'était connecté lors du premier lancement du jeu. Pour établir l'utilisateur initial, le jeu doit appeler `XUserAddAsync` sans utiliser l'indicateur `AddDefaultUserSilently`. Contrairement à l'option « silencieuse », cet appel garantit que tous les problèmes de consentement sont entièrement résolus et que, si l'appel réussit, l'utilisateur est connecté aux services XBOX. Le jeu peut créer un contexte XBOX pour cet utilisateur.

#### Option 2 : déterminer l'utilisateur avec la possibilité d'afficher une interface utilisateur

Appelez `XUserAddAsync` à l'aide de `AddDefaultUserAllowingUI`. Comme l'option précédente (« silencieuse »), cette fonction tente de déterminer qui a lancé le jeu. Contrairement à l'option précédente, si l'utilisateur par défaut ne peut pas être déterminé, elle affiche une interface utilisateur permettant aux joueurs de se connecter ou de se sélectionner. Si `XUserAddResult` réussit, le jeu dispose d'un utilisateur entièrement connecté aux services XBOX et peut créer un contexte XBOX pour cet utilisateur.

Pour obtenir un exemple de code illustrant ces étapes, consultez [Procédure : bonne pratique pour connecter un utilisateur](/fr/build/core-features/common/user/xuser_howto_best_practice_signing_in).

## Gestion de XUserHandle

Chaque `XUserHandle` représente un utilisateur. Toutefois, il est possible que plusieurs handles de ce type représentent chacun le même utilisateur. Les jeux doivent utiliser le modèle de base suivant.

1. Gérez une collection d'instances `XUserHandle` qui représente l'ensemble des utilisateurs qui intéressent le jeu.
2. Inscrivez-vous aux modifications d'état `XUser` en appelant `XUserRegisterForChangeEvent`. Lorsque vous constatez qu'un utilisateur est en cours de déconnexion, mettez à jour votre collection d'utilisateurs.
3. Lorsque vous obtenez un nouveau `XUserHandle` à partir de `XUserAddAsync`, vérifiez s'il représente un nouvel utilisateur. Vous pouvez comparer directement les handles à l'aide de `XUserCompare`. Vous pouvez également effectuer la comparaison à l'aide de l'ID local obtenu en appelant `XUserGetLocalId`.
4. Si plusieurs instances `XUserHandle` représentent le même utilisateur, utilisez `XUserCloseHandle` pour supprimer les instances en trop.

L'*ID local* est un identificateur qui reste associé à l'utilisateur pendant toute la durée de vie de cet utilisateur dans la session de jeu. Utilisez l'ID local dans tous les processus que le jeu lance ou si le jeu appelle `XLaunchNewGame`.  Toutefois, n'utilisez pas l'ID local pour identifier un utilisateur d'une session de jeu à l'autre.


## Related topics

- [XR052 Emplacement, itinérance et dépendances de l'état utilisateur et des sauvegardes de titre](/fr-CA/publishing/certification/fma/xr-052.md)
- [XR052 Emplacement, itinérance et dépendances de l'état utilisateur et des sauvegardes du titre](/fr/publishing/certification/fma/xr-052.md)
- [XR-052 État utilisateur et emplacement des sauvegardes de titre, itinérance et dépendances](/fr/publishing/certification/xr/xr-052.md)
- [XR-052 Emplacement, itinérance et dépendances de l'état utilisateur et des sauvegardes de titre](/fr-CA/publishing/certification/xr/xr-052.md)
- [XR-112 Établissement d'un utilisateur et d'une manette lors de l'activation initiale et de la reprise](/fr/publishing/certification/xr/xr-112.md)