Migrating from the Legacy C++ API to the New C API

This document is a reference for games already integrated with the C++ API of 3.4.x or earlier (Stove::PCSDK namespace, Base_* · IAP_* · Ownership_* families) that are moving their code to the new C API (Stove_* family) introduced in 3.5.0.

You do not have to migrate to the new API. Since the 3.4.x API will continue to be supported, you can leave your existing integration code as is and simply replace the deployment files with the 3.5.0 version. This document is only necessary if you decide to migrate your code to the new API.

Please read in the following order.

1. First, review the basic structure of the new API. (Chapter 1)
2. Check what the functions and structures you are currently using will be replaced with. (Chapters 2 and 3)
3. Check to see if you are using any features that are not available in the new API. (Chapter 4)
4. When modifying the code, check for any changes in the calling syntax. (Chapter 5)

1. Basic Structure of the New API

The rules for the new interface are outlined in the "Basic Integration Guide" at the beginning of the Reference Guide. This chapter briefly summarizes only the information you need to know when migrating your code.

The number of deployment files is reduced to one.

With the new API, there is only BaseSDK.dll file that needs to be deployed along with the game. You no longer need to include files such as IAPSDK.dll, ViewSDK.dll, and PCBangSDK.dll, which used to be deployed for each module. This is because all features have been integrated into a single binary.

For games integrated with the existing 3.4.x API, please keep your deployment configuration as is. Regardless of whether the binaries are bundled, you must continue to include the individual module files as you have been doing. The number of deployment files will be reduced to one only if you have migrated to the new API.

The module categories have been removed.

The procedure for initializing each module has been removed. Calling Stove_Initialize once enables all payment, pop-up, PC Bang, and log functions, and you only need to call Stove_Uninitialize once to exit.

The module name has also been removed from function names. The prefix has been standardized to Stove_.

Base_GetUser        ->  Stove_GetUser
IAP_StartPurchase   ->  Stove_StartPurchase
View_AutoPopup      ->  Stove_AutoPopup

We use interface pointers instead of structures.

The old API directly declared and exchanged value structures (such as StovePCUser). The new API treats all objects as IStove* pointers and retrieves values using accessors.

// Old C++
StovePCUser user;
Base_GetUser(&user);
const wchar_t* nickname = user.GetNickname();

The new API is available in two forms: C functions and C++ methods, and they behave exactly the same. You can choose the form that best suits your project environment.

IStoveUser* user = nullptr;
Stove_GetUser(&user);
const wchar_t* nickName = Stove_IStoveUser_GetNickName(user);

The naming convention for C functions follows a consistent pattern, such as Stove_<Interface>_<Member>. Since SDK functions (such as Stove_GetUser) are free functions, they are called in the same way in both formats.

Parameters are also created as objects.

Parameters passed to the call are also created using a factory, rather than by declaring a structure. The value EStove<Module>TypeKind specifies which parameter to create.

IStoveInitializeParam* initParam =
    (IStoveInitializeParam*)Stove_CreateParam(k_EStoveBaseTypeKind_InitializeParam);
Stove_IStoveInitializeParam_SetShopKey(initParam, L"YOUR_SHOP_KEY");

Objects that have been passed in must be released.

Objects created by the SDK should be released after use. Use ShouldDestroy to determine whether an object needs to be released.

if (Stove_IStoveTypeBase_ShouldDestroy(obj))
    Stove_IStoveTypeBase_Destroy(obj);

Since this is a rule that did not exist in the old API, it is the part most often overlooked when porting code. This is explained in more detail in Chapter 5.

It is available in both C and C++ versions

Headers are divided into four types for each module, and stove_api.h is also provided, which allows you to include all of them on a single line.

2. Function Correspondence

Initialization and Termination

The functions for initialization, termination, and version lookup for each module are not included in the new API. They have been consolidated into three functions.

User Information and Environment

Regulatory Compliance Notice

Payment

Pop-up

PC Bang

Log

3. Correspondence Between Structures and Enumerations

General

User Information and Environment

Regulatory Compliance Notice

Payment

Pop-up

PC Bang and the log

4. Features Not Available in the New API

The following items do not have corresponding functions or structures in the new C API. If you are using these features, you should determine an alternative approach before porting your code.

Function

Structures and Enumerations

A Method That No Longer Exists

• Ex · Ex2 Extension Functions: The new API does not provide separate extension functions. The functionality previously handled by the existing Ex series—namely, the callback triggered when the popup closes, the added response fields, and the extended parameters—is now all included in a single default function.
• Module-by-Module Initialization: The process of individually initializing modules to use payment or pop-up features has been eliminated.
• Results Code by Module: The SDKResultCode code that existed in each module has been organized into two categories: common code and function-specific code.

5. Changes Made When Modifying the Code

Simply changing the name won't make the build succeed, because the calling syntax changes as well. The following six areas are where you actually need to modify the code.

5.1 Synchronous functions return their results as pointers.

The old API returned the value Result, and the result structure was declared by the caller, who then passed its address. The new API returns IStoveResult*, and the result object is passed as a double pointer.

// Old C++
StovePCUser user;
Result result = Base_GetUser(&user);
if (result.IsSuccessful())
{
    const wchar_t* nickname = user.GetNickname();
}

IStoveUser* user = nullptr;
IStoveResult* result = Stove_GetUser(&user);
if (Stove_IStoveResult_IsSuccessful(result))
{
    const wchar_t* nickName = Stove_IStoveUser_GetNickName(user);
    Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)user);
}
Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result);

• Check IsSuccessful() to see if it was successful. Do not use try-catch.
• Check the result code at GetResultCode(), and check which function generated the result at GetMethodCode().

5.2 Release any objects that were passed in

In the old API, value structures were automatically cleaned up when they went out of scope. In the new API, objects created by the SDK must be released by the caller.

