Handles d'entité

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) :

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

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 et les libérer avec 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.

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

size_t size{};
HRESULT hr = PFEntityGetEntityKeySize(entityHandle, &size);

std::vector<char> 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.

XAsyncBlock async{};
HRESULT hr = PFEntityGetEntityTokenAsync(entityHandle, &async);
hr = XAsyncGetStatus(&async, true);

size_t size{};
hr = PFEntityGetEntityTokenResultSize(&async, &size);

std::vector<char> 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 pour une vérification rapide, au lieu d’examiner la chaîne du type de clé d’entité :

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	Renvoie `true`	Renvoie `false`
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.

size_t keySize{};
HRESULT hr = PFEntityGetSecretKeySize(entityHandle, &keySize);
if (SUCCEEDED(hr))
{
    std::vector<char> 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.

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
    },
    &registrationToken);

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.

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
    },
    &registrationToken);

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

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.

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.

// Get API endpoint
size_t endpointSize{};
HRESULT hr = PFEntityGetAPIEndpointSize(entityHandle, &endpointSize);

std::vector<char> endpoint(endpointSize);
hr = PFEntityGetAPIEndpoint(entityHandle, endpoint.size(), endpoint.data(), nullptr);

// Get title ID
size_t titleIdSize{};
hr = PFEntityGetTitleIdSize(entityHandle, &titleIdSize);

std::vector<char> 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é :

#include <playfab/core/PFEntity.h>
#include <playfab/services/PFServices.h>

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<char> 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<char> 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	Duplique un handle en incrémentant le compteur de références. Les deux handles doivent être fermés indépendamment.
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	Obtient la taille de la mémoire tampon nécessaire pour stocker la clé d’entité.
PFEntityGetEntityKey	Obtient la clé d’entité (type et ID) de l’entité.
PFEntityGetEntityTokenAsync	Récupère de manière asynchrone le jeton d’entité mis en cache.
PFEntityGetEntityTokenResultSize	Obtient la taille de la mémoire tampon nécessaire pour le résultat du jeton d’entité.
PFEntityGetEntityTokenResult	Obtient le jeton d’entité à partir d’un appel PFEntityGetEntityTokenAsync terminé.
PFEntityIsTitlePlayer	Indique si l’entité est un title_player_account.
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	Obtient la clé secrète d’une entité de titre. Disponible uniquement sur Windows, Linux et macOS.
PFEntityGetAPIEndpointSize	Obtient la taille de la mémoire tampon nécessaire pour la chaîne du point de terminaison de l’API.
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	Inscrit un rappel appelé en cas d’échec de l’actualisation automatique du jeton.
PFEntityUnregisterTokenExpiredEventHandler	Désinscrit un rappel d’expiration de jeton.
PFEntityRegisterTokenRefreshedEventHandler	Inscrit un rappel appelé lorsque le SDK actualise un jeton avec succès.
PFEntityUnregisterTokenRefreshedEventHandler	Désinscrit un rappel d’actualisation de jeton.

Pour la référence complète de l’API, consultez Membres de PFEntity.

XBOX Services

PlayFab

Obtenir un handle d’entité

Propriété des handles et comptage de références

Obtenir les informations de l’entité

Clé d’entité

Jeton d’entité

Vérifier le type d’entité

Entités de joueur et entités de titre

Gestionnaires d’événements de jeton

Jeton expiré

Jeton actualisé

Quand inscrire et désinscrire les gestionnaires

Accesseurs utilitaires

Exemple complet

Référence de l’API

Voir aussi

​Obtenir un handle d’entité

​Propriété des handles et comptage de références

​Obtenir les informations de l’entité

​Clé d’entité

​Jeton d’entité

​Vérifier le type d’entité

​Entités de joueur et entités de titre

​Gestionnaires d’événements de jeton

​Jeton expiré

​Jeton actualisé

​Quand inscrire et désinscrire les gestionnaires

​Accesseurs utilitaires

​Exemple complet

​Référence de l’API

​Voir aussi

Obtenir un handle d’entité

Propriété des handles et comptage de références

Obtenir les informations de l’entité

Clé d’entité

Jeton d’entité

Vérifier le type d’entité

Entités de joueur et entités de titre

Gestionnaires d’événements de jeton

Jeton expiré

Jeton actualisé

Quand inscrire et désinscrire les gestionnaires

Accesseurs utilitaires

Exemple complet

Référence de l’API

Voir aussi