Cycle de vie du SDK

Cette page décrit la séquence complète de démarrage et d’arrêt du SDK PlayFab Services. Tous les titres suivent le même modèle général : configurer les hooks facultatifs, initialiser Core, créer une configuration de service, initialiser Services, effectuer le travail, puis tout arrêter dans l’ordre inverse.

Séquence d’initialisation

L’initialisation comporte quatre étapes. La première est facultative ; les trois autres sont obligatoires.

PFMemSetFunctions (optional)  →  PFInitialize  →  PFServiceConfigCreateHandle  →  PFServicesInitialize

Étape 1 : définir des hooks de mémoire personnalisés (facultatif)

Si votre titre utilise un allocateur de mémoire personnalisé, appelez PFMemSetFunctions avant toute autre API PlayFab. Toutes les allocations de mémoire du SDK passent alors par vos propres rappels alloc et free.

PFMemoryHooks hooks{};
hooks.alloc = MyAllocFunction;
hooks.free = MyFreeFunction;
HRESULT hr = PFMemSetFunctions(&hooks);

PFMemSetFunctions doit être appelé avant PFInitialize. Il ne peut pas être appelé à nouveau une fois les hooks définis.

Si vous n’avez pas besoin d’une gestion personnalisée de la mémoire, ignorez cette étape. Le SDK utilise les routines d’allocation par défaut.

Étape 2 : initialiser PlayFab Core

PFInitialize configure l’état global du SDK, notamment la couche HTTP et la file d’attente des tâches d’arrière-plan. La signature exacte varie selon la plateforme.

Windows, Linux, iOS et macOS

HRESULT hr = PFInitialize(nullptr); // Uses a default threadpool queue

Transmettez un XTaskQueueHandle si vous souhaitez contrôler la file d’attente qui gère le travail en arrière-plan. Transmettez nullptr pour utiliser la file d’attente du pool de threads par défaut.

Android

Sur Android, vous devez également fournir la machine virtuelle Java et le contexte de l’application afin que le SDK puisse initialiser libHttpClient :

HRESULT hr = PFInitialize(nullptr, javaVm, applicationContext);

Si vous n’appelez pas explicitement PFInitialize, PFServicesInitialize l’appelle en interne avec les paramètres par défaut. Cela convient à la plupart des titres. Toutefois, si vous utilisez des hooks de mémoire personnalisés via PFMemSetFunctions, vous devez appeler vous-même PFInitialize ; sinon, PFServicesInitialize initialise Core avant que vos hooks de mémoire ne prennent effet, et le SDK utilise alors les routines d’allocation par défaut.

Étape 3 : créer une configuration de service

PFServiceConfigCreateHandle crée un handle qui indique au SDK le titre et le point de terminaison PlayFab à cibler. Vous trouverez ces deux valeurs dans Game Manager.

PFServiceConfigHandle serviceConfigHandle{ nullptr };
HRESULT hr = PFServiceConfigCreateHandle(
    "https://ABCDEF.playfabapi.com",    // API endpoint from Game Manager
    "ABCDEF",                           // Title ID from Game Manager
    &serviceConfigHandle);

Le PFServiceConfigHandle renvoyé est requis pour tous les appels de connexion ultérieurs.

Étape 4 : initialiser PlayFab Services

PFServicesInitialize configure la couche Services (Inventory, Leaderboards, Friends, etc.) au-dessus de Core.

Windows, Linux, iOS et macOS

HRESULT hr = PFServicesInitialize(nullptr);

Le paramètre est réservé à un usage ultérieur ; transmettez nullptr.

Android

Sur Android, transmettez un struct HCInitArgs contenant la machine virtuelle Java et le contexte de l’application :

HRESULT hr = PFServicesInitialize(nullptr, initArgs);

Une fois cet appel réussi, le SDK est prêt. Vous pouvez connecter des joueurs et effectuer des appels de service.

Cycle de vie de PFServiceConfigHandle

Un PFServiceConfigHandle est un handle à comptage de références. Le SDK gère sa durée de vie interne par comptage de références, mais il vous incombe de fermer chaque handle que vous possédez.