if (Stove_IStoveTypeBase_ShouldDestroy(obj))
    Stove_IStoveTypeBase_Destroy(obj);

• The returned IStoveResult* will be released.
• Parameters created using Stove_CreateParam() are also released once the call is complete.
• Check the memory management table for each document to see which objects were passed to the callback. Some objects are owned by the SDK and must not be released.
• If it's difficult to verify in the document, you can determine it as ShouldDestroy, as shown above.

5.3 Parameters are created using the Factory pattern

// Old C++
StovePCInitializeParam initParam;
initParam.SetShopKey(L"YOUR_SHOP_KEY");
Base_Initialize(&initParam, OnInitializeFinished);

IStoveInitializeParam* initParam =
    (IStoveInitializeParam*)Stove_CreateParam(k_EStoveBaseTypeKind_InitializeParam);
Stove_IStoveInitializeParam_SetShopKey(initParam, L"YOUR_SHOP_KEY");

IStoveResult* result = Stove_Initialize(initParam);
// Check the results.

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result);
Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)initParam);

The value passed to Stove_CreateParam() is the TypeKind of the parameter you want to create. The value to be passed is specified in each parameter's documentation.

5.4 The initialization process is shorter.

Old C++ : Base_RestartAppIfNecessaryAsync -> Base_Initialize
         -> IAP_Initialize -> View_Initialize -> PCBang_Initialize -> Log_Initialize

New C   : Stove_RestartAppIfNecessary -> Stove_Initialize

• Remove all module-specific initialization calls. If you leave them in, the build will fail.
• Call Stove_Uninitialize only once when exiting as well. Please note that the notation has changed from UnInitialize to Uninitialize.
• Stove_Initialize is an asynchronous function. It immediately returns a value indicating whether the operation succeeded, without waiting for the completion callback.

5.5 A user data argument has been added to callbacks

Asynchronous functions receive void* userData along with a callback. You can use this value instead of a global variable in the callback when you need to locate the game object again.

// Old C++
void IAP_StartPurchase(const StovePCStartPurchaseParam* params,
                       OnStartPurchaseFinished onFinished);

// New C
void Stove_StartPurchase(const IStoveStartPurchaseParam* params,
                         OnStartPurchaseCallback onFinished,
                         OnIAPPopupDestroyCallback onDestroy,
                         void* userData1, void* userData2);

• Since SDK functions are free functions, their declarations are the same in both C and C++ environments.
• The function that opens a popup takes both a completion callback and a callback that is called when the popup closes. This corresponds to the part of the old API that used the Ex function.
• If a close callback is not required, pass nullptr.
• The callback is executed at the same time as before. Since it runs on the thread that called Stove_RunCallback(), you must continue to call it from within the game loop.

5.6 The code structure has changed.

The old API had a separate SDKResultCode for each module. The new API has been consolidated into two.

• If you have code that compares values numerically, check each one against the new enumeration. The same number may have a different meaning.
• The names of enumeration values follow the format k_E<Enum><Value>. "Success" is k_EStoveCommonResultCode_Success.
• You can check the table in each result code document to see if the code requires a guidance screen to be displayed to the user.

6. Order of Transfer

Instead of making all the changes at once, it’s easier to check how things work along the way if you break the process down into the following steps.

1. First, replace the header and linker settings. This involves removing the old API headers and replacing them with the new API headers, as explained in detail in Section 6.1.
2. Modify the initialization and shutdown code. Remove the module-specific initialization, reorganize the code as shown in Stove_Initialize and Stove_Uninitialize, and then verify that the game runs.
3. Modify the variable lookup function. Start by moving functions that return values directly, such as Stove_GetUser and Stove_GetGds, to get used to the rule of releasing objects.
4. Update the asynchronous functions. Move features that use callbacks—such as payment, pop-ups, and PC Bang—to the new functions. For sections that previously used the Ex function, reorganize them to use the closure callback argument.
5. Review the code branches. Replace the sections that used numerical comparisons and module-specific code with a new enumeration.
6. Clean up the deployment configuration. Change it so that only BaseSDK.dll is included and the module-specific files are dropped.
7. Review Chapter 4 again. Do a final check to see if there are any features that still require workarounds.

6.1 Replacing Headers and Modifying include Statements

The headers for the old API are located in the Include folder of the distribution package, with one per module, while enumerations, structures, and callback declarations are located in the Include/Misc folder. The headers for the new API are located in the Public/C folder for each module and are divided into four categories.

In the project settings, remove the header path for the old API, add the header path for the new API to the directory, and then update the include statements in the source code.

// Old C++
#include "BaseSDK.h"
#include "IAPSDK.h"
#include "ViewSDK.h"
#include "PCBangSDK.h"

The simplest method is to replace it with a single unified header. Since the four types of headers from all modules are included together, C accessors can be used immediately.

// New: The unified header includes all modules in a single line.
#include "stove_api.h"

You can also choose to include only the modules you need. In this case, to access interface members in a C environment, you must also include <module>_flat_api.h.

// New: When selecting and including a module
#include "base_api.h"
#include "base_flat_api.h"
#include "iap_api.h"
#include "iap_flat_api.h"
#include "view_api.h"
#include "view_flat_api.h"

• <module>_api.h includes <module>_types.h, and <module>_types.h includes <module>_misc.h. Therefore, there is no need to add the enumeration and structure headers separately.
• If you are only using the C++ method form, you do not need to include <module>_flat_api.h.
• If you have any code that directly includes the header Include/Misc from the old API, remove it as well. The new API does not have a header with that name.
• If you have listed the module-specific lib files as additional dependencies for the linker, organize them according to the Lib folder structure of the distribution package. There is only one binary BaseSDK.dll distributed with the game.