Ciclo de vida do SDK

Esta página aborda a sequência completa de inicialização e desligamento do SDK do PlayFab Services. Todo título segue o mesmo padrão geral: configurar hooks opcionais, inicializar o Core, criar uma configuração de serviço, inicializar o Services, realizar o trabalho e, em seguida, desligar na ordem inversa.

Sequência de inicialização

A inicialização tem quatro etapas. A primeira é opcional; as três restantes são obrigatórias.

PFMemSetFunctions (optional)  →  PFInitialize  →  PFServiceConfigCreateHandle  →  PFServicesInitialize

Etapa 1: definir hooks de memória personalizados (opcional)

Se o seu título usa um alocador de memória personalizado, chame PFMemSetFunctions antes de qualquer outra API do PlayFab. Isso direciona todas as alocações de memória do SDK para seus próprios retornos de chamada alloc e free.

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

PFMemSetFunctions deve ser chamado antes de PFInitialize. Ele não pode ser chamado novamente depois que os hooks forem definidos.

Se você não precisar de gerenciamento de memória personalizado, ignore esta etapa. O SDK usa as rotinas de alocação padrão.

Etapa 2: inicializar o PlayFab Core

PFInitialize configura o estado global do SDK, incluindo a camada HTTP e a fila de tarefas em segundo plano. A assinatura exata varia de acordo com a plataforma.

Windows, Linux, iOS e macOS

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

Passe um XTaskQueueHandle se quiser controlar qual fila processa o trabalho em segundo plano. Passe nullptr para usar a fila padrão do pool de threads.

Android

No Android, você também deve fornecer a Java VM e o contexto do aplicativo para que o SDK possa inicializar o libHttpClient:

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

Se você não chamar PFInitialize explicitamente, PFServicesInitialize o chamará internamente com os parâmetros padrão. Isso é adequado para a maioria dos títulos. No entanto, se você estiver usando hooks de memória personalizados por meio de PFMemSetFunctions, deverá chamar PFInitialize por conta própria; caso contrário, PFServicesInitialize inicializará o Core antes que seus hooks de memória entrem em vigor, e o SDK usará as rotinas de alocação padrão.

Etapa 3: criar uma configuração de serviço

PFServiceConfigCreateHandle cria um identificador que informa ao SDK qual título e qual ponto de extremidade do PlayFab usar. Você encontrará ambos os valores no Game Manager.

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

O PFServiceConfigHandle retornado é necessário para todas as chamadas de login subsequentes.

Etapa 4: inicializar o PlayFab Services

PFServicesInitialize configura a camada Services (Inventory, Leaderboards, Friends e assim por diante) sobre o Core.

Windows, Linux, iOS e macOS

HRESULT hr = PFServicesInitialize(nullptr);

O parâmetro é reservado para uso futuro; passe nullptr.

Android

No Android, passe um struct HCInitArgs que contenha a Java VM e o contexto do aplicativo:

HRESULT hr = PFServicesInitialize(nullptr, initArgs);

Depois que essa chamada for bem-sucedida, o SDK estará pronto. Você poderá fazer login de jogadores e fazer chamadas de serviço.

Ciclo de vida de PFServiceConfigHandle

Um PFServiceConfigHandle é um identificador com contagem de referências. O SDK gerencia seu tempo de vida interno por meio da contagem de referências, mas você é responsável por fechar todos os identificadores que possui.

Função	Descrição
PFServiceConfigCreateHandle	Cria um novo identificador. A contagem de referências inicial é 1.
PFServiceConfigDuplicateHandle	Incrementa a contagem de referências e retorna um segundo identificador. Ambos os identificadores devem ser fechados de forma independente.
PFServiceConfigCloseHandle	Decrementa a contagem de referências. Quando ela chega a 0, a configuração é destruída.
PFServiceConfigGetAPIEndpoint	Recupera a cadeia de caracteres do ponto de extremidade da API. Chame PFServiceConfigGetAPIEndpointSize primeiro para determinar o tamanho do buffer.
PFServiceConfigGetTitleId	Recupera a cadeia de caracteres da ID do título. Chame PFServiceConfigGetTitleIdSize primeiro para determinar o tamanho do buffer.

Duplicando um identificador

Use PFServiceConfigDuplicateHandle quando precisar compartilhar uma configuração de serviço entre componentes que gerenciam seus próprios tempos de vida:

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

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

Sequência de desligamento

O desligamento é o inverso da inicialização. Você deve desinicializar o Services antes do Core, e ambas as chamadas são assíncronas.