Fonction	Description
PFServiceConfigCreateHandle	Crée un nouveau handle. Le compteur de références initial est 1.
PFServiceConfigDuplicateHandle	Incrémente le compteur de références et renvoie un deuxième handle. Les deux handles doivent être fermés indépendamment.
PFServiceConfigCloseHandle	Décrémente le compteur de références. Lorsqu’il atteint 0, la configuration est détruite.
PFServiceConfigGetAPIEndpoint	Récupère la chaîne du point de terminaison de l’API. Appelez d’abord PFServiceConfigGetAPIEndpointSize pour déterminer la taille de la mémoire tampon.
PFServiceConfigGetTitleId	Récupère la chaîne de l’ID du titre. Appelez d’abord PFServiceConfigGetTitleIdSize pour déterminer la taille de la mémoire tampon.

Dupliquer un handle

Utilisez PFServiceConfigDuplicateHandle lorsque vous devez partager une configuration de service entre des composants qui gèrent leur propre durée de vie :

PFServiceConfigHandle duplicatedHandle{ nullptr };
HRESULT hr = PFServiceConfigDuplicateHandle(serviceConfigHandle, &duplicatedHandle);

// Both handles are now valid and must be closed separately
PFServiceConfigCloseHandle(duplicatedHandle);
PFServiceConfigCloseHandle(serviceConfigHandle);

Séquence d’arrêt

L’arrêt suit l’ordre inverse de l’initialisation. Vous devez désinitialiser Services avant Core, et les deux appels sont asynchrones.

Close handles  →  PFServicesUninitializeAsync  →  PFUninitializeAsync

Étape 1 : fermer tous les handles ouverts

Avant de démonter le SDK, fermez chaque PFEntityHandle et PFServiceConfigHandle que vous possédez :

PFEntityCloseHandle(entityHandle);
entityHandle = nullptr;

PFServiceConfigCloseHandle(serviceConfigHandle);
serviceConfigHandle = nullptr;

Étape 2 : désinitialiser Services

PFServicesUninitializeAsync démonte la couche Services. Attendez la fin de cette opération avant de continuer.

XAsyncBlock asyncServices{};
HRESULT hr = PFServicesUninitializeAsync(&asyncServices);
hr = XAsyncGetStatus(&asyncServices, true); // Blocking wait

Étape 3 : désinitialiser Core

Une fois le nettoyage de Services terminé, appelez PFUninitializeAsync pour démonter Core :

XAsyncBlock asyncCore{};
HRESULT hr = PFUninitializeAsync(&asyncCore);
hr = XAsyncGetStatus(&asyncCore, true); // Blocking wait

Si vous n’avez pas appelé explicitement PFInitialize, vous pouvez ignorer PFUninitializeAsync. Dans ce cas, PFServicesUninitializeAsync gère automatiquement le nettoyage de Core. Toutefois, si vous avez appelé vous-même PFInitialize, vous devez appeler vous-même PFUninitializeAsync.

Exemple complet

Cet exemple montre le cycle de vie complet, de l’initialisation à l’arrêt, pour un titre Windows :

#include <playfab/services/PFServices.h>

void RunPlayFab()
{
    //
    // Optional: set custom memory hooks
    //
    PFMemoryHooks hooks{};
    hooks.alloc = MyAllocFunction;
    hooks.free = MyFreeFunction;
    HRESULT hr = PFMemSetFunctions(&hooks);

    //
    // Initialize Core
    //
    hr = PFInitialize(nullptr);

    //
    // Create a service configuration
    //
    PFServiceConfigHandle serviceConfigHandle{ nullptr };
    hr = PFServiceConfigCreateHandle(
        "https://ABCDEF.playfabapi.com",
        "ABCDEF",
        &serviceConfigHandle);

    //
    // Initialize Services
    //
    hr = PFServicesInitialize(nullptr);

    //
    // Log in a player (Windows example using XUser)
    //
    PFAuthenticationLoginWithXUserRequest request{};
    request.createAccount = true;
    request.user = userHandle;

    XAsyncBlock asyncLogin{};
    hr = PFAuthenticationLoginWithXUserAsync(serviceConfigHandle, &request, &asyncLogin);
    hr = XAsyncGetStatus(&asyncLogin, true);

    size_t bufferSize{};
    hr = PFAuthenticationLoginWithXUserGetResultSize(&asyncLogin, &bufferSize);

    std::vector<char> loginResultBuffer(bufferSize);
    PFAuthenticationLoginResult const* loginResult{};
    PFEntityHandle entityHandle{ nullptr };
    hr = PFAuthenticationLoginWithXUserGetResult(
        &asyncLogin, &entityHandle,
        loginResultBuffer.size(), loginResultBuffer.data(),
        &loginResult, nullptr);

    //
    // ... make service calls ...
    //

    //
    // Shutdown: close handles first
    //
    PFEntityCloseHandle(entityHandle);
    entityHandle = nullptr;

    PFServiceConfigCloseHandle(serviceConfigHandle);
    serviceConfigHandle = nullptr;

    //
    // Shutdown: uninitialize Services, then Core
    //
    XAsyncBlock asyncServices{};
    hr = PFServicesUninitializeAsync(&asyncServices);
    hr = XAsyncGetStatus(&asyncServices, true);

    XAsyncBlock asyncCore{};
    hr = PFUninitializeAsync(&asyncCore);
    hr = XAsyncGetStatus(&asyncCore, true);
}

