Identificadores de entidade

Um PFEntityHandle é sua principal credencial para fazer chamadas de serviço do PlayFab. Ele representa uma entidade autenticada (um jogador, title_player_account, ou um título) e contém o token de entidade de que o SDK precisa para autorizar as solicitações. Toda chamada de login ou autenticação retorna um PFEntityHandle, e toda chamada de serviço exige um.

Obtendo um identificador de entidade

Você não cria identificadores de entidade diretamente. Em vez disso, obtém um como saída de uma chamada de login ou autenticação bem-sucedida. Login de jogador (exemplo do 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);

Entidade de título (servidor): As entidades de título se autenticam com uma chave secreta em vez de uma credencial de usuário. O PFEntityHandle retornado funciona da mesma forma, mas representa o título em vez de um jogador. Consulte Acessando o PlayFab com uma entidade de título para obter detalhes.

Propriedade dos identificadores e contagem de referências

PFEntityHandle tem contagem de referências. Quando você recebe um identificador de uma chamada de login, possui uma referência. Você pode criar referências adicionais com PFEntityDuplicateHandle e liberá-las com PFEntityCloseHandle. O objeto de entidade subjacente só é destruído quando a última referência é fechada. Regras:

Toda chamada a uma função GetResult de login ou a PFEntityDuplicateHandle fornece um identificador que você deve fechar.
Fechar um identificador não invalida outros identificadores da mesma entidade.
Feche todos os identificadores antes de chamar 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);

Obtendo informações da entidade

Chave da entidade

A chave da entidade identifica a entidade (seu tipo e sua ID). Use o padrão de duas chamadas: primeiro obtenha o tamanho e depois obtenha os dados.

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

Token de entidade

O token de entidade autoriza as chamadas de serviço. O SDK gerencia os tokens automaticamente, mas você pode recuperar o atual, se necessário.

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)

Verificando o tipo de entidade

Use PFEntityIsTitlePlayer como uma verificação rápida, em vez de inspecionar a cadeia de caracteres do tipo da chave da entidade:

bool isTitlePlayer{};
HRESULT hr = PFEntityIsTitlePlayer(entityHandle, &isTitlePlayer);

Entidades de jogador e entidades de título

As entidades de jogador e de título usam PFEntityHandle, mas diferem no que podem fazer:

	Entidade de jogador	Entidade de título
Como obtê-la	Chamada de login (por exemplo, `PFAuthenticationLoginWithXUserAsync`)	`PFAuthenticationGetEntityWithSecretKeyAsync`
Tipo de entidade	`title_player_account`	`title`
PFEntityIsTitlePlayer	Retorna `true`	Retorna `false`
PFEntityGetSecretKey	Falha com `E_PF_NOSECRETKEY`	Retorna a chave secreta
APIs disponíveis	APIs com prefixo Client e sem prefixo	APIs com prefixo Server e sem prefixo

As APIs sem prefixo (por exemplo, Inventory, Leaderboards, Data) geralmente podem ser chamadas tanto por entidades de jogador quanto de título, a menos que indicado de outra forma na documentação delas. As APIs com prefixo Client são exclusivas de jogadores, e as APIs com prefixo Server são exclusivas de títulos. PFEntityGetSecretKey recupera a chave secreta associada a uma entidade de título. Ela falha para entidades de jogador, pois elas não têm uma.

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 está disponível apenas nas plataformas Windows, Linux e macOS.

Manipuladores de eventos de token

O SDK atualiza automaticamente os tokens de entidade antes que expirem. Você pode registrar retornos de chamada para observar esses eventos.

Token expirado

Se a atualização automática falhar (por exemplo, se a credencial de login original não for mais válida), o SDK disparará o evento de token expirado. Registre um manipulador para fornecer uma nova credencial e tentar o login novamente.

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

Token atualizado

Registre um manipulador de token atualizado se quiser saber quando o SDK atualizar um token em segundo plano com êxito. Isso é informativo; você não precisa realizar nenhuma ação.

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

Quando registrar e cancelar o registro

Registre os manipuladores cedo, logo após a inicialização do SDK e antes do login. Isso garante que você não perca nenhum evento.
Cancele o registro dos manipuladores durante o desligamento, antes de fechar os identificadores de entidade.

