实体句柄

PFEntityHandle 是你进行 PlayFab 服务调用的主要凭据。它表示已验证的实体——一个玩家 (title_player_account) 或一个游戏——并保存 SDK 授权请求所需的实体令牌。每次登录或身份验证调用都会返回 PFEntityHandle,并且每次服务调用都需要它。

获取实体句柄

你不能直接创建实体句柄。相反,你可以通过成功的登录或身份验证调用的输出获得句柄。 玩家登录 (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);

游戏实体 (服务器): 游戏实体使用密钥而不是用户凭据进行身份验证。返回的 PFEntityHandle 工作方式相同,但它表示游戏而不是玩家。有关详细信息,请参阅使用游戏实体访问 PlayFab。

句柄所有权和引用计数

PFEntityHandle 是引用计数的。当你从登录调用接收句柄时,你拥有一个引用。你可以使用 PFEntityDuplicateHandle 创建其他引用,并使用 PFEntityCloseHandle 释放它们。仅当关闭最后一个引用时,底层实体对象才会被销毁。 规则:

对登录 GetResult 函数或 PFEntityDuplicateHandle 的每次调用都会为你提供一个必须关闭的句柄。
关闭句柄不会使指向同一实体的其他句柄失效。
在调用 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);

获取实体信息

实体键

实体键标识实体(它的类型和 ID)。使用两个调用模式:首先获取大小,然后获取数据。

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

实体令牌

实体令牌授权服务调用。SDK 自动管理令牌,但如果需要,你可以检索当前令牌。

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)

检查实体类型

使用 PFEntityIsTitlePlayer 作为快速检查,而不是检查实体键类型字符串:

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

玩家实体与游戏实体

玩家实体和游戏实体都使用 PFEntityHandle,但它们的功能有所不同:

	玩家实体	游戏实体
如何获取	登录调用(例如 `PFAuthenticationLoginWithXUserAsync`)	`PFAuthenticationGetEntityWithSecretKeyAsync`
实体类型	`title_player_account`	`title`
PFEntityIsTitlePlayer	返回 `true`	返回 `false`
PFEntityGetSecretKey	失败并返回 `E_PF_NOSECRETKEY`	返回密钥
可用 API	带 Client 前缀的和不带前缀的 API	带 Server 前缀的和不带前缀的 API

不带前缀的 API(例如 Inventory、Leaderboards、Data)通常可以由玩家实体和游戏实体调用,除非其文档中另有说明。带 Client 前缀的 API 仅限玩家,带 Server 前缀的 API 仅限游戏。 PFEntityGetSecretKey 检索与游戏实体关联的密钥。它对玩家实体失败,因为它们没有密钥。

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 仅在 Windows、Linux 和 macOS 平台上可用。

令牌事件处理程序

SDK 会在实体令牌过期之前自动刷新它们。你可以注册回调来观察这些事件。

令牌已过期

如果自动刷新失败(例如,原始登录凭据不再有效),SDK 将触发令牌过期事件。注册一个处理程序以提供新凭据并重试登录。

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

令牌已刷新

如果你想知道 SDK 何时在后台成功刷新令牌,请注册一个令牌已刷新处理程序。这只是提供信息——你不需要采取任何操作。

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

何时注册和取消注册

注册处理程序应尽早进行,即在 SDK 初始化之后和登录之前。这可以确保你不会错过任何事件。
取消注册处理程序应在关闭期间进行,在关闭实体句柄之前。

PFEntityUnregisterTokenExpiredEventHandler(expiredRegistrationToken);
PFEntityUnregisterTokenRefreshedEventHandler(refreshedRegistrationToken);

有关令牌过期处理和重新登录的完整演练,请参阅处理令牌过期。

实用访问器

你可以从实体句柄检索 API 端点和游戏 ID。它们来自登录期间使用的 PFServiceConfigHandle。

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

完整示例

此示例演示了创建、复制、查询和关闭实体句柄:

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

API 参考

函数	描述
PFEntityDuplicateHandle	复制一个句柄,增加引用计数。两个句柄必须独立关闭。
PFEntityCloseHandle	关闭一个句柄,减少引用计数。当最后一个句柄关闭时,实体将被销毁。
PFEntityGetEntityKeySize	获取存储实体键所需的缓冲区大小。
PFEntityGetEntityKey	获取实体的实体键(类型和 ID)。
PFEntityGetEntityTokenAsync	异步检索缓存的实体令牌。
PFEntityGetEntityTokenResultSize	获取实体令牌结果所需的缓冲区大小。
PFEntityGetEntityTokenResult	从已完成的 PFEntityGetEntityTokenAsync 调用中获取实体令牌。
PFEntityIsTitlePlayer	返回实体是否为 title_player_account。
PFEntityGetSecretKeySize	获取密钥所需的缓冲区大小。如果实体不是游戏实体,则失败。
PFEntityGetSecretKey	获取游戏实体的密钥。仅在 Windows、Linux 和 macOS 上可用。
PFEntityGetAPIEndpointSize	获取 API 端点字符串所需的缓冲区大小。
PFEntityGetAPIEndpoint	从实体的关联服务配置中获取 API 端点。
PFEntityGetTitleIdSize	获取游戏 ID 字符串所需的缓冲区大小。
PFEntityGetTitleId	从实体的关联服务配置中获取游戏 ID。
PFEntityRegisterTokenExpiredEventHandler	注册一个自动令牌刷新失败时的回调。
PFEntityUnregisterTokenExpiredEventHandler	取消注册令牌过期回调。
PFEntityRegisterTokenRefreshedEventHandler	注册一个 SDK 成功刷新令牌时的回调。
PFEntityUnregisterTokenRefreshedEventHandler	取消注册令牌已刷新回调。

有关完整的 API 参考,请参阅 PFEntity 成员。

XBOX Services

PlayFab

获取实体句柄

句柄所有权和引用计数

获取实体信息

实体键

实体令牌

检查实体类型

玩家实体与游戏实体

令牌事件处理程序

令牌已过期

令牌已刷新

何时注册和取消注册

实用访问器

完整示例

API 参考

另请参阅

​获取实体句柄

​句柄所有权和引用计数

​获取实体信息

​实体键

​实体令牌

​检查实体类型

​玩家实体与游戏实体

​令牌事件处理程序

​令牌已过期

​令牌已刷新

​何时注册和取消注册

​实用访问器

​完整示例

​API 参考

​另请参阅

获取实体句柄

句柄所有权和引用计数

获取实体信息

实体键

实体令牌

检查实体类型

玩家实体与游戏实体

令牌事件处理程序

令牌已过期

令牌已刷新

何时注册和取消注册

实用访问器

完整示例

API 参考

另请参阅