Erreurs courantes

Erreur	Conséquence	Correction
Appeler PFMemSetFunctions après PFInitialize	L’appel échoue. Les hooks de mémoire ne peuvent être définis qu’avant l’initialisation.	Faites de PFMemSetFunctions le tout premier appel PlayFab de votre programme.
Appeler PFUninitializeAsync avant PFServicesUninitializeAsync	Comportement non défini. Core est démonté alors que Services en dépend encore.	Désinitialisez toujours Services en premier, attendez la fin de l’opération, puis désinitialisez Core.
Oublier d’appeler PFUninitializeAsync après un appel explicite à PFInitialize	Fuite des ressources de Core. La file d’attente d’arrière-plan et la couche HTTP ne sont pas nettoyées.	Si vous avez appelé PFInitialize, vous devez appeler PFUninitializeAsync.
Ne pas attendre la fin de la désinitialisation asynchrone	Le processus peut se terminer alors que le nettoyage est toujours en cours, provoquant des plantages ou des blocages.	Utilisez `XAsyncGetStatus(async, true)` ou un rappel XAsyncBlock pour attendre la fin de l’opération.
Fuite de PFServiceConfigHandle ou de PFEntityHandle	Les ressources à comptage de références ne sont pas libérées et peuvent empêcher un arrêt propre.	Fermez chaque handle que vous créez ou dupliquez avant d’appeler la désinitialisation.

XBOX Services

PlayFab

Séquence d’initialisation

Étape 1 : définir des hooks de mémoire personnalisés (facultatif)

Étape 2 : initialiser PlayFab Core

Windows, Linux, iOS et macOS

Android

Étape 3 : créer une configuration de service

Étape 4 : initialiser PlayFab Services

Windows, Linux, iOS et macOS

Android

Cycle de vie de PFServiceConfigHandle

Dupliquer un handle

Séquence d’arrêt

Étape 1 : fermer tous les handles ouverts

Étape 2 : désinitialiser Services

Étape 3 : désinitialiser Core

Exemple complet

Erreurs courantes

Voir aussi

​Séquence d’initialisation

​Étape 1 : définir des hooks de mémoire personnalisés (facultatif)

​Étape 2 : initialiser PlayFab Core

​Windows, Linux, iOS et macOS

​Android

​Étape 3 : créer une configuration de service

​Étape 4 : initialiser PlayFab Services

​Windows, Linux, iOS et macOS

​Android

​Cycle de vie de PFServiceConfigHandle

​Dupliquer un handle

​Séquence d’arrêt

​Étape 1 : fermer tous les handles ouverts

​Étape 2 : désinitialiser Services

​Étape 3 : désinitialiser Core

​Exemple complet

​Erreurs courantes

​Voir aussi

Séquence d’initialisation

Étape 1 : définir des hooks de mémoire personnalisés (facultatif)

Étape 2 : initialiser PlayFab Core

Windows, Linux, iOS et macOS

Android

Étape 3 : créer une configuration de service

Étape 4 : initialiser PlayFab Services

Windows, Linux, iOS et macOS

Android

Cycle de vie de PFServiceConfigHandle

Dupliquer un handle

Séquence d’arrêt

Étape 1 : fermer tous les handles ouverts

Étape 2 : désinitialiser Services

Étape 3 : désinitialiser Core

Exemple complet

Erreurs courantes

Voir aussi