PFEntityUnregisterTokenExpiredEventHandler(expiredRegistrationToken);
PFEntityUnregisterTokenRefreshedEventHandler(refreshedRegistrationToken);

Para ver um passo a passo completo do tratamento da expiração de tokens e do novo login, consulte Tratando a expiração de tokens.

Acessadores utilitários

Você pode recuperar o ponto de extremidade da API e a ID do título de um identificador de entidade. Eles vêm do PFServiceConfigHandle usado durante o login.

// 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);

Exemplo completo

Este exemplo demonstra como criar, duplicar, consultar e fechar identificadores de entidade:

#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);
}

Referência de API

Função	Descrição
PFEntityDuplicateHandle	Duplica um identificador, incrementando a contagem de referências. Ambos os identificadores devem ser fechados de forma independente.
PFEntityCloseHandle	Fecha um identificador, decrementando a contagem de referências. A entidade é destruída quando o último identificador é fechado.
PFEntityGetEntityKeySize	Obtém o tamanho do buffer necessário para armazenar a chave da entidade.
PFEntityGetEntityKey	Obtém a chave (tipo e ID) da entidade.
PFEntityGetEntityTokenAsync	Recupera de forma assíncrona o token de entidade armazenado em cache.
PFEntityGetEntityTokenResultSize	Obtém o tamanho do buffer necessário para o resultado do token de entidade.
PFEntityGetEntityTokenResult	Obtém o token de entidade de uma chamada PFEntityGetEntityTokenAsync concluída.
PFEntityIsTitlePlayer	Retorna se a entidade é um title_player_account.
PFEntityGetSecretKeySize	Obtém o tamanho do buffer necessário para a chave secreta. Falha se a entidade não for uma entidade de título.
PFEntityGetSecretKey	Obtém a chave secreta de uma entidade de título. Disponível apenas no Windows, Linux e macOS.
PFEntityGetAPIEndpointSize	Obtém o tamanho do buffer necessário para a cadeia de caracteres do ponto de extremidade da API.
PFEntityGetAPIEndpoint	Obtém o ponto de extremidade da API da configuração de serviço associada à entidade.
PFEntityGetTitleIdSize	Obtém o tamanho do buffer necessário para a cadeia de caracteres da ID do título.
PFEntityGetTitleId	Obtém a ID do título da configuração de serviço associada à entidade.
PFEntityRegisterTokenExpiredEventHandler	Registra um retorno de chamada para quando a atualização automática do token falhar.
PFEntityUnregisterTokenExpiredEventHandler	Cancela o registro de um retorno de chamada de token expirado.
PFEntityRegisterTokenRefreshedEventHandler	Registra um retorno de chamada para quando o SDK atualizar um token com êxito.
PFEntityUnregisterTokenRefreshedEventHandler	Cancela o registro de um retorno de chamada de token atualizado.

Para ver a referência de API completa, consulte Membros de PFEntity.

XBOX Services

PlayFab

Obtendo um identificador de entidade

Propriedade dos identificadores e contagem de referências

Obtendo informações da entidade

Chave da entidade

Token de entidade

Verificando o tipo de entidade

Entidades de jogador e entidades de título

Manipuladores de eventos de token

Token expirado

Token atualizado

Quando registrar e cancelar o registro

Acessadores utilitários

Exemplo completo

Referência de API

Confira também

​Obtendo um identificador de entidade

​Propriedade dos identificadores e contagem de referências

​Obtendo informações da entidade

​Chave da entidade

​Token de entidade

​Verificando o tipo de entidade

​Entidades de jogador e entidades de título

​Manipuladores de eventos de token

​Token expirado

​Token atualizado

​Quando registrar e cancelar o registro

​Acessadores utilitários

​Exemplo completo

​Referência de API

​Confira também

Obtendo um identificador de entidade

Propriedade dos identificadores e contagem de referências

Obtendo informações da entidade

Chave da entidade

Token de entidade

Verificando o tipo de entidade

Entidades de jogador e entidades de título

Manipuladores de eventos de token

Token expirado

Token atualizado

Quando registrar e cancelar o registro

Acessadores utilitários

Exemplo completo

Referência de API

Confira também