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 遊戲和端點為目標。您可以在 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	擷取遊戲識別碼字串。請先呼叫 PFServiceConfigGetTitleIdSize 以判斷緩衝區大小。

複製控制代碼

當您需要在各自管理存留期的元件之間共用服務設定時，請使用 PFServiceConfigDuplicateHandle：

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

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

關閉順序

關閉是初始化的反向順序。您必須先將 Services 取消初始化，再將 Core 取消初始化，而且這兩個呼叫都是非同步的。

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 取消初始化

完整範例

常見錯誤

另請參閱