Close handles  →  PFServicesUninitializeAsync  →  PFUninitializeAsync

Etapa 1: fechar todos os identificadores abertos

Antes de desmontar o SDK, feche todos os PFEntityHandle e PFServiceConfigHandle que você possui:

PFEntityCloseHandle(entityHandle);
entityHandle = nullptr;

PFServiceConfigCloseHandle(serviceConfigHandle);
serviceConfigHandle = nullptr;

Etapa 2: desinicializar o Services

PFServicesUninitializeAsync desmonta a camada Services. Aguarde a conclusão antes de prosseguir.

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

Etapa 3: desinicializar o Core

Depois que a limpeza do Services terminar, chame PFUninitializeAsync para desmontar o Core:

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

Se você não chamou PFInitialize explicitamente, pode ignorar PFUninitializeAsync. Nesse caso, PFServicesUninitializeAsync cuida da limpeza do Core automaticamente. No entanto, se você chamou PFInitialize por conta própria, deverá chamar PFUninitializeAsync por conta própria.

Exemplo completo

Este exemplo mostra o ciclo de vida completo, da inicialização ao desligamento, em um título do 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);
}

Erros comuns

Erro	O que acontece	Correção
Chamar PFMemSetFunctions depois de PFInitialize	A chamada falha. Os hooks de memória só podem ser definidos antes da inicialização.	Mova PFMemSetFunctions para a primeiríssima chamada do PlayFab no seu programa.
Chamar PFUninitializeAsync antes de PFServicesUninitializeAsync	Comportamento indefinido. O Core é desmontado enquanto o Services ainda depende dele.	Sempre desinicialize o Services primeiro, aguarde a conclusão e então desinicialize o Core.
Esquecer de chamar PFUninitializeAsync após um PFInitialize explícito	Há vazamento de recursos do Core. A fila em segundo plano e a camada HTTP não são limpas.	Se você chamou PFInitialize, deverá chamar PFUninitializeAsync.
Não aguardar a conclusão da desinicialização assíncrona	O processo pode ser encerrado enquanto a limpeza ainda está em andamento, causando falhas ou travamentos.	Use `XAsyncGetStatus(async, true)` ou um retorno de chamada de XAsyncBlock para aguardar a conclusão.
Vazamento de PFServiceConfigHandle ou PFEntityHandle	Os recursos com contagem de referências não são liberados e podem impedir um desligamento limpo.	Feche todos os identificadores que você criar ou duplicar antes de chamar a desinicialização.

XBOX Services

PlayFab

Sequência de inicialização

Etapa 1: definir hooks de memória personalizados (opcional)

Etapa 2: inicializar o PlayFab Core

Windows, Linux, iOS e macOS

Android

Etapa 3: criar uma configuração de serviço

Etapa 4: inicializar o PlayFab Services

Windows, Linux, iOS e macOS

Android

Ciclo de vida de PFServiceConfigHandle

Duplicando um identificador

Sequência de desligamento

Etapa 1: fechar todos os identificadores abertos

Etapa 2: desinicializar o Services

Etapa 3: desinicializar o Core

Exemplo completo

Erros comuns

Confira também

​Sequência de inicialização

​Etapa 1: definir hooks de memória personalizados (opcional)

​Etapa 2: inicializar o PlayFab Core

​Windows, Linux, iOS e macOS

​Android

​Etapa 3: criar uma configuração de serviço

​Etapa 4: inicializar o PlayFab Services

​Windows, Linux, iOS e macOS

​Android

​Ciclo de vida de PFServiceConfigHandle

​Duplicando um identificador

​Sequência de desligamento

​Etapa 1: fechar todos os identificadores abertos

​Etapa 2: desinicializar o Services

​Etapa 3: desinicializar o Core

​Exemplo completo

​Erros comuns

​Confira também

Sequência de inicialização

Etapa 1: definir hooks de memória personalizados (opcional)

Etapa 2: inicializar o PlayFab Core

Windows, Linux, iOS e macOS

Android

Etapa 3: criar uma configuração de serviço

Etapa 4: inicializar o PlayFab Services

Windows, Linux, iOS e macOS

Android

Ciclo de vida de PFServiceConfigHandle

Duplicando um identificador

Sequência de desligamento

Etapa 1: fechar todos os identificadores abertos

Etapa 2: desinicializar o Services

Etapa 3: desinicializar o Core

Exemplo completo

Erros comuns

Confira também