> ## 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. # Handles d'entité > Gérez les informations d'identification PFEntityHandle, le comptage de références et la durée de vie des jetons d'entité pour les appels authentifiés de joueur et de titre dans le SDK C PlayFab. Un **PFEntityHandle** est votre principale information d'identification pour effectuer des appels de service PlayFab. Il représente une entité authentifiée, soit un joueur (title\_player\_account), soit un titre, et contient le jeton d'entité dont le SDK a besoin pour autoriser les requêtes. Chaque appel de connexion ou d'authentification renvoie un **PFEntityHandle**, et chaque appel de service en nécessite un. ## Obtenir un handle d'entité Vous ne créez pas directement de handles d'entité. Vous en obtenez un en sortie d'un appel de connexion ou d'authentification réussi. **Connexion d'un joueur (exemple Windows) :** ```cpp theme={null} PFAuthenticationLoginWithXUserRequest request{}; request.createAccount = true; request.user = userHandle; // XUserHandle from XUserAddAsync XAsyncBlock async{}; HRESULT hr = PFAuthenticationLoginWithXUserAsync(serviceConfigHandle, &request, &async); hr = XAsyncGetStatus(&async, true); PFEntityHandle entityHandle{ nullptr }; size_t bufferSize{}; hr = PFAuthenticationLoginWithXUserGetResultSize(&async, &bufferSize); std::vector loginResultBuffer(bufferSize); PFAuthenticationLoginResult const* loginResult{}; hr = PFAuthenticationLoginWithXUserGetResult( &async, &entityHandle, loginResultBuffer.size(), loginResultBuffer.data(), &loginResult, nullptr); ``` **Entité de titre (serveur) :** Les entités de titre s'authentifient avec une clé secrète au lieu d'informations d'identification d'utilisateur. Le **PFEntityHandle** renvoyé fonctionne de la même manière, mais il représente le titre plutôt qu'un joueur. Pour plus de détails, consultez [Accéder à PlayFab avec une entité de titre](/fr/services/playfab/sdks/c/server). ## Propriété des handles et comptage de références **PFEntityHandle** fait l'objet d'un comptage de références. Lorsque vous recevez un handle d'un appel de connexion, vous possédez une référence. Vous pouvez créer des références supplémentaires avec [**PFEntityDuplicateHandle**](/fr/services/playfab/api-references/c/pfentity/functions/pfentityduplicatehandle) et les libérer avec [**PFEntityCloseHandle**](/fr/services/playfab/api-references/c/pfentity/functions/pfentityclosehandle). L'objet d'entité sous-jacent n'est détruit que lorsque la dernière référence est fermée. **Règles :** * Chaque appel à une fonction `GetResult` de connexion ou à **PFEntityDuplicateHandle** vous fournit un handle que vous devez fermer. * La fermeture d'un handle n'invalide pas les autres handles de la même entité. * Fermez tous les handles avant d'appeler [**PFServicesUninitializeAsync**](/fr/services/playfab/api-references/c/pfservices/functions/pfservicesuninitializeasync). ```cpp theme={null} // Duplicate a handle for another component PFEntityHandle secondHandle{ nullptr }; HRESULT hr = PFEntityDuplicateHandle(entityHandle, &secondHandle); // Both handles are independently valid // ... // Each owner closes their own handle PFEntityCloseHandle(secondHandle); PFEntityCloseHandle(entityHandle); ``` ## Obtenir les informations de l'entité ### Clé d'entité La clé d'entité identifie l'entité (son type et son ID). Utilisez le modèle à deux appels : obtenez d'abord la taille, puis les données. ```cpp theme={null} size_t size{}; HRESULT hr = PFEntityGetEntityKeySize(entityHandle, &size); std::vector buffer(size); PFEntityKey const* entityKey{}; hr = PFEntityGetEntityKey(entityHandle, buffer.size(), buffer.data(), &entityKey, nullptr); // entityKey->type is "title_player_account" for players // entityKey->id is the entity's unique ID ``` ### Jeton d'entité Le jeton d'entité autorise les appels de service. Le SDK gère automatiquement les jetons, mais vous pouvez récupérer le jeton actuel si nécessaire. ```cpp theme={null} XAsyncBlock async{}; HRESULT hr = PFEntityGetEntityTokenAsync(entityHandle, &async); hr = XAsyncGetStatus(&async, true); size_t size{}; hr = PFEntityGetEntityTokenResultSize(&async, &size); std::vector buffer(size); const PFEntityToken* entityToken{}; hr = PFEntityGetEntityTokenResult(&async, buffer.size(), buffer.data(), &entityToken, nullptr); // entityToken->token is the token string // entityToken->expiration is the optional expiration time (UTC) ``` ### Vérifier le type d'entité Utilisez [**PFEntityIsTitlePlayer**](/fr/services/playfab/api-references/c/pfentity/functions/pfentityistitleplayer) pour une vérification rapide, au lieu d'examiner la chaîne du type de clé d'entité : ```cpp theme={null} bool isTitlePlayer{}; HRESULT hr = PFEntityIsTitlePlayer(entityHandle, &isTitlePlayer); ``` ## Entités de joueur et entités de titre Les entités de joueur et de titre utilisent toutes deux **PFEntityHandle**, mais elles diffèrent par ce qu'elles peuvent faire : | | Entité de joueur | Entité de titre | | - | - | - | | **Comment l'obtenir** | Appel de connexion (par exemple, `PFAuthenticationLoginWithXUserAsync`) | `PFAuthenticationGetEntityWithSecretKeyAsync` | | **Type d'entité** | `title_player_account` | `title` | | [**PFEntityIsTitlePlayer**](/fr/services/playfab/api-references/c/pfentity/functions/pfentityistitleplayer) | Renvoie `true` | Renvoie `false` | | [**PFEntityGetSecretKey**](/fr/services/playfab/api-references/c/pfentity/functions/pfentitygetsecretkey) | Échoue avec `E_PF_NOSECRETKEY` | Renvoie la clé secrète | | **API disponibles** | API avec préfixe Client et API sans préfixe | API avec préfixe Server et API sans préfixe | Les API sans préfixe (par exemple, Inventory, Leaderboards, Data) peuvent généralement être appelées à la fois par les entités de joueur et de titre, sauf indication contraire dans leur documentation. Les API avec préfixe Client sont réservées aux joueurs, et les API avec préfixe Server sont réservées aux titres. **PFEntityGetSecretKey** récupère la clé secrète associée à une entité de titre. Cette fonction échoue pour les entités de joueur, car elles n'en possèdent pas. ```cpp theme={null} size_t keySize{}; HRESULT hr = PFEntityGetSecretKeySize(entityHandle, &keySize); if (SUCCEEDED(hr)) { std::vector secretKey(keySize); hr = PFEntityGetSecretKey(entityHandle, secretKey.size(), secretKey.data(), nullptr); } ``` **PFEntityGetSecretKey** n'est disponible que sur les plateformes Windows, Linux et macOS. ## Gestionnaires d'événements de jeton Le SDK actualise automatiquement les jetons d'entité avant leur expiration. Vous pouvez inscrire des rappels pour observer ces événements. ### Jeton expiré Si l'actualisation automatique échoue (par exemple, si les informations d'identification de connexion d'origine ne sont plus valides), le SDK déclenche l'événement d'expiration du jeton. Inscrivez un gestionnaire pour fournir de nouvelles informations d'identification et relancer la connexion. ```cpp theme={null} PFRegistrationToken registrationToken{}; HRESULT hr = PFEntityRegisterTokenExpiredEventHandler( nullptr, // XTaskQueueHandle, or nullptr for default nullptr, // optional context [](void* ctx, PFEntityKey const* entityKey) { // Re-authenticate the player with a fresh credential // See relogin.md for a complete example }, ®istrationToken); ``` ### Jeton actualisé Inscrivez un gestionnaire d'actualisation de jeton si vous souhaitez savoir quand le SDK actualise avec succès un jeton en arrière-plan. Ce gestionnaire est informatif : vous n'avez aucune action à effectuer. ```cpp theme={null} PFRegistrationToken registrationToken{}; HRESULT hr = PFEntityRegisterTokenRefreshedEventHandler( nullptr, // XTaskQueueHandle, or nullptr for default nullptr, // optional context [](void* ctx, PFEntityKey const* entityKey, const PFEntityToken* newToken) { // Log the refresh or update cached token references }, ®istrationToken); ``` ### Quand inscrire et désinscrire les gestionnaires * **Inscrivez** les gestionnaires tôt, juste après l'initialisation du SDK et avant la connexion. Vous êtes ainsi sûr de ne manquer aucun événement. * **Désinscrivez** les gestionnaires lors de l'arrêt, avant de fermer les handles d'entité. ```cpp theme={null} PFEntityUnregisterTokenExpiredEventHandler(expiredRegistrationToken); PFEntityUnregisterTokenRefreshedEventHandler(refreshedRegistrationToken); ``` Pour une présentation complète de la gestion de l'expiration des jetons et de la reconnexion, consultez [Gérer l'expiration des jetons](/fr/services/playfab/sdks/c/relogin). ## Accesseurs utilitaires Vous pouvez récupérer le point de terminaison de l'API et l'ID du titre à partir d'un handle d'entité. Ces valeurs proviennent du **PFServiceConfigHandle** utilisé lors de la connexion. ```cpp theme={null} // Get API endpoint size_t endpointSize{}; HRESULT hr = PFEntityGetAPIEndpointSize(entityHandle, &endpointSize); std::vector endpoint(endpointSize); hr = PFEntityGetAPIEndpoint(entityHandle, endpoint.size(), endpoint.data(), nullptr); // Get title ID size_t titleIdSize{}; hr = PFEntityGetTitleIdSize(entityHandle, &titleIdSize); std::vector titleId(titleIdSize); hr = PFEntityGetTitleId(entityHandle, titleId.size(), titleId.data(), nullptr); ``` ## Exemple complet Cet exemple montre comment créer, dupliquer, interroger et fermer des handles d'entité : ```cpp theme={null} #include #include void EntityHandleExample(PFServiceConfigHandle serviceConfigHandle, XUserHandle userHandle) { // // Log in and get an entity handle // PFAuthenticationLoginWithXUserRequest request{}; request.createAccount = true; request.user = userHandle; XAsyncBlock asyncLogin{}; HRESULT hr = PFAuthenticationLoginWithXUserAsync(serviceConfigHandle, &request, &asyncLogin); hr = XAsyncGetStatus(&asyncLogin, true); PFEntityHandle entityHandle{ nullptr }; size_t resultSize{}; hr = PFAuthenticationLoginWithXUserGetResultSize(&asyncLogin, &resultSize); std::vector loginBuffer(resultSize); PFAuthenticationLoginResult const* loginResult{}; hr = PFAuthenticationLoginWithXUserGetResult( &asyncLogin, &entityHandle, loginBuffer.size(), loginBuffer.data(), &loginResult, nullptr); // // Register token event handlers // PFRegistrationToken expiredToken{}; hr = PFEntityRegisterTokenExpiredEventHandler(nullptr, nullptr, [](void* ctx, PFEntityKey const* entityKey) { // Handle re-authentication }, &expiredToken); PFRegistrationToken refreshedToken{}; hr = PFEntityRegisterTokenRefreshedEventHandler(nullptr, nullptr, [](void* ctx, PFEntityKey const* entityKey, const PFEntityToken* newToken) { // Log token refresh }, &refreshedToken); // // Duplicate the handle for a subsystem // PFEntityHandle subsystemHandle{ nullptr }; hr = PFEntityDuplicateHandle(entityHandle, &subsystemHandle); // // Query entity info // bool isTitlePlayer{}; hr = PFEntityIsTitlePlayer(entityHandle, &isTitlePlayer); size_t keySize{}; hr = PFEntityGetEntityKeySize(entityHandle, &keySize); std::vector keyBuffer(keySize); PFEntityKey const* entityKey{}; hr = PFEntityGetEntityKey(entityHandle, keyBuffer.size(), keyBuffer.data(), &entityKey, nullptr); // // ... make service calls with entityHandle or subsystemHandle ... // // // Cleanup: unregister handlers, then close all handles // PFEntityUnregisterTokenExpiredEventHandler(expiredToken); PFEntityUnregisterTokenRefreshedEventHandler(refreshedToken); PFEntityCloseHandle(subsystemHandle); PFEntityCloseHandle(entityHandle); } ``` ## Référence de l'API | Fonction | Description | | - | - | | [PFEntityDuplicateHandle](/fr/services/playfab/api-references/c/pfentity/functions/pfentityduplicatehandle) | Duplique un handle en incrémentant le compteur de références. Les deux handles doivent être fermés indépendamment. | | [PFEntityCloseHandle](/fr/services/playfab/api-references/c/pfentity/functions/pfentityclosehandle) | Ferme un handle en décrémentant le compteur de références. L'entité est détruite lorsque le dernier handle est fermé. | | [PFEntityGetEntityKeySize](/fr/services/playfab/api-references/c/pfentity/functions/pfentitygetentitykeysize) | Obtient la taille de la mémoire tampon nécessaire pour stocker la clé d'entité. | | [PFEntityGetEntityKey](/fr/services/playfab/api-references/c/pfentity/functions/pfentitygetentitykey) | Obtient la clé d'entité (type et ID) de l'entité. | | [PFEntityGetEntityTokenAsync](/fr/services/playfab/api-references/c/pfentity/functions/pfentitygetentitytokenasync) | Récupère de manière asynchrone le jeton d'entité mis en cache. | | [PFEntityGetEntityTokenResultSize](/fr/services/playfab/api-references/c/pfentity/functions/pfentitygetentitytokenresultsize) | Obtient la taille de la mémoire tampon nécessaire pour le résultat du jeton d'entité. | | [PFEntityGetEntityTokenResult](/fr/services/playfab/api-references/c/pfentity/functions/pfentitygetentitytokenresult) | Obtient le jeton d'entité à partir d'un appel PFEntityGetEntityTokenAsync terminé. | | [PFEntityIsTitlePlayer](/fr/services/playfab/api-references/c/pfentity/functions/pfentityistitleplayer) | Indique si l'entité est un title\_player\_account. | | [PFEntityGetSecretKeySize](/fr/services/playfab/api-references/c/pfentity/functions/pfentitygetsecretkeysize) | Obtient la taille de la mémoire tampon nécessaire pour la clé secrète. Échoue si l'entité n'est pas une entité de titre. | | [PFEntityGetSecretKey](/fr/services/playfab/api-references/c/pfentity/functions/pfentitygetsecretkey) | Obtient la clé secrète d'une entité de titre. Disponible uniquement sur Windows, Linux et macOS. | | [PFEntityGetAPIEndpointSize](/fr/services/playfab/api-references/c/pfentity/functions/pfentitygetapiendpointsize) | Obtient la taille de la mémoire tampon nécessaire pour la chaîne du point de terminaison de l'API. | | [PFEntityGetAPIEndpoint](/fr/services/playfab/api-references/c/pfentity/functions/pfentitygetapiendpoint) | Obtient le point de terminaison de l'API à partir de la configuration de service associée à l'entité. | | **PFEntityGetTitleIdSize** | Obtient la taille de la mémoire tampon nécessaire pour la chaîne de l'ID du titre. | | **PFEntityGetTitleId** | Obtient l'ID du titre à partir de la configuration de service associée à l'entité. | | [PFEntityRegisterTokenExpiredEventHandler](/fr/services/playfab/api-references/c/pfentity/functions/pfentityregistertokenexpiredeventhandler) | Inscrit un rappel appelé en cas d'échec de l'actualisation automatique du jeton. | | [PFEntityUnregisterTokenExpiredEventHandler](/fr/services/playfab/api-references/c/pfentity/functions/pfentityunregistertokenexpiredeventhandler) | Désinscrit un rappel d'expiration de jeton. | | [PFEntityRegisterTokenRefreshedEventHandler](/fr/services/playfab/api-references/c/pfentity/functions/pfentityregistertokenrefreshedeventhandler) | Inscrit un rappel appelé lorsque le SDK actualise un jeton avec succès. | | [PFEntityUnregisterTokenRefreshedEventHandler](/fr/services/playfab/api-references/c/pfentity/functions/pfentityunregistertokenrefreshedeventhandler) | Désinscrit un rappel d'actualisation de jeton. | Pour la référence complète de l'API, consultez [Membres de PFEntity](/fr/services/playfab/api-references/c/pfentity/pfentity_members). ## Voir aussi * [Gérer l'expiration des jetons](/fr/services/playfab/sdks/c/relogin) * [Accéder à PlayFab avec une entité de titre](/fr/services/playfab/sdks/c/server) * [Cycle de vie du SDK](/fr/services/playfab/sdks/c/lifecycle) * [Démarrage rapide : Windows](/fr/services/playfab/sdks/c/quickstart-gdk) * [Démarrage rapide : Win32](/fr/services/playfab/sdks/c/quickstart-win32) ## Related topics - [Migrer du SDK autonome PlayFab v1 vers le SDK unifié v2](/fr/services/playfab/sdks/unified-sdk/migrating-from-v1.md) - [Groupes d'entités](/fr/services/playfab/community/associations/groups/quickstart.md) - [Fichiers d'entité](/fr/services/playfab/live-service-management/game-configuration/entities/entity-files.md) - [Types d'entités intégrés disponibles](/fr/services/playfab/live-service-management/game-configuration/entities/available-built-in-entity-types.md) - [Valider un jeton d'entité](/fr/services/playfab/api-references/rest/authentication/authentication/validate-entity-token.md)