> ## 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 de `XUser` représente un utilisateur connecté au jeu. Chaque utilisateur est représenté par `XUserHandle`. Les jeux peuvent faire ce qui suit à l'aide de `XUserHandle`.

* Interroger l'état de connexion aux XBOX services.
* Récupérer le gamertag des utilisateurs.
* Récupérer l'image de joueur des utilisateurs.
* Déterminer le groupe d'âge des utilisateurs.
* Déterminer quels privilèges sont accordés à l'utilisateur qui 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 XBOX services (XUID).

L'*ID local* est un identificateur qui reste associé à l'utilisateur pendant toute la durée de vie de cet utilisateur au sein de la session de jeu. Utilisez l'ID local dans tous les processus que le jeu génère 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 Xbox services (XUID)* est l'identificateur qui doit être utilisé lors des communications avec les XBOX services ou lors de l'appel de l'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 requis pour obtenir le XUID. Si ce consentement est requis et n'est pas accordé, `XUserGetId` retourne E\_GAMEUSER\_RESOLVE\_USER\_ISSUE\_REQUIRED. Pour résoudre le problème et recueillir le consentement, les jeux doivent alors appeler `XUserResolveIssueWithUiAsync`.

## États de XUser

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

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

## Ajout ou retrait d'utilisateurs dans le jeu

Contrairement au modèle de l'ERA de 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 changements 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. À partir du guide, l'utilisateur B choisit de se déconnecter.
6. Aucun événement de changement de connexion n'est déclenché pour le jeu. Le jeu n'a jamais su que l'utilisateur B existait.
7. À partir du guide, l'utilisateur A choisit de se déconnecter.
8. Le jeu reçoit d'abord un événement de changement indiquant 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é.

Bien que les jeux aient la capacité d'ajouter des utilisateurs, il n'existe que quelques façons de retirer des utilisateurs, au moyen de l'une des méthodes suivantes.

* Le jeu peut fermer tous les descripteurs 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 à 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 capacités d'un utilisateur sur le 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 demeurent sur la console jusqu'à ce qu'ils soient explicitement supprimés au moyen de l'application Paramètres.

Les *invités Xbox* disposent d'une seule session sur une console. Ils sont créés lorsqu'ils choisissent, dans le sélecteur de compte, de jouer en tant qu'invité, et ils sont parrainés par un autre joueur XBOX connecté. Les invités demeurent 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 veulent 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 principales façons d'y parvenir.

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

1. Appelez `XUserAddAsync` en utilisant `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 XBOX services. 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` en utilisant `AddDefaultUserAllowingUI`. Tout 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 XBOX services et peut créer un contexte XBOX pour cet utilisateur.

Pour obtenir un exemple de code illustrant ces étapes, consultez [Procédure : pratique exemplaire pour connecter un utilisateur](/fr-CA/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 de ces descripteurs représentent chacun le même utilisateur. Les jeux doivent utiliser le modèle de base suivant.

1. Maintenez une collection d'instances de `XUserHandle` qui représente la collection d'utilisateurs qui intéressent le jeu.
2. Inscrivez-vous aux changements d'état de `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` de `XUserAddAsync`, assurez-vous de vérifier s'il représente un nouvel utilisateur. Vous pouvez comparer directement les descripteurs à l'aide de `XUserCompare`. Vous pouvez aussi les comparer à l'aide de l'ID local obtenu en appelant `XUserGetLocalId`.
4. Si vous avez plusieurs instances de `XUserHandle` qui représentent le même utilisateur, utilisez `XUserCloseHandle` pour retirer les instances supplémentaires.

L'*ID local* est un identificateur qui reste associé à l'utilisateur pendant toute la durée de vie de cet utilisateur au sein de la session de jeu. Utilisez l'ID local dans tous les processus que le jeu génère 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

- [Identité de l'utilisateur et API XUser dans le GDK](/fr-CA/build/core-features/common/user/index.md)
- [Utilisateurs](/fr-CA/build/core-features/common/user/user-toc.md)
- [Prise en charge multiplateforme de XUser](/fr-CA/build/core-features/common/user/xuser-crossplatform.md)
- [Procédure : pratique exemplaire pour connecter un utilisateur](/fr-CA/build/core-features/common/user/xuser_howto_best_practice_signing_in.md)
- [Vue d'ensemble des utilisateurs invités](/fr-CA/build/core-features/common/user/users-guest-overview.md)