SDK 生命周期

本页涵盖 PlayFab Services SDK 的完整启动和关闭序列。每个游戏都遵循相同的高层模式：配置可选钩子、初始化 Core、创建服务配置、初始化 Services、执行业务逻辑，然后按相反顺序关闭。

初始化序列

初始化分为四步。第一步是可选的；其余三步是必需的。

PFMemSetFunctions (optional)  →  PFInitialize  →  PFServiceConfigCreateHandle  →  PFServicesInitialize

第 1 步：设置自定义内存钩子（可选）

如果你的游戏使用自定义内存分配器，请在调用任何其他 PlayFab API 之前调用 PFMemSetFunctions。这会将所有 SDK 的内存分配路由到你自己的 alloc 和 free 回调。

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

PFMemSetFunctions 必须在 PFInitialize 之前调用。一旦钩子设置完成，就不能再次调用。

如果你不需要自定义内存管理，可以跳过这一步。SDK 会使用默认的分配例程。

第 2 步：初始化 PlayFab Core

PFInitialize 设置 SDK 的全局状态，包括 HTTP 层和后台任务队列。具体签名因平台而异。

Windows、Linux、iOS 和 macOS

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

如果想控制哪个队列处理后台工作，请传入一个 XTaskQueueHandle。传入 nullptr 以使用默认的线程池队列。

Android

在 Android 上，你还必须提供 Java VM 和应用程序上下文，以便 SDK 可以初始化 libHttpClient：

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

如果你没有显式调用 PFInitialize，PFServicesInitialize 会使用默认参数在内部调用它。对于大多数游戏来说这没问题。但是，如果你通过 PFMemSetFunctions 使用自定义内存钩子，你必须自己调用 PFInitialize — 否则 PFServicesInitialize 会在你的内存钩子生效之前初始化 Core，SDK 会转而使用默认的分配例程。

第 3 步：创建服务配置

PFServiceConfigCreateHandle 创建一个句柄，告诉 SDK 目标是哪个 PlayFab 游戏（title）和端点。你可以在 Game Manager 中找到这两个值。

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

返回的 PFServiceConfigHandle 是所有后续登录调用所必需的。

第 4 步：初始化 PlayFab Services

PFServicesInitialize 在 Core 之上设置 Services 层（Inventory、Leaderboards、Friends 等）。

Windows、Linux、iOS 和 macOS

HRESULT hr = PFServicesInitialize(nullptr);

该参数保留供将来使用；请传入 nullptr。

Android

在 Android 上，传入一个包含 Java VM 和应用程序上下文的 HCInitArgs 结构：

HRESULT hr = PFServicesInitialize(nullptr, initArgs);

此调用成功后，SDK 便已准备就绪。你可以登录玩家并进行服务调用。

PFServiceConfigHandle 生命周期

PFServiceConfigHandle 是一个引用计数的句柄。SDK 通过引用计数管理其内部生命周期，但你负责关闭自己拥有的每一个句柄。

函数	描述
PFServiceConfigCreateHandle	创建新句柄。初始引用计数为 1。
PFServiceConfigDuplicateHandle	递增引用计数并返回第二个句柄。两个句柄都必须独立关闭。
PFServiceConfigCloseHandle	递减引用计数。当计数达到 0 时，配置会被销毁。
PFServiceConfigGetAPIEndpoint	获取 API 端点字符串。先调用 PFServiceConfigGetAPIEndpointSize 以确定缓冲区大小。
PFServiceConfigGetTitleId	获取 title ID 字符串。先调用 PFServiceConfigGetTitleIdSize 以确定缓冲区大小。

复制句柄

当你需要在管理自己生命周期的组件之间共享服务配置时，使用 PFServiceConfigDuplicateHandle：

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

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

关闭序列

关闭与初始化相反。你必须在 Core 之前反初始化 Services，且两个调用都是异步的。

Close handles  →  PFServicesUninitializeAsync  →  PFUninitializeAsync

第 1 步：关闭所有已打开的句柄

在拆除 SDK 之前，关闭你拥有的每一个 PFEntityHandle 和 PFServiceConfigHandle：

PFEntityCloseHandle(entityHandle);
entityHandle = nullptr;

PFServiceConfigCloseHandle(serviceConfigHandle);
serviceConfigHandle = nullptr;

第 2 步：反初始化 Services

PFServicesUninitializeAsync 拆除 Services 层。在继续之前等待其完成。

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

第 3 步：反初始化 Core

Services 清理完成后，调用 PFUninitializeAsync 拆除 Core：

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

如果你没有显式调用 PFInitialize，则可以跳过 PFUninitializeAsync。在这种情况下，PFServicesUninitializeAsync 会自动处理 Core 的清理。但是，如果你自己调用了 PFInitialize，则必须自己调用 PFUninitializeAsync。

完整示例

以下示例展示了 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);
}

常见错误

错误	发生的情况	解决方法
在 PFInitialize 之后调用 PFMemSetFunctions	调用失败。内存钩子只能在初始化之前设置。	将 PFMemSetFunctions 移到程序中的第一个 PlayFab 调用。
在 PFServicesUninitializeAsync 之前调用 PFUninitializeAsync	未定义行为。Core 已被拆除而 Services 仍依赖于它。	始终先反初始化 Services，等待完成后再反初始化 Core。
显式调用 PFInitialize 后忘记调用 PFUninitializeAsync	Core 资源泄漏。后台队列和 HTTP 层未清理。	如果你调用了 PFInitialize，就必须调用 PFUninitializeAsync。
未等待异步反初始化完成	清理仍在进行时进程可能已退出，导致崩溃或挂起。	使用 `XAsyncGetStatus(async, true)` 或 XAsyncBlock 回调来等待完成。
泄漏 PFServiceConfigHandle 或 PFEntityHandle	引用计数的资源未被释放，可能阻止干净关闭。	在调用反初始化之前关闭你创建或复制的每一个句柄。

XBOX Services

PlayFab

初始化序列

第 1 步：设置自定义内存钩子（可选）

第 2 步：初始化 PlayFab Core

Windows、Linux、iOS 和 macOS

Android

第 3 步：创建服务配置

第 4 步：初始化 PlayFab Services

Windows、Linux、iOS 和 macOS

Android

PFServiceConfigHandle 生命周期

复制句柄

关闭序列

第 1 步：关闭所有已打开的句柄

第 2 步：反初始化 Services

第 3 步：反初始化 Core

完整示例

常见错误

参见

​初始化序列

​第 1 步：设置自定义内存钩子（可选）

​第 2 步：初始化 PlayFab Core

​Windows、Linux、iOS 和 macOS

​Android

​第 3 步：创建服务配置

​第 4 步：初始化 PlayFab Services

​Windows、Linux、iOS 和 macOS

​Android

​PFServiceConfigHandle 生命周期

​复制句柄

​关闭序列

​第 1 步：关闭所有已打开的句柄

​第 2 步：反初始化 Services

​第 3 步：反初始化 Core

​完整示例

​常见错误

​参见

初始化序列

第 1 步：设置自定义内存钩子（可选）

第 2 步：初始化 PlayFab Core

Windows、Linux、iOS 和 macOS

Android

第 3 步：创建服务配置

第 4 步：初始化 PlayFab Services

Windows、Linux、iOS 和 macOS

Android

PFServiceConfigHandle 生命周期

复制句柄

关闭序列

第 1 步：关闭所有已打开的句柄

第 2 步：反初始化 Services

第 3 步：反初始化 Core

完整示例

常见错误

参见