Skip to content
Store Dev
Cập nhật lần cuối

PC SDK Native Reference

Based on SDK version 3.5.3. 106 items combined in alphabetical order.

Contents

NameKindModule
Basic Integration GuideIntegration GuideBase
EStoveBaseMethodCodeEnumBase
EStoveBaseTypeKindEnumBase
EStoveCommonResultCodeResult CodeBase
EStoveDiscountTypeEnumIAP
EStoveGameSupportMethodCodeEnumGameSupport
EStoveGameSupportTypeKindEnumGameSupport
EStoveIAPMethodCodeEnumIAP
EStoveIAPTypeKindEnumIAP
EStoveLogMethodCodeEnumLog
EStoveLogTypeKindEnumLog
EStoveOverlayModeEnumBase
EStoveOwnershipCodeEnumOwnership
EStoveOwnershipGameCodeEnumOwnership
EStoveOwnershipMethodCodeEnumOwnership
EStoveOwnershipTypeKindEnumOwnership
EStoveProductTypeCodeEnumIAP
EStovePurchaseLimitTypeCodeEnumIAP
EStovePurchaseOperationEnumIAP
EStovePurchaseProgressEnumIAP
EStoveResultCodeResult CodeBase
EStoveTermsOperationEnumIAP
EStoveWebViewModeEnumBase
IStoveAccessTokenStructBase
IStoveAchievementStructGameSupport
IStoveAchievementConditionStructGameSupport
IStoveAchievementListStructGameSupport
IStoveCallbackResultStructBase
IStoveChargeInfoStructIAP
IStoveConfirmPurchaseOutcomeStructIAP
IStoveConfirmPurchaseParamStructIAP
IStoveFetchAchievementParamStructGameSupport
IStoveFetchAchievementsParamStructGameSupport
IStoveFetchProductsParamStructIAP
IStoveFetchRankingParamStructGameSupport
IStoveFetchStatParamStructGameSupport
IStoveFetchTermsAgreementParamStructIAP
IStoveGdsStructBase
IStoveInitializeParamStructBase
IStoveInventoryItemStructIAP
IStoveInventoryListStructIAP
IStoveOrderProductParamStructIAP
IStoveOverImmersionInfoStructBase
IStoveOwnershipStructOwnership
IStoveOwnershipListStructOwnership
IStoveProductStructIAP
IStoveProductListStructIAP
IStovePurchasedProductStructIAP
IStovePurchaseParamStructIAP
IStoveRankStructGameSupport
IStoveRankingStructGameSupport
IStoveRestartAppIfNecessaryOutcomeStructBase
IStoveRestartAppIfNecessaryParamStructBase
IStoveResultStructBase
IStoveSendLogParamStructLog
IStoveSetGameProfileParamStructBase
IStoveSetStatOutcomeStructGameSupport
IStoveSetStatParamStructGameSupport
IStoveShopCategoryStructIAP
IStoveShopCategoryListStructIAP
IStoveShutdownInfoStructBase
IStoveSigninStructBase
IStoveStartPurchaseOutcomeStructIAP
IStoveStartPurchaseParamStructIAP
IStoveStatStructGameSupport
IStoveStatFullIdStructGameSupport
IStoveTermsAgreementOutcomeStructIAP
IStoveTypeBaseStructBase
IStoveUserStructBase
IStoveVietnamAgeRatingInfoStructBase
IStoveVietnamOverimmersionInfoStructBase
IStoveWebViewLayoutParamStructIAP
Stove_AccessTokenRenewedFunctionBase
Stove_CloseAllPopupsFunctionBase
Stove_ConfirmPurchaseFunctionIAP
Stove_CreateParamFunctionBase
Stove_FetchAchievementFunctionGameSupport
Stove_FetchAchievementsFunctionGameSupport
Stove_FetchInventoryFunctionIAP
Stove_FetchOwnershipsFunctionOwnership
Stove_FetchProductsFunctionIAP
Stove_FetchRankingFunctionGameSupport
Stove_FetchShopCategoriesFunctionIAP
Stove_FetchStatFunctionGameSupport
Stove_FetchTermsAgreementFunctionIAP
Stove_GetAccessTokenFunctionBase
Stove_GetCloudSavingPathFunctionBase
Stove_GetGdsFunctionBase
Stove_GetSigninFunctionBase
Stove_GetUserFunctionBase
Stove_GetVersionFunctionBase
Stove_InitializeFunctionBase
Stove_OpenExternalUrlFunctionBase
Stove_OverImmersionNotificationFunctionBase
Stove_RestartAppIfNecessaryFunctionBase
Stove_RunCallbackFunctionBase
Stove_RunCallbackWithTimeoutFunctionBase
Stove_SendLogFunctionLog
Stove_SetGameProfileFunctionBase
Stove_SetLanguageFunctionBase
Stove_SetStatFunctionGameSupport
Stove_ShutdownNotificationFunctionBase
Stove_StartPurchaseFunctionIAP
Stove_UninitializeFunctionBase
Stove_VietnamAgeRatingNotificationFunctionBase
Stove_VietnamOverimmersionNotificationFunctionBase

Basic Integration Guide

Kind Integration Guide · Module Base · Version 3.5.0

Description

You cannot mix the old API and the new API within a single game. If you decide to integrate using the new API covered in this document, you must write all of your integration code using the new API. Using both methods together will cause discrepancies in the initialization paths and deployment file structures, and we cannot guarantee proper operation. If you choose to keep your existing 3.4.x API integration as-is, please refer to the relevant documentation.

The Stove PCSDK Native API provides two main types of declarations: C++ methods and C flat functions. You can choose which one to use based on your environment and convenience.

  • In a typical C/C++ development environment, you can easily use the C++ method format.
  • The C flat function can be used in environments where C++ syntax is not available (e.g., Go, development of JavaScript-based game engine plugins, etc.).

If you're using a development environment that supports C++, it's more convenient to use the C++ method format. The code is shorter, and there are fewer type conversions. C flat functions were designed to enable integration in development environments that don't support C++ syntax; this serves the same purpose as the Steamworks SDK providing C headers in addition to the C++ interface.

All SDK objects are represented by IStove* opaque pointers, and their properties are accessed through accessor functions of the Stove_<Interface>_<Method>(self, ...) type.

Header files are provided in four different formats, one for each module, depending on the single binary (BaseSDK) integration.

FileRole
<module>_api.hDeclaring SDK Custom Functions (such as Stove_Initialize)
<module>_types.hC++ environment: IStove* interface definition (pure virtual function). C environment: opaque typedef struct
<module>_misc.hEnumeration Definitions (EStove<Module>TypeKind, EStove<Module>MethodCode, EStove<Module>ResultCode)
<module>_flat_api.hC-flat accessor for interface members (Stove_<Interface>_<Method>)

Unified Header stove_api.h: This is an "umbrella" header that combines all four types of headers (28 in total) from the seven modules (Base, GameSupport, IAP, Log, Ownership, PC bang, and View). Of these, 5 modules (Base, GameSupport, IAP, Log, and Ownership) can be used in Store Indie games. PC bang features are not officially supported for STOVE Store games. Since #include "stove_api.h" allows you to include the public C APIs for all modules at once in a single line, there is no need to include individual module headers separately. (You can still use the method of selecting only the modules you need and including their individual headers.)

Distribution Files: If you use only the new API, the only file distributed with the game is BaseSDK.dll. It does not include IAPSDK.dll, OwnershipSDK.dll, and GameSupportSDK.dll, which were previously distributed on a per-module basis.

The distribution package also includes headers for modules that cannot be used in StoreIndy games. The popup (view_*) is exclusively for Partners games. If you include it all at once using stove_api.h, these headers will be included as well, but you should only see the declarations, do not call them.

Declaration Forms

This document is organized into the following formats depending on the subject matter.

TargetNotation
SDK API Functions (such as Stove_Initialize)C-flat function (free function, same signature as C/C++)
Interface members (GetNickName, SetGameId, etc.)C++ methods + C flat functions
CallbackCallback typedef
  • C++ Method: This is a member function defined in the IStove* interface structure within *_types.h. Since most compilers support C++, you can use this form as-is to call it directly, as shown in self->Method().
  • C flat function: This is an entry point exposed from *_api.h / *_flat_api.h to extern "C" + __cdecl. It is provided for environments where C++ vtable calls are not possible, such as pure C or C#, but it can also be called in a C++ environment.
  • Both forms perform the same action. The C flat function internally calls the object's C++ method.

The SDK API function (Stove_<Method>) is a free function, not an interface member. It is declared from *_api.h to extern "C", and is called with the same signature by both C++ methods and C flat functions (in C/C# environments). (Example: IStoveResult* Stove_Initialize(const IStoveInitializeParam* initParam);, called identically in both C and C++)

Although the header also declares a typedef for the function pointer for each C-flat function (<function-name>_t), this document does not list them separately. Please refer to them only when dynamic loading (GetProcAddress) is required.

In the ## Example section of each function's documentation, the two forms are listed side by side under the C · C++ tabs. Since calling the same API using either form yields the same result, you only need to look at the tab that matches your project environment.

TabUsesAccessing Interface MembersObject Release
CC projects, or environments where vtable calls cannot be usedStove_IStoveResult_IsSuccessful(result)Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result)
C++A C++ project that uses the interface of *_types.h as-isresult->IsSuccessful()result->Destroy()

The SDK API functions (Stove_<Method>) are the same in both tabs. The only differences are in how interface members are accessed and how they are released. The C++ mentioned here refers to calling the new interface using C++ syntax, which differs from the old C++ interfaces (Stove::PCSDK::<Module>, old_native/).

Naming Rules

CategoryPatternExample
SDK FunctionsStove_<Method> (Free function without a module token)Stove_Initialize, Stove_StartPurchase, Stove_FetchProducts
Parameter Object Composite FactoryStove_CreateParam(int kind)Stove_CreateParam(k_EStoveBaseTypeKind_InitializeParam)
Interface AccessorsStove_<Interface>_<Method>Stove_IStoveUser_GetNickName(user)
Callback TypeOn<Action>CallbackOnRestartAppIfNecessaryCallback
Enumeration valuesk_E<Enum><Value>k_EStoveCommonResultCode_Success

Memory Lifetime

The responsibility for freeing an SDK object is determined by the ShouldDestroy flag set by IStoveTypeBase.

General Rule: You can determine whether any SDK object has been released using the following single line of code.

c
if (Stove_IStoveTypeBase_ShouldDestroy(obj))   // In C++: obj->ShouldDestroy()
    Stove_IStoveTypeBase_Destroy(obj); // In C++, obj->Destroy()

You don’t need to memorize the source of each object (Factory creation, synchronous return, out parameters, callbacks, or getter return) one by one; simply calling Destroy based on the return value of ShouldDestroy() will prevent both memory leaks and double release. The table below summarizes the return values of ShouldDestroy for each path for your reference.

Objects created by the Factory must be released by the caller: All structure pointers returned by the unified factory Stove_CreateParam(<TypeKind>) are ShouldDestroy == true, and you must free them by calling Stove_IStoveTypeBase_Destroy(obj) (or obj->Destroy() in C++) after you’re done using them. Failure to free them will result in a memory leak.

c
// Example: Create an IStoveRestartAppIfNecessaryParam using Stove_CreateParam
IStoveRestartAppIfNecessaryParam* restartParam = (IStoveRestartAppIfNecessaryParam*)
    Stove_CreateParam(k_EStoveBaseTypeKind_RestartAppIfNecessaryParam);

Stove_IStoveRestartAppIfNecessaryParam_SetGameId(restartParam, L"my_game_id");
Stove_IStoveRestartAppIfNecessaryParam_SetAppKey(restartParam, L"my_app_key");
// ... other setter calls ...

Stove_RestartAppIfNecessary(restartParam, OnRestartAppCallback, NULL);

// Be sure to release the resource after the API call returns
Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)restartParam);
Creation PathShouldDestroyRelease
Parameter object created using Factory(Stove_CreateParam)trueThe caller must free the memory, After the API call is complete, Stove_IStoveTypeBase_Destroy(self) (in C++, self->Destroy())
Synchronous API return value IStoveResult*trueThe caller must release it, Stove_IStoveTypeBase_Destroy(result)
Objects received as out parameters (IStoveUser**, IStoveGds**, IStoveSignin**)trueThe caller must release it, Stove_IStoveTypeBase_Destroy(*outXxx)
IStoveCallbackResult* and its associated objects (IStoveAccessToken*, IStoveStat*, IStoveAchievement*, ...) passed via an asynchronous callbackfalseSDK Ownership, The SDK is automatically released after the callback ends. The caller does not call Destroy
A child object returned by a parent object's getter (e.g., IStoveStatFullId* in IStoveStat::GetStatsFullId())falseOwned by the parent object, No separate release required

You must manually deallocate any structures passed as parameters. Even after passing a IStoveTypeBase*-derived object created by the Factory as a parameter to an API call, ownership of the object remains with the caller. Call Stove_IStoveTypeBase_Destroy(obj) (obj->Destroy() in C++) to deallocate the object after the API call returns (for synchronous APIs) or after the callback completes (for asynchronous APIs).

Example of Calling C: Passing order parameters to Stove_StartPurchase() and then releasing them:

c
// 1) Create parameter objects using the Factory
IStoveOrderProductParam* order = (IStoveOrderProductParam*)Stove_CreateParam(k_EStoveIAPTypeKind_OrderProductParam);
Stove_IStoveOrderProductParam_SetProductId(order, 12345);
Stove_IStoveOrderProductParam_SetQuantity(order, 1);

IStovePurchaseParam* option = (IStovePurchaseParam*)Stove_CreateParam(k_EStoveIAPTypeKind_PurchaseParam);
Stove_IStovePurchaseParam_SetOperation(option, k_EStovePurchaseOperation_WithWebViewAndConfirmResult);

IStoveStartPurchaseParam* params = (IStoveStartPurchaseParam*)Stove_CreateParam(k_EStoveIAPTypeKind_StartPurchaseParam);
IStoveOrderProductParam* products[] = { order };
Stove_IStoveStartPurchaseParam_SetProducts(params, products, 1);
Stove_IStoveStartPurchaseParam_SetPurchaseParam(params, option);

// 2) API Call
//    OnPopupDestroyed is an IAP callback that is called when the payment web view is closed.
Stove_StartPurchase(params, OnPurchaseFinished, OnPopupDestroyed, NULL, NULL);

// 3) After the API call returns, destroy all the parameter objects that were passed
//    (Since the caller created it using the Factory, ShouldDestroy == true)
Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)params);
Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)option);
Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)order);

C++ Call Example: Same scenario, direct call to a C++ method:

cpp
auto* order = static_cast<IStoveOrderProductParam*>(
    Stove_CreateParam(k_EStoveIAPTypeKind_OrderProductParam));
order->SetProductId(12345);
order->SetQuantity(1);

// ... (omitted)

Stove_StartPurchase(params, OnPurchaseFinished, OnPopupDestroyed, nullptr, nullptr);

params->Destroy();
option->Destroy();
order->Destroy();

Initialization Order

The initialization parameters are divided into two types of objects, IStoveRestartAppIfNecessaryParam for verifying launcher re-execution and IStoveInitializeParam for the actual initialization. Create each one separately and pass them to the corresponding function.

  1. Created IStoveRestartAppIfNecessaryParam as Stove_CreateParam(k_EStoveBaseTypeKind_RestartAppIfNecessaryParam)
  2. Configure settings such as environment variables, game IDs, and app keys using Stove_IStoveRestartAppIfNecessaryParam_Set*() (or restartParam->SetXxx() in C++)
  3. Call Stove_RestartAppIfNecessary(restartParam, callback, userData), Asynchronous. The SDK checks whether the launcher is running in a separate thread, and the result is passed via a callback.
  4. In the game's main loop, we start calling Stove_RunCallback() every frame. Since the callback for Stove_RestartAppIfNecessary() is dispatched when Stove_RunCallback() is called, the Stove_RunCallback() loop must start running immediately after the call in order to receive the callback.
  5. In the callback, if IsRestartRequired() == false, call Stove_Initialize() in the order shown below, (if IsRestartRequired() == true, the SDK will relaunch the app via the launcher, so terminate the current process)
    1. Created as Stove_CreateParam(k_EStoveBaseTypeKind_InitializeParam) from IStoveInitializeParam
    2. To use IAP together, set SetMainWndHandle() to be the parent window of the payment webview along with SetShopKey().
    3. Stove_Initialize(initParam) call, Synchronous, IStoveResult* returns immediately. The IAP module is also initialized based on the specified value.
  6. If the returned IStoveResult* result code is 0 (success), it can be used. Destroy after use.
  7. Keep the Stove_RunCallback() loop running while the game is running (main thread)
  8. Call Stove_Uninitialize() upon termination (must return IStoveResult* Destroy)
  9. restartParam and initParam are each released via Stove_IStoveTypeBase_Destroy() after they have finished executing (after the callback completes / after Stove_Initialize() is returned).

Stove_RestartAppIfNecessary() is an asynchronous function. The callback is dispatched on the thread that called Stove_RunCallback(), not on an internal SDK thread. Therefore, if you do not run Stove_RunCallback() in the game loop after calling Stove_RestartAppIfNecessary(), the callback will not be invoked and initialization will not proceed.

Stove_Initialize(initParam) is a synchronous function. It does not accept a callback and immediately returns IStoveResult*. Be sure to call it within the IsRestartRequired() == false branch of the Stove_RestartAppIfNecessary() callback. After checking the result code, the caller should release it using Stove_IStoveTypeBase_Destroy(result).

The new interface does not require module-specific initialization or termination. Stove_Initialize() A single operation activates all features, including payment, PC Bang, logs, ownership, and game support, simultaneously.

Callback Execution Rules

  • All callbacks for asynchronous APIs use the __cdecl calling convention.
  • The callback runs on the thread (main/UI thread) that called Stove_RunCallback(). It does not run on an internal SDK thread.
  • The IStoveCallbackResult* and associated object pointer passed as callback parameters are valid only during the callback call. Destroy() is not valid.
  • One-time callbacks (such as VietnamAgeRating and VietnamOverimmersion) must be called after the point at which rendering is possible.
  • The onFinished callback in the asynchronous API is a required parameter. If you do not specify it, a k_EStoveCommonResultCode_InvalidParam(5) error occurs.

userData Parameter Rules

Asynchronous APIs accept the void* userData parameter along with a callback function. This value is not interpreted by the SDK but is passed on exactly as is when the callback is invoked. It serves as a channel for the game (or developer) to pass arbitrary context data into the callback.

Usage Pattern: Pass information to be used within the callback, such as object pointers from the game code, request IDs, and identifiers for ongoing tasks. Within the callback, retrieve this information using IStoveCallbackResult::GetUserData() (Stove_IStoveCallbackResult_GetUserData(callbackResult) in C).

Memory Lifespan:

  • void* Since this is a pointer type, the SDK does not perform any management on the corresponding memory. Developers must pay close attention to allocation, deallocation, lifetime management, and thread safety during development.
  • For one-time callbacks (such as StartPurchase and FetchProducts), you can safely release the callback after it has been called exactly once.
  • For recurring callbacks (such as Stove_AccessTokenRenewed and Stove_OverImmersionNotification), userData must remain active until the SDK is terminated or unregistered.
  • Be careful not to let userData point to a stack variable or a temporary object. By the time the callback is executed, that scope will have already ended, resulting in a dangling pointer that could cause a crash.
  • Functions that accept two callbacks (such as onFinished and onDestroy) operate independently of userData1 and userData2. Be sure to release them separately according to each callback's lifespan.

The SDK makes no assumptions about the content, size, or ownership of userData. Passing NULL is also allowed. If you do not use it, pass NULL.

Example C: The game dynamically allocates and passes a context structure, which is then freed after use in the callback:

c
typedef struct GamePurchaseCtx
{
    int     requestId;
    void*   uiHandle;
} GamePurchaseCtx;

void __cdecl OnPurchaseFinished(const IStoveCallbackResult* result, const IStoveStartPurchaseOutcome* purchase)
{
    GamePurchaseCtx* ctx = (GamePurchaseCtx*)Stove_IStoveCallbackResult_GetUserData(result);
    // Post-processing on the game side using ctx->requestId and ctx->uiHandle

    free(ctx);  // Caller releases it directly — the SDK is not involved
}

// Call Section
GamePurchaseCtx* ctx = (GamePurchaseCtx*)malloc(sizeof(GamePurchaseCtx));
ctx->requestId = 12345;
ctx->uiHandle  = myUiHandle;

Stove_StartPurchase(params, OnPurchaseFinished, OnPopupDestroyed, ctx, NULL);
//                                                                  ^^^  ^^^^
//                                                                  userData1 (onFinished)
//                                                                       userData2 (onDestroy) — not used

In the example above, if ctx is deallocated before the OnPurchaseFinished callback is called, a crash will occur due to a dangling pointer. Be sure to maintain the lifetime of ctx until the callback is called.

Common Interface

For types shared by all modules, I've only included links to the respective documents. Please refer to each document for the details.

  • IStoveTypeBase: This is the top-level interface for all SDK objects. It is responsible for runtime type identification and release lifecycle management (ShouldDestroy / Destroy).
  • IStoveResult: This is the result of a synchronous API call. It contains the method code and the result code.
  • IStoveCallbackResult: This is the result passed to an asynchronous callback. It is valid only while the callback is being called.
TypeDocument
IStoveTypeBaseIStoveTypeBase
IStoveResultIStoveResult
IStoveCallbackResultIStoveCallbackResult

Notes

  • Stove_RestartAppIfNecessary() must be called before Stove_Initialize(), and to receive its callback, Stove_RunCallback() must be running in the game loop immediately after the call.
  • Stove_Initialize() is a synchronous function, so it doesn't accept a callback, but you must call it from within the callback of Stove_RestartAppIfNecessary() (the IsRestartRequired() == false branch).
  • Since userData is a void* that is not managed by the SDK, if you allow it to point to a stack variable or a temporary object, it will become a dangling pointer at the time of the callback and may cause a crash.

See Also

DocumentContent
Stove_CreateParamParameter Object Composite Factory
IStoveRestartAppIfNecessaryOutcomeStove_RestartAppIfNecessary() Result passed to the callback (IsRestartRequired())

EStoveBaseMethodCode

Kind Enum · Module Base · Version 3.5.0

Description

Identifies which SDK method generated this result based on the value retrieved as IStoveResult::GetMethodCode(). It is used for logging and error routing.

Declaration

c
typedef enum EStoveBaseMethodCode
{
    k_EStoveBaseMethodCode_Invalid = -1,
    k_EStoveBaseMethodCode_BaseInitialize = 1,
    // ... See the table of enumerated values below
    k_EStoveBaseMethodCode_GetTranslateLanguage = 119U,

    k_EStoveBaseMethodCode_Max = 0x7fffffff
} EStoveBaseMethodCode;

Enum Values

Lifecycle / Versioning

CodeNameDescription
-1k_EStoveBaseMethodCode_InvalidNot used
1k_EStoveBaseMethodCode_BaseInitializeStove_Initialize
2k_EStoveBaseMethodCode_BaseUninitializeStove_Uninitialize
5k_EStoveBaseMethodCode_BaseGetVersionStove_GetVersion
,6 ~ 63Not in use (reserved section)

Public APIs

CodeNameDescription
64k_EStoveBaseMethodCode_GetAccessTokenStove_GetAccessToken
65k_EStoveBaseMethodCode_AccessTokenRenewedStove_AccessTokenRenewed
66k_EStoveBaseMethodCode_GetUserStove_GetUser
67k_EStoveBaseMethodCode_SetLanguageStove_SetLanguage
68k_EStoveBaseMethodCode_OverImmersionNotificationStove_OverImmersionNotification
69k_EStoveBaseMethodCode_ShutdownNotificationStove_ShutdownNotification
,70, 71Not in use (reserved numbers that have been retired for internal use only)
72k_EStoveBaseMethodCode_SetGameProfileStove_SetGameProfile
73k_EStoveBaseMethodCode_GetGdsStove_GetGds
74k_EStoveBaseMethodCode_GetSigninStove_GetSignin
75k_EStoveBaseMethodCode_RestartAppIfNecessaryStove_RestartAppIfNecessary
76k_EStoveBaseMethodCode_RestartAppIfNecessaryAsyncAsynchronous processing path for Stove_RestartAppIfNecessary
77k_EStoveBaseMethodCode_OpenExternalUrlStove_OpenExternalUrl
78k_EStoveBaseMethodCode_GetCloudSavingPathStove_GetCloudSavingPath, Exclusive to StoreIndi
79k_EStoveBaseMethodCode_VietnamAgeRatingNotificationStove_VietnamAgeRatingNotification
80k_EStoveBaseMethodCode_VietnamOverimmersionNotificationStove_VietnamOverimmersionNotification
81k_EStoveBaseMethodCode_CloseAllPopupsStove_CloseAllPopups(Single binary integration, Closes both the IAP and View pop-ups)
,82 ~ 95Not in use (reserved section)

Private getters (private getters exposed to other SDK modules, not exposed to the game)

CodeNameDescription
115k_EStoveBaseMethodCode_GetEnvPrivatePrivate getter, For use by other SDK modules only; not exposed to the game
116k_EStoveBaseMethodCode_GetGameIdPrivatePrivate getter, For use by other SDK modules only; not exposed to the game
117k_EStoveBaseMethodCode_GetMemberNoPrivatePrivate getter, Reserved for other SDK modules; not exposed to the game
118k_EStoveBaseMethodCode_GetPublicIpPrivate getter, For use by other SDK modules only; not exposed to the game
119k_EStoveBaseMethodCode_GetTranslateLanguagePrivate getter, For use by other SDK modules only; not exposed to the game

Other

CodeNameDescription
,120 ~ 0x7ffffffeNot in use (reserved section)
0x7fffffffk_EStoveBaseMethodCode_MaxNot used

Values whose names include Internal (3, 4, 96–108, 110–114) are for internal SDK use only and have been excluded from the table. 109 is a reserved number that appears in the source code without a name, marked only with a "Deprecated" comment.

Example

c
IStoveResult* result = Stove_Initialize(initParam);

if (Stove_IStoveResult_GetMethodCode(result) == k_EStoveBaseMethodCode_BaseInitialize)
{
    // Please implement logic to verify that this result was generated by a call to `Stove_Initialize()`.
}

Notes

  • The code for the "Internal" methods starting from number 96 is used for internal SDK operations, such as reporting playtime, configuring the server, and processing tokens, and does not correspond to any APIs that can be called directly from the game.
  • The private getters numbered 115–119 were included in the table because their names do not contain Internal, but they are private APIs exposed only to other SDK modules and are not available in the game.
  • Items 3 and 4 (InternalSend81Plug, InternalUpdate81Plug) are also excluded from the table because their names contain Internal.
  • In the old interface, value names did not include underscores (e.g., k_EStoveBaseMethodCodeInvalid). In the current interface, an underscore is inserted between the type name and the value name, as in k_EStoveBaseMethodCode_Invalid.

Changelog

VersionChange
3.5.0First Published

See Also


EStoveBaseTypeKind

Kind Enum · Module Base · Version 3.5.0

Description

IStoveTypeBase is the value that identifies the concrete type instance. It is used when requesting a specific parameter object in Stove_CreateParam() and when identifying the runtime type in IStoveTypeBase::GetTypeKind().

The value range is 0 to 999. These are divided into the result and data types returned or passed by the SDK, and the parameter types created by the caller using Stove_CreateParam(). This range is designed not to overlap with the TypeKind enumeration of other SDK modules, so you can create parameters for all modules using just Stove_CreateParam().

Declaration

c
typedef enum EStoveBaseTypeKind
{
    k_EStoveBaseTypeKind_Invalid = -1,
    k_EStoveBaseTypeKind_Base = 0,
    // ... See the table of enumerated values below
    k_EStoveBaseTypeKind_SetGameProfileParam = 502,
    k_EStoveBaseTypeKind_Max = 0x7fffffff,
} EStoveBaseTypeKind;

Enum Values

Result / Data types (returned by the SDK or passed via callback)

CodeNameDescription
-1k_EStoveBaseTypeKind_InvalidNot used
0k_EStoveBaseTypeKind_BaseIStoveTypeBase
1k_EStoveBaseTypeKind_StoveResultIStoveResult
2k_EStoveBaseTypeKind_StoveCallbackResultIStoveCallbackResult
3k_EStoveBaseTypeKind_StoveUserIStoveUser
4k_EStoveBaseTypeKind_StoveAccessTokenIStoveAccessToken
5k_EStoveBaseTypeKind_StoveGdsIStoveGds
6k_EStoveBaseTypeKind_StoveSigninIStoveSignin
7k_EStoveBaseTypeKind_StoveOverImmersionInfoIStoveOverImmersionInfo
8k_EStoveBaseTypeKind_StoveVietnamAgeRatingInfoIStoveVietnamAgeRatingInfo
9k_EStoveBaseTypeKind_StoveVietnamOverimmersionInfoIStoveVietnamOverimmersionInfo
10k_EStoveBaseTypeKind_StoveShutdownInfoIStoveShutdownInfo
11k_EStoveBaseTypeKind_StoveRestartAppIfNecessaryOutcomeIStoveRestartAppIfNecessaryOutcome
,12 ~ 499Not used (reserved range between the result/data type and the parameter type range)

Parameter types (created by the caller using Stove_CreateParam())

CodeNameDescription
500k_EStoveBaseTypeKind_RestartAppIfNecessaryParamIStoveRestartAppIfNecessaryParam
501k_EStoveBaseTypeKind_InitializeParamIStoveInitializeParam
502k_EStoveBaseTypeKind_SetGameProfileParamIStoveSetGameProfileParam
,503 ~ 0x7ffffffeNot in use (reserved section)
0x7fffffffk_EStoveBaseTypeKind_MaxNot used

Example

c
IStoveSetGameProfileParam* profileParam =
    (IStoveSetGameProfileParam*)Stove_CreateParam(k_EStoveBaseTypeKind_SetGameProfileParam);

Notes

  • The parameter type (500 series) is used as the Stove_CreateParam() argument. The result/data type (0–11) is returned by the SDK or passed via a callback, so you do not create it yourself.
  • In the old interface, value names did not include an underscore (e.g., k_EStoveBaseTypeKindInvalid). In the current interface, an underscore is inserted between the type name and the value name, as in k_EStoveBaseTypeKind_Invalid.
  • In the old interface, IStoveInitializeParam was a larger structure that included Environment, GameId, and AppKey, but now those fields have been separated into field 500 (RestartAppIfNecessaryParam), while field 501 (InitializeParam) contains only ShopKey and MainWndHandle.

Changelog

VersionChange
3.5.0First Published

See Also


EStoveCommonResultCode

Kind Result Code · Module Base · Version 3.5.0

Description

This is the result code used by all Stove SDK modules. It is retrieved as IStoveResult::GetResultCode(); a value of 0 (Success) indicates success.

For module-specific result codes (300 and above), see EStoveResultCode.

Declaration

c
typedef enum EStoveCommonResultCode
{
    k_EStoveCommonResultCode_Success = 0,
    k_EStoveCommonResultCode_Fail = 1,
    // ... See the table of enumerated values below
    k_EStoveCommonResultCode_UnknownError = 255,

    k_EStoveCommonResultCode_Max = 0x7fffffff
} EStoveCommonResultCode;

Enum Values

General Results

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
1k_EStoveCommonResultCode_FailGeneral Failurex

Configuration/Parameter Validation Failed

CodeNameDescriptionShow to UserIn-Game Message
2k_EStoveCommonResultCode_InvalidConfigThe setting is invalid.x
3k_EStoveCommonResultCode_InvalidLogLevelThe log level value is invalid.x
4k_EStoveCommonResultCode_InvalidLogPathThe log path is invalid.x
5k_EStoveCommonResultCode_InvalidParamThe parameter is invalid.x
,6 ~ 15Not in use (reserved section),,

Initialization State Error

CodeNameDescriptionShow to UserIn-Game Message
16k_EStoveCommonResultCode_BaseNotInitializedThe SDK has not been initialized.x
17k_EStoveCommonResultCode_NotInitializedThis module has not been initialized.x
18k_EStoveCommonResultCode_AlreadyInitializedIt is already initialized.x

Token/Entity Error

CodeNameDescriptionShow to UserIn-Game Message
19k_EStoveCommonResultCode_InvalidAccessTokenThe AccessToken is invalid.OYour login session has expired. Please close the game and restart it. [OK]
20k_EStoveCommonResultCode_NullTokenEntityThe token entity is null.x
21k_EStoveCommonResultCode_NullEntityThe entity is null.x

If you receive the code below, you must exit the game. The game cannot proceed normally.

  • 19 k_EStoveCommonResultCode_InvalidAccessToken, Your login session has expired and needs to be refreshed

HTTP/Response Errors

CodeNameDescriptionShow to UserIn-Game Message
22k_EStoveCommonResultCode_HttpErrorAn HTTP error has occurredOThe network connection is unstable. Please check your network status and try again. [OK]
23k_EStoveCommonResultCode_ResponseErrorThis is a server response error.OThe network connection is unstable. Please check your network status and try again. [OK]
24k_EStoveCommonResultCode_ResponseInvalidCodeThe server response code is invalid.OThe network connection is unstable. Please check your network status and try again. [OK]
25k_EStoveCommonResultCode_ResponseValueIsNullThe server response value is null.OThe network connection is unstable. Please check your network status and try again. [OK]
26k_EStoveCommonResultCode_ResponseInvalidValueFormatThe format of the server response is invalid.OThe network connection is unstable. Please check your network status and try again. [OK]

Other Conditions

CodeNameDescriptionShow to UserIn-Game Message
,27, 28Not in use (discontinued number),,
29k_EStoveCommonResultCode_AsyncOperationInProgressAn asynchronous task is already in progress.x
30k_EStoveCommonResultCode_BaseUninitializedThe SDK has already been unlocked (Stove_Uninitialize).x
31k_EStoveCommonResultCode_NotSupportedCountryThis country/region is not supported.x
33k_EStoveCommonResultCode_PopupNotCreatedThe task terminated without creating a popup. This code is intended solely for internal cleanup and is not passed to the game callback (all interfaces intercept it).x
34k_EStoveCommonResultCode_WebviewClosedBeforeCompleteThe WebView closed before the task was completed.OThe purchase was not completed successfully. Please try again. [OK]

Local DB Failure (Common to All Modules)

CodeNameDescriptionShow to UserIn-Game Message
40k_EStoveCommonResultCode_LocalDbCreateWorkingDirectoryFailedFailed to create the local DB working directoryx
41k_EStoveCommonResultCode_LocalDbConnectFailedFailed to connect to the local databasex
42k_EStoveCommonResultCode_LocalDbCreateTableFailedFailed to create a local database tablex
43k_EStoveCommonResultCode_LocalDbDisconnectFailedFailed to disconnect from the local databasex
44k_EStoveCommonResultCode_LocalDbWriteFailedFailed to write to the local databasex
,45 ~ 59Not in use (reserved for future Local DB/payload/storage code),,

WebView/Popup UI Failure (Shared Module)

CodeNameDescriptionShow to UserIn-Game Message
60k_EStoveCommonResultCode_ViewUiNotInitializedThe Popup/WebView UI subsystem has not been initialized.x
61k_EStoveCommonResultCode_ViewUiUninitFailedFailed to close the Popup/WebView UI subsystemx
62k_EStoveCommonResultCode_WebviewCreateFailFailed to create a WebViewx
63k_EStoveCommonResultCode_WebviewLoadUrlFailFailed to load the URL in the WebViewx
64k_EStoveCommonResultCode_WebviewCreateCookieFailFailed to set WebView cookiesOThe page cannot be loaded. Please try again. [OK]
65k_EStoveCommonResultCode_WebviewCloseAllFailFailed to close all web views/pop-upsx
66k_EStoveCommonResultCode_WebviewCloseFailFailed to close the WebView/popupx
67k_EStoveCommonResultCode_NoPopupDataThere is no pop-up data to display.OThere is no pop-up configuration information, so there is no window to display. [OK]
68k_EStoveCommonResultCode_CloseAllPopupsFailedOne or more pop-ups could not be closed during call Stove_CloseAllPopups (IAP+View integrated call)x
,69 ~ 79Not in use (reserved for future WebView/pop-up UI code),,

Parameter/Payload Validation (Common to All Modules)

CodeNameDescriptionShow to UserIn-Game Message
80k_EStoveCommonResultCode_ParameterLengthExceededThe request parameters exceeded the maximum length.OThe payment information is invalid, so we cannot process the payment. Please try again. [OK]
81k_EStoveCommonResultCode_InvalidJsonStringThe JSON string format is invalid.OThe payment information is invalid, so we cannot process the payment. Please try again. [OK]
82k_EStoveCommonResultCode_PayloadSizeExceededThe payload exceeds the maximum allowed size.x
,83 ~ 248Not in use (reserved section),,

Network Transmission Failure

CodeNameDescriptionShow to UserIn-Game Message
249k_EStoveCommonResultCode_NetworkTransportErrorThis is a network transmission error. The HTTP backend's native error code IStoveCallbackResult::GetExternalError() is returned (e.g., WinHTTP 12002/12007/12029).x
,250Not in use (reserved section),,

System/Runtime Failure

CodeNameDescriptionShow to UserIn-Game Message
251k_EStoveCommonResultCode_PcsdkDllNotFoundThe PCSDK DLL cannot be foundx
252k_EStoveCommonResultCode_NotImplementedThis feature has not been implemented.x
253k_EStoveCommonResultCode_UnmanagedExceptionAn unmanaged exception has occurred.OA temporary issue has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionA managed exception has occurred.OA temporary issue has occurred. Please try again. [OK]
255k_EStoveCommonResultCode_UnknownErrorAn unknown error has occurred.x
,256 ~ 0x7ffffffeNot in use (reserved section),,
0x7fffffffk_EStoveCommonResultCode_MaxNot used,,

Example

c
IStoveResult* result = Stove_Uninitialize();

if (Stove_IStoveResult_GetResultCode(result) == k_EStoveCommonResultCode_Success)
{
    // Please implement the logic for a successful outcome.
}
else
{
    // Please implement the logic for when an error occurs.
}

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result);

Notes

  • These are the result codes used by all APIs and other SDK modules.
  • Module-specific codes are defined as EStoveResultCode (300~), and ranges are divided to ensure that the numbers do not overlap with this enumeration. Module-specific codes such as EStoveBaseResultCode and EStoveIAPResultCode from the old interface no longer exist.
  • In the old interface, value names did not include underscores (e.g., k_EStoveCommonResultCodeSuccess). In the current interface, an underscore is inserted between the type name and the value name, as in k_EStoveCommonResultCode_Success.

Changelog

VersionChange
3.5.0Initial release (consolidates duplicate code across modules into this enumeration via a single binary integration)

See Also


EStoveDiscountType

Kind Enum · Module IAP · Version 3.5.0

Description

It returns IStoveProduct as DiscountType and determines how to interpret DiscountTypeValue.

Declaration

c
typedef enum EStoveDiscountType
{
    k_EStoveDiscountType_None = 0,
    k_EStoveDiscountType_FixedRate = 1,
    k_EStoveDiscountType_FlatRate = 2,
    k_EStoveDiscountType_Max = 0x7fffffff
} EStoveDiscountType;

Enum Values

CodeNameDescription
0k_EStoveDiscountType_NoneNo discount
1k_EStoveDiscountType_FixedRatePercentage discount (e.g., 10% off), DiscountTypeValue is a percentage value.
2k_EStoveDiscountType_FlatRateFixed-amount discount (e.g., $2 off), DiscountTypeValue is the discount amount in the product's currency.
0x7fffffffk_EStoveDiscountType_MaxNot used

Example

c
int32_t discountType = Stove_IStoveProduct_GetDiscountType(product);
int32_t discountValue = Stove_IStoveProduct_GetDiscountTypeValue(product);

if (discountType == k_EStoveDiscountType_FixedRate)
{
    // Please interpret `discountValue` as a percentage.
}
else if (discountType == k_EStoveDiscountType_FlatRate)
{
    // Please interpret "discountValue" as a fixed amount based on the product's currency.
}

Notes

See Also


EStoveGameSupportMethodCode

Kind Enum · Module GameSupport · Version 3.5.0

Description

EStoveGameSupportMethodCode is a value that identifies which statistics and achievements API generated IStoveResult. It can be queried as IStoveResult::GetMethodCode()(Stove_IStoveResult_GetMethodCode()) and is used in log entries and error-handling branches.

The value range for this enumeration is 5000 to 5999 (module block), and the values are numbered consecutively in the order of the public API.

Declaration

c
typedef enum EStoveGameSupportMethodCode
{
    k_EStoveGameSupportMethodCode_Invalid = -1,
    k_EStoveGameSupportMethodCode_FetchStat = 5000,
    // ... See the table of enumerated values below
    k_EStoveGameSupportMethodCode_FetchRanking = 5004,
    k_EStoveGameSupportMethodCode_Max = 0x7fffffff
} EStoveGameSupportMethodCode;

Enum Values

CodeNameDescription
-1k_EStoveGameSupportMethodCode_InvalidNot used
5000k_EStoveGameSupportMethodCode_FetchStatStove_FetchStat
5001k_EStoveGameSupportMethodCode_SetStatStove_SetStat
5002k_EStoveGameSupportMethodCode_FetchAchievementStove_FetchAchievement
5003k_EStoveGameSupportMethodCode_FetchAchievementsStove_FetchAchievements
5004k_EStoveGameSupportMethodCode_FetchRankingStove_FetchRanking
0x7fffffffk_EStoveGameSupportMethodCode_MaxNot used

Example

c
void OnGetStatFinished(const IStoveCallbackResult* callbackResult, const IStoveStat* stat)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);
    uint32_t methodCode = Stove_IStoveResult_GetMethodCode(result); // k_EStoveGameSupportMethodCode_FetchStat
}

Notes

  • The value range (5000–5999) does not overlap with the MethodCode values of other modules.

Changelog

VersionChange
3.5.0First Published

See Also


EStoveGameSupportTypeKind

Kind Enum · Module GameSupport · Version 3.5.0

Description

EStoveGameSupportTypeKind is a value that identifies the concrete type of the IStoveTypeBase series of objects handled by the statistics and achievements features. This value is passed when requesting a specific parameter object via Stove_CreateParam(), and it is also used when checking the actual type of an object at runtime via IStoveTypeBase::GetTypeKind() (Stove_IStoveTypeBase_GetTypeKind()).

The value range for this enumeration is 5000 to 5999. The result/data types returned or passed by the SDK are in the 5000 range, while the parameter types created by the caller using Stove_CreateParam() are in the 5500 range; the values are not consecutive. Since the value ranges do not overlap with the TypeKind enumerations of other modules, you can create parameters for all modules using just Stove_CreateParam().

Declaration

c
typedef enum EStoveGameSupportTypeKind
{
    k_EStoveGameSupportTypeKind_Invalid = -1,
    k_EStoveGameSupportTypeKind_StatFullId = 5000,
    // ... See the table of enumerated values below
    k_EStoveGameSupportTypeKind_FetchRankingParam = 5504,
    k_EStoveGameSupportTypeKind_Max = 0x7fffffff
} EStoveGameSupportTypeKind;

Enum Values

Result / Data types (returned by the SDK or passed via callback)

CodeNameDescription
-1k_EStoveGameSupportTypeKind_InvalidNot used
5000k_EStoveGameSupportTypeKind_StatFullIdIStoveStatFullId
5001k_EStoveGameSupportTypeKind_StatIStoveStat
5002k_EStoveGameSupportTypeKind_SetStatOutcomeIStoveSetStatOutcome
5003k_EStoveGameSupportTypeKind_AchievementConditionIStoveAchievementCondition
5004k_EStoveGameSupportTypeKind_AchievementIStoveAchievement
5005k_EStoveGameSupportTypeKind_RankIStoveRank
5006k_EStoveGameSupportTypeKind_AchievementListIStoveAchievementList
5007k_EStoveGameSupportTypeKind_RankingIStoveRanking
,5008 ~ 5499Not used (reserved range between the result/data type and the parameter type range)

Parameter types (created by the caller using Stove_CreateParam())

CodeNameDescription
5500k_EStoveGameSupportTypeKind_FetchStatParamIStoveFetchStatParam
5501k_EStoveGameSupportTypeKind_SetStatParamIStoveSetStatParam
5502k_EStoveGameSupportTypeKind_FetchAchievementParamIStoveFetchAchievementParam
5503k_EStoveGameSupportTypeKind_FetchAchievementsParamIStoveFetchAchievementsParam
5504k_EStoveGameSupportTypeKind_FetchRankingParamIStoveFetchRankingParam
,5505 ~ 0x7ffffffeNot in use (reserved section)
0x7fffffffk_EStoveGameSupportTypeKind_MaxNot used

Example

c
IStoveFetchStatParam* param =
    (IStoveFetchStatParam*)Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchStatParam);

Notes

  • The data/result type (5000) is the type returned by the SDK via a callback, and it cannot be set to Stove_CreateParam().
  • The parameter type (5500) is the type that the caller must create using Stove_CreateParam().

Changelog

VersionChange
3.5.0First Published

See Also


EStoveIAPMethodCode

Kind Enum · Module IAP · Version 3.5.0

Description

Search for IStoveResult::GetMethodCode() to identify which payment API call generated this result. This is used when branching log entries or error handling by API.

The values range from 2000 to 2999 and are assigned sequentially according to the order of the payment feature's public APIs.

Declaration

c
typedef enum EStoveIAPMethodCode
{
    k_EStoveIAPMethodCode_Invalid = -1,
    k_EStoveIAPMethodCode_FetchShopCategories = 2000,
    // ... See the table of enumerated values below
    k_EStoveIAPMethodCode_Max = 0x7fffffff
} EStoveIAPMethodCode;

Enum Values

CodeNameDescription
-1k_EStoveIAPMethodCode_InvalidNot used
2000k_EStoveIAPMethodCode_FetchShopCategoriesStove_FetchShopCategories
2001k_EStoveIAPMethodCode_FetchProductsStove_FetchProducts
2002k_EStoveIAPMethodCode_StartPurchaseStove_StartPurchase
2003k_EStoveIAPMethodCode_ConfirmPurchaseStove_ConfirmPurchase
2004k_EStoveIAPMethodCode_FetchInventoryStove_FetchInventory
2005k_EStoveIAPMethodCode_FetchTermsAgreementStove_FetchTermsAgreement
2006k_EStoveIAPMethodCode_WithdrawGameStove_WithdrawGame, For Lost Ark Mobile only
0x7fffffffk_EStoveIAPMethodCode_MaxNot used

Example

c
IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);
uint32_t methodCode = Stove_IStoveResult_GetMethodCode(result);

if (methodCode == k_EStoveIAPMethodCode_StartPurchase)
{
    // This is the result of the Stove_StartPurchase() call.
}

Notes

  • Although the value range (2000–2006) appears to overlap numerically with the data type range (2000–2005) for EStoveIAPTypeKind, these are different enumerations, so be careful not to confuse them.
  • The module-specific EStoveIAPResultCode from the previous interface has been removed. To determine the cause of the failure, check the value of GetResultCode() in EStoveResultCode or EStoveCommonResultCode along with this method's code.

See Also


EStoveIAPTypeKind

Kind Enum · Module IAP · Version 3.5.0

Description

It is used to create the desired payment parameter object by passing it to Stove_CreateParam(), and it is also used to determine the actual type of the object at runtime via IStoveTypeBase::GetTypeKind().

The value range is 2000–2999. Within this range, the 2000s represent the result/data types passed by the SDK via callback, while the 2500s represent the parameter types created by the caller using Stove_CreateParam().

Declaration

c
typedef enum EStoveIAPTypeKind
{
    k_EStoveIAPTypeKind_Invalid = -1,
    k_EStoveIAPTypeKind_ShopCategory = 2000,
    // ... See the table of enumerated values below
    k_EStoveIAPTypeKind_Max = 0x7fffffff
} EStoveIAPTypeKind;

Enum Values

CodeNameDescription
-1k_EStoveIAPTypeKind_InvalidNot used
2000k_EStoveIAPTypeKind_ShopCategoryIStoveShopCategory, Store Category Entry
2001k_EStoveIAPTypeKind_ProductIStoveProduct, Product Item
2002k_EStoveIAPTypeKind_StartPurchaseOutcomeIStoveStartPurchaseOutcome, Purchase Start Result (Formerly: PurchaseResult)
2003k_EStoveIAPTypeKind_PurchasedProductIStovePurchasedProduct, Items with confirmed purchases
2004k_EStoveIAPTypeKind_ChargeInfoIStoveChargeInfo, Payment Currency (Charge) Information
2005k_EStoveIAPTypeKind_InventoryItemIStoveInventoryItem, Inventory (Purchase History) Item
,2006Not in use (reservation number)
,2007Not in use (reserved number)
2008k_EStoveIAPTypeKind_ConfirmPurchaseOutcomeIStoveConfirmPurchaseOutcome, Purchase Confirmation Results
2009k_EStoveIAPTypeKind_WithdrawGameOutcomeIStoveWithdrawGameOutcome, Game Withdrawal Results (Lost Ark Mobile Only)
2010k_EStoveIAPTypeKind_TermsAgreementOutcomeIStoveTermsAgreementOutcome, Results of Terms and Conditions Agreement Check
2011k_EStoveIAPTypeKind_ShopCategoryListIStoveShopCategoryList, Container for the list of store categories
2012k_EStoveIAPTypeKind_ProductListIStoveProductList, Product List Container
2013k_EStoveIAPTypeKind_InventoryListIStoveInventoryList, Inventory (Purchase History) List Container
2500k_EStoveIAPTypeKind_FetchProductsParamIStoveFetchProductsParam, Product search parameters
2501k_EStoveIAPTypeKind_OrderProductParamIStoveOrderProductParam, Order Item Parameters
2502k_EStoveIAPTypeKind_PurchaseParamIStovePurchaseParam, Purchase Action Parameters
2503k_EStoveIAPTypeKind_StartPurchaseParamIStoveStartPurchaseParam, Start Purchase Parameter
2504k_EStoveIAPTypeKind_FetchTermsAgreementParamIStoveFetchTermsAgreementParam, Terms of Service Agreement Lookup Parameter
,2505Not in use (reservation number)
2506k_EStoveIAPTypeKind_WithdrawGameParamIStoveWithdrawGameParam, Game Exit Parameter (Lost Ark Mobile Only)
2507k_EStoveIAPTypeKind_ConfirmPurchaseParamIStoveConfirmPurchaseParam, Purchase Confirmation Parameter
,2508Not in use (reserved number)
0x7fffffffk_EStoveIAPTypeKind_MaxNot used

IStoveWebViewLayoutParam is an abstract base type shared by IStovePurchaseParam, IStoveFetchTermsAgreementParam, and IStoveWithdrawGameParam; there are no values corresponding to this enumeration. It cannot be instantiated on its own as Stove_CreateParam().

Internal-use-only values have been excluded from the table.

Example

c
IStoveFetchProductsParam* param = (IStoveFetchProductsParam*)Stove_CreateParam(k_EStoveIAPTypeKind_FetchProductsParam);

Notes

  • Since the TypeKind enumerations for each module, such as Base and IAP, use non-overlapping integer ranges, you can generate parameters for all modules using just a single Stove_CreateParam().
  • The 2000 series (result/data type) is not created directly by the caller; it appears only as the GetTypeKind() value of the object passed via callback.
  • k_EStoveIAPTypeKind_StartPurchaseOutcome was renamed from its former name, PurchaseResult. Please keep this in mind when transferring past links.

See Also


EStoveLogMethodCode

Kind Enum · Module Log · Version 3.5.0

Description

It queries IStoveResult::GetMethodCode() and is used for logging and error routing.

Use module blocks 6000 through 6999 in sequence.

Declaration

c
typedef enum EStoveLogMethodCode
{
    k_EStoveLogMethodCode_Invalid = -1,

    k_EStoveLogMethodCode_SendLog = 6000,

    k_EStoveLogMethodCode_Max = 0x7fffffff
} EStoveLogMethodCode;

Enum Values

CodeNameDescription
-1k_EStoveLogMethodCode_InvalidNot used
6000k_EStoveLogMethodCode_SendLogThis is the result created by Stove_SendLog.
0x7fffffffk_EStoveLogMethodCode_MaxNot used

Example

c
IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

if (Stove_IStoveResult_GetMethodCode(result) == k_EStoveLogMethodCode_SendLog)
{
    // This is the result of the Stove_SendLog() call.
}

Notes

  • Only one logging function, Stove_SendLog(), is provided via the public API. The SDK handles initialization and termination.
  • EStoveLogResultCode has been removed from each module. The resulting code has been merged into EStoveResultCode and EStoveCommonResultCode.

See Also


EStoveLogTypeKind

Kind Enum · Module Log · Version 3.5.0

Description

Stove_CreateParam() is used when creating this specific parameter object, and IStoveTypeBase::GetTypeKind() is used to check its runtime type. The integer range is 6000–6999.

Declaration

c
typedef enum EStoveLogTypeKind
{
    k_EStoveLogTypeKind_Invalid = -1,

    k_EStoveLogTypeKind_SendLogParam = 6500,

    k_EStoveLogTypeKind_Max = 0x7fffffff
} EStoveLogTypeKind;

Enum Values

CodeNameDescription
-1k_EStoveLogTypeKind_InvalidNot used
6500k_EStoveLogTypeKind_SendLogParamThis is the parameter type created by the caller as Stove_CreateParam(). It corresponds to IStoveSendLogParam.
0x7fffffffk_EStoveLogTypeKind_MaxNot used

Example

c
IStoveSendLogParam* logParam = (IStoveSendLogParam*)Stove_CreateParam(k_EStoveLogTypeKind_SendLogParam);

Notes

  • The TypeKind range (6000–6999) for the log function does not overlap with the TypeKind ranges of other modules.
  • Currently, there is only one parameter type defined by the log function: k_EStoveLogTypeKind_SendLogParam.

See Also


EStoveOverlayMode

Kind Enum · Module Base · Version 3.5.0

Description

This value indicates the display status of regulatory and notification overlays, such as Vietnam's age rating notices and excessive use prevention notices.

Search for IStoveVietnamAgeRatingInfo::GetOverlayMode() and IStoveVietnamOverimmersionInfo::GetOverlayMode().

Declaration

c
typedef enum EStoveOverlayMode
{
    k_EStoveOverlayMode_Invalid = -1,

    k_EStoveOverlayMode_Show = 0,
    k_EStoveOverlayMode_Hide = 1,
    k_EStoveOverlayMode_Expanded = 2,

    k_EStoveOverlayMode_Max = 0x7fffffff
} EStoveOverlayMode;

Enum Values

CodeNameDescription
-1k_EStoveOverlayMode_InvalidNot used
0k_EStoveOverlayMode_ShowDisplays the overlay
1k_EStoveOverlayMode_HideHide the overlay
2k_EStoveOverlayMode_ExpandedDisplays the overlay in its expanded form
0x7fffffffk_EStoveOverlayMode_MaxNot used

Example

c
void __cdecl OnVietnamAgeRatingNotificationCallback(const IStoveCallbackResult* callbackResult, const IStoveVietnamAgeRatingInfo* ageRatingInfo)
{
    int32_t overlayMode = Stove_IStoveVietnamAgeRatingInfo_GetOverlayMode(ageRatingInfo);
    if (overlayMode == k_EStoveOverlayMode_Show)
    {
        // Please implement the logic to display the overlay.
    }
}

Notes

  • k_EStoveOverlayMode_Expanded is a value used exclusively in the Vietnamese Excessive Gaming Prevention Notice (IStoveVietnamOverimmersionInfo). Only "Show/Hide" is passed to the Age Rating Notice (IStoveVietnamAgeRatingInfo).
  • In the old interface, value names did not include an underscore (e.g., k_EStoveOverlayModeInvalid). In the current interface, an underscore is inserted between the type name and the value name, as in k_EStoveOverlayMode_Invalid.

Changelog

VersionChange
3.5.0First Published

See Also


EStoveOwnershipCode

Kind Enum · Module Ownership · Version 3.5.0

Description

The value returned by IStoveOwnership::GetOwnershipCode() indicates the current ownership status of a single item, such as a game, DLC, or demo.

Declaration

c
typedef enum EStoveOwnershipCode
{
    k_EStoveOwnershipCode_Invalid = -1,

    k_EStoveOwnershipCode_None = 0,
    k_EStoveOwnershipCode_Acquire = 1,
    k_EStoveOwnershipCode_Lose = 2,

    k_EStoveOwnershipCode_Max = 0x7fffffff
} EStoveOwnershipCode;

Enum Values

CodeNameDescription
-1k_EStoveOwnershipCode_InvalidNot used
0k_EStoveOwnershipCode_NoneThere is no recorded ownership status.
1k_EStoveOwnershipCode_AcquireThe user currently owns this item.
2k_EStoveOwnershipCode_LoseThe user has lost ownership (e.g., due to a refund).
0x7fffffffk_EStoveOwnershipCode_MaxNot used

Example

c
if (Stove_IStoveOwnership_GetOwnershipCode(ownership) == k_EStoveOwnershipCode_Acquire)
{
    // Please implement the logic for the items you own.
}

Notes

See Also


EStoveOwnershipGameCode

Kind Enum · Module Ownership · Version 3.5.0

Description

The value returned by IStoveOwnership::GetGameCode() indicates whether the ownership entry refers to the base game, a demo, or DLC.

Declaration

c
typedef enum EStoveOwnershipGameCode
{
    k_EStoveOwnershipGameCode_Invalid = -1,

    k_EStoveOwnershipGameCode_None = 0,
    // 1, 2: Not in use (discarded numbers)
    k_EStoveOwnershipGameCode_Basic = 3,
    k_EStoveOwnershipGameCode_Demo = 4,
    k_EStoveOwnershipGameCode_Dlc = 5,

    k_EStoveOwnershipGameCode_Max = 0x7fffffff
} EStoveOwnershipGameCode;

Enum Values

CodeNameDescription
-1k_EStoveOwnershipGameCode_InvalidNot used
0k_EStoveOwnershipGameCode_NoneNot a product item / Unclassified
,1, 2Not in use (discontinued number)
3k_EStoveOwnershipGameCode_BasicBase Game
4k_EStoveOwnershipGameCode_DemoDemo Build
5k_EStoveOwnershipGameCode_DlcDownloadable Content (DLC) associated with the base game
0x7fffffffk_EStoveOwnershipGameCode_MaxNot used

Example

c
if (Stove_IStoveOwnership_GetGameCode(ownership) == k_EStoveOwnershipGameCode_Dlc)
{
    // Please implement the logic for the DLC items.
}

Notes

  • Values 1 and 2 are reserved or deprecated numbers.
  • This is the value of the GameCode field in IStoveOwnership.

See Also


EStoveOwnershipMethodCode

Kind Enum · Module Ownership · Version 3.5.0

Description

It is queried as IStoveResult::GetMethodCode() and is used for logging and error routing.

Use module blocks 4000 through 4999 in sequence.

Declaration

c
typedef enum EStoveOwnershipMethodCode
{
    k_EStoveOwnershipMethodCode_Invalid = -1,

    k_EStoveOwnershipMethodCode_FetchOwnerships = 4000,

    k_EStoveOwnershipMethodCode_Max = 0x7fffffff
} EStoveOwnershipMethodCode;

Enum Values

CodeNameDescription
-1k_EStoveOwnershipMethodCode_InvalidNot used
4000k_EStoveOwnershipMethodCode_FetchOwnershipsThis is the result created by Stove_FetchOwnerships.
0x7fffffffk_EStoveOwnershipMethodCode_MaxNot used

Example

c
IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

if (Stove_IStoveResult_GetMethodCode(result) == k_EStoveOwnershipMethodCode_FetchOwnerships)
{
    // These are the results of the Stove_FetchOwnerships() call.
}

Notes

  • Only one ownership function, Stove_FetchOwnerships(), is provided via the public API. The SDK handles initialization and termination.

See Also


EStoveOwnershipTypeKind

Kind Enum · Module Ownership · Version 3.5.0

Description

This is used to identify the runtime type of result/data objects passed via asynchronous callbacks in the ownership function. It is queried as IStoveTypeBase::GetTypeKind(). The integer range is 4000 to 4999.

Declaration

c
typedef enum EStoveOwnershipTypeKind
{
    k_EStoveOwnershipTypeKind_Invalid = -1,

    k_EStoveOwnershipTypeKind_StoveOwnership = 4000,
    k_EStoveOwnershipTypeKind_OwnershipList = 4001,

    k_EStoveOwnershipTypeKind_Max = 0x7fffffff
} EStoveOwnershipTypeKind;

Enum Values

CodeNameDescription
-1k_EStoveOwnershipTypeKind_InvalidNot used
4000k_EStoveOwnershipTypeKind_StoveOwnershipThis is the type value for IStoveOwnership.
4001k_EStoveOwnershipTypeKind_OwnershipListThis is the type value for IStoveOwnershipList.
0x7fffffffk_EStoveOwnershipTypeKind_MaxNot used

Example

c
if (Stove_IStoveTypeBase_GetTypeKind((const IStoveTypeBase*)ownerships) == k_EStoveOwnershipTypeKind_OwnershipList)
{
    // Please implement the logic that uses `ownerships` as `IStoveOwnershipList`.
}

Notes

  • The ownership function does not define the type of the input parameter created by the caller. All values included in this enumeration are result/data types returned by the SDK via callbacks.
  • The range 4000–4999 is reserved exclusively for ownership functions and does not overlap with the TypeKind values of other modules.

See Also


EStoveProductTypeCode

Kind Enum · Module IAP · Version 3.5.0

Description

This is the product category code that returns ProductTypeCode out of IStoveProduct.

Declaration

c
typedef enum EStoveProductTypeCode
{
    k_EStoveProductTypeCode_None = 0,
    k_EStoveProductTypeCode_IndiePackageGameItem = 1,
    k_EStoveProductTypeCode_InGameItem = 2,
    k_EStoveProductTypeCode_PackageItem = 3,
    k_EStoveProductTypeCode_Max = 0x7fffffff
} EStoveProductTypeCode;

Enum Values

CodeNameDescription
0k_EStoveProductTypeCode_NoneUncategorized
1k_EStoveProductTypeCode_IndiePackageGameItemReserved (not currently used)
2k_EStoveProductTypeCode_InGameItemIn-game items
3k_EStoveProductTypeCode_PackageItemReserved (not currently used)
0x7fffffffk_EStoveProductTypeCode_MaxNot used

Example

c
int32_t typeCode = Stove_IStoveProduct_GetProductTypeCode(product);
if (typeCode == k_EStoveProductTypeCode_InGameItem)
{
    // Please implement logic specifically for in-game items.
}

Notes

  • This is used when interpreting the value IStoveProduct::ProductTypeCode.
  • Only 0 and 2 are currently in use. 1 and 3 are reserved and their meaning will change in the future, so do not rely on these values in your game code.

See Also


EStovePurchaseLimitTypeCode

Kind Enum · Module IAP · Version 3.5.0

Description

It returns IStoveProduct as PurchaseLimitTypeCode, indicating the scope (account-based or character-based) to which PurchaseLimitCount applies.

Declaration

c
typedef enum EStovePurchaseLimitTypeCode
{
    k_EStovePurchaseLimitTypeCode_None = 0,
    k_EStovePurchaseLimitTypeCode_Unlimited = 1,
    k_EStovePurchaseLimitTypeCode_Member = 2,
    k_EStovePurchaseLimitTypeCode_Character = 3,
    k_EStovePurchaseLimitTypeCode_Max = 0x7fffffff
} EStovePurchaseLimitTypeCode;

Enum Values

CodeNameDescription
0k_EStovePurchaseLimitTypeCode_NoneNo defined restriction policy
1k_EStovePurchaseLimitTypeCode_UnlimitedUnlimited purchases available
2k_EStovePurchaseLimitTypeCode_MemberAccount (Member) Level Limits
3k_EStovePurchaseLimitTypeCode_CharacterCharacter Limit
0x7fffffffk_EStovePurchaseLimitTypeCode_MaxNot used

Example

c
int32_t limitType = Stove_IStoveProduct_GetPurchaseLimitTypeCode(product);
int32_t limitCount = Stove_IStoveProduct_GetPurchaseLimitCount(product);

Notes

See Also


EStovePurchaseOperation

Kind Enum · Module IAP · Version 3.5.0

Description

Pass a value of Operation to IStovePurchaseParam to select which flow Stove_StartPurchase() will follow: manual URL, Stove WebView, or WebView + auto-complete.

Declaration

c
typedef enum EStovePurchaseOperation
{
    k_EStovePurchaseOperation_Default = 0,
    k_EStovePurchaseOperation_WithWebView = 1,
    k_EStovePurchaseOperation_WithWebViewAndConfirmResult = 2,
    k_EStovePurchaseOperation_Max = 0x7fffffff
} EStovePurchaseOperation;

Enum Values

CodeNameDescription
0k_EStovePurchaseOperation_DefaultDo not use the Stove WebView. The caller must open the Stove payment page directly using the one-time URL provided with the purchase results, and after completing the payment, call Stove_ConfirmPurchase() to confirm the purchase.
1k_EStovePurchaseOperation_WithWebViewOpens the Stove payment page within the Stove web view. Even after payment is complete, the caller must call Stove_ConfirmPurchase() for the purchase to be finalized.
2k_EStovePurchaseOperation_WithWebViewAndConfirmResultOpen the Stove payment page within the Stove web view, and if the payment is successful, the SDK automatically calls Stove_ConfirmPurchase() and returns the confirmed purchase result.
0x7fffffffk_EStovePurchaseOperation_MaxNot used

Example

c
IStovePurchaseParam* purchaseParam = (IStovePurchaseParam*)Stove_CreateParam(k_EStoveIAPTypeKind_PurchaseParam);
Stove_IStovePurchaseParam_SetOperation(purchaseParam, k_EStovePurchaseOperation_WithWebViewAndConfirmResult);

Notes

  • When entering values other than Default, you must also fill in the WebView* field (WebView position and size), which is inherited by IStovePurchaseParam.
  • Which field is populated in the results depends on this value. For more information, see the IStoveStartPurchaseOutcome documentation.

See Also


EStovePurchaseProgress

Kind Enum · Module IAP · Version 3.5.0

Description

It returns IStoveStartPurchaseOutcome as PurchaseProgress.

Declaration

c
typedef enum EStovePurchaseProgress
{
    k_EStovePurchaseProgress_None = 0,
    k_EStovePurchaseProgress_NeedPaymentWindow = 1,
    k_EStovePurchaseProgress_NotNeedPaymentWindow = 2,
    k_EStovePurchaseProgress_Max = 0x7fffffff
} EStovePurchaseProgress;

Enum Values

CodeNameDescription
0k_EStovePurchaseProgress_NoneNo progress
1k_EStovePurchaseProgress_NeedPaymentWindowThe caller must manually open the payment window using the one-time payment URL provided in the response.
2k_EStovePurchaseProgress_NotNeedPaymentWindowYou don't need to open the payment window, the transaction was completed via free payment, or the webview-based flow has already processed the payment.
0x7fffffffk_EStovePurchaseProgress_MaxNot used

Example

c
int32_t progress = Stove_IStoveStartPurchaseOutcome_GetPurchaseProgress(outcome);
if (progress == k_EStovePurchaseProgress_NeedPaymentWindow)
{
    const wchar_t* paymentUrl = Stove_IStoveStartPurchaseOutcome_GetTempPaymentUrl(outcome);
    // Please open the payment window using `paymentUrl`.
}

Notes

See Also


EStoveResultCode

Kind Result Code · Module Base · Version 3.5.0

Description

Among the values returned by IStoveResult::GetResultCode(), these are codes in the 300s range that belong to a global dictionary shared by multiple modules. The category is distinguished by the digit in the hundreds place (3xx: Base, 4xx: webview/popup UI, 5xx: IAP purchase/payload). Since separating codes by module is meaningless in a single-binary structure, codes that were used with the same meaning across multiple modules have been consolidated into a single number. You can determine which module generated a particular code by checking the GetMethodCode() value (code / 1000 = module block).

For the result code (0–299) used by all modules, please refer to EStoveCommonResultCode.

The module-specific result code enumerations (EStoveBaseResultCode, EStoveIAPResultCode, etc.) from the old interface have been removed. They have now been consolidated into this enumeration (300–) and EStoveCommonResultCode (0–299).

Declaration

c
typedef enum EStoveResultCode
{
    k_EStoveResultCode_LanguageNotSet = 300,
    // ... See the table of enumerated values below
    k_EStoveResultCode_InvalidOrderProductInformation = 503,

    k_EStoveResultCode_Max = 0x7fffffff
} EStoveResultCode;

Enum Values

3xx, Base Language / GDS / Launcher / Token / IPC

CodeNameDescriptionShow to UserIn-Game Message
300k_EStoveResultCode_LanguageNotSetNo display language has been set (Set the language to Stove_SetLanguage and try again)x
301k_EStoveResultCode_EmptyTranslatedStringThe translated string is empty.x
302k_EStoveResultCode_NotFoundRequiredInformationThe required information was not found.x
303k_EStoveResultCode_InvalidGdsInfoThe GDS (Country/Regulatory) information is invalid.x
304k_EStoveResultCode_NeedStoveLauncherThe Stove launcher is required but is not running.OThe game is closing because it is not running through the Stove PC client. Please relaunch the game from the client. If you do not have the client installed, please install it from the Stove website. [OK]
305k_EStoveResultCode_LauncherFailedCreateRequiredFailed to create the required launcher resourcesx
306k_EStoveResultCode_RenewTokenMaxRetryCountExceededThe token renewal has exceeded the maximum number of retry attempts.OThe network connection is unstable. Please check your network status and try again. [OK]
307k_EStoveResultCode_IpcConnectFailedFailed to establish an IPC connection with the launcherOThe game is closing because it is not running through the Stove PC client. Please launch the game again from the client. If you do not have the client installed, please install it from the Stove website. [OK]
308k_EStoveResultCode_IpcAesKeyNotReceivedThe AES key was not received over IPC.OThe game is closing because it is not running through the Stove PC client. Please launch the game again from the client. If you haven't installed the client, please install it from the Stove website.[OK]
309k_EStoveResultCode_IpcTimeoutThe IPC communication with the launcher timed out.OThe game is closing because it is not running through the Stove PC client. Please launch the game again from the client. If you do not have the client installed, please install it from the Stove website.[OK]

If you receive the code below, you must exit the game. The game cannot proceed normally.

  • 304 k_EStoveResultCode_NeedStoveLauncher, This is not running via the Stove PC client, so it needs to be restarted.
  • 307 k_EStoveResultCode_IpcConnectFailed, Failed to connect to the launcher; please try again.
  • 308 k_EStoveResultCode_IpcAesKeyNotReceived, Failed to establish communication with the launcher; a retry is required
  • 309 k_EStoveResultCode_IpcTimeout, Communication with the launcher timed out; a retry is required

4xx, (Reserved, Unused)

CodeNameDescriptionShow to UserIn-Game Message
,400 ~ 499The webview/popup UI code has been moved to EStoveCommonResultCode lines 60–68.,,

5xx, IAP Purchase / Payload

CodeNameDescriptionShow to UserIn-Game Message
,501, 502EStoveCommonResultCode Moved to 80 and 81,,
503k_EStoveResultCode_InvalidOrderProductInformationThe order/product information is invalid.OThe payment information is invalid, so we cannot process the payment. Please try again. [OK]
0x7fffffffk_EStoveResultCode_MaxNot used,,

Example

c
IStoveResult* result = Stove_SetGameProfile(profileParam);

if (Stove_IStoveResult_GetResultCode(result) == k_EStoveResultCode_LanguageNotSet)
{
    // Please implement logic that calls `Stove_SetLanguage()` first.
}

Notes

  • This replaces EStoveBaseResultCode (80s) from the old interface. With the single binary integration, the result codes for each module have been reorganized into this enumeration (300–) and EStoveCommonResultCode (0–299).
  • The values 401–499, 501, and 502 are merely reserved; they do not actually exist in this enumeration. The actual code can be found in EStoveCommonResultCode, specifically in the ranges 60–68 (WebView/popup UI) and 80–81 (IAP parameter validation).

Changelog

VersionChange
3.5.0First release (replaces the old EStoveBaseResultCode)

See Also


EStoveTermsOperation

Kind Enum · Module IAP · Version 3.5.0

Description

Pass a value of Operation to IStoveFetchTermsAgreementParam to choose how Stove_FetchTermsAgreement() displays the terms and conditions page.

Declaration

c
typedef enum EStoveTermsOperation
{
    k_EStoveTermsOperation_Default = 0,
    k_EStoveTermsOperation_WithWebView = 1,
    k_EStoveTermsOperation_Max = 0x7fffffff
} EStoveTermsOperation;

Enum Values

CodeNameDescription
0k_EStoveTermsOperation_DefaultThe Stove WebView is not used. The caller opens the Terms and Conditions page directly using the one-time URL received as a result.
1k_EStoveTermsOperation_WithWebViewOpens the Terms of Service agreement page within the Stove web view.
0x7fffffffk_EStoveTermsOperation_MaxNot used

Example

c
IStoveFetchTermsAgreementParam* param = (IStoveFetchTermsAgreementParam*)Stove_CreateParam(k_EStoveIAPTypeKind_FetchTermsAgreementParam);
Stove_IStoveFetchTermsAgreementParam_SetOperation(param, k_EStoveTermsOperation_WithWebView);

Notes

  • When using WithWebView, you must also fill in the WebView* fields (WebView position and size) that IStoveFetchTermsAgreementParam inherits.
  • If a user has already agreed to the latest terms of service, regardless of this value, IsAgreed in IStoveTermsAgreementOutcome will be returned as true, and Url will be returned as an empty string.

See Also


EStoveWebViewMode

Kind Enum · Module Base · Version 3.5.0

Description

This setting in the View SDK and IAP SDK determines whether a web view opens as an external pop-up (the system's default browser) or an internal pop-up (the SDK's built-in web view).

Declaration

c
typedef enum EStoveWebViewMode
{
    k_EStoveWebViewMode_Invalid = -1,

    k_EStoveWebViewMode_External = 0,
    k_EStoveWebViewMode_Internal = 1,

    k_EStoveWebViewMode_Max = 0x7fffffff
} EStoveWebViewMode;

Enum Values

CodeNameDescription
-1k_EStoveWebViewMode_InvalidNot used
0k_EStoveWebViewMode_ExternalOpens in the system's default browser
1k_EStoveWebViewMode_InternalOpens in the SDK's built-in web view
0x7fffffffk_EStoveWebViewMode_MaxNot used

Example

c
int32_t webViewMode = k_EStoveWebViewMode_Internal;

Notes

  • This value is used to specify how pop-ups are displayed in the View SDK and IAP SDK.
  • k_EStoveWebViewMode_Internal is a value that indicates the domain meaning "uses an internal WebView"; it is not an "Internal-only" value.
  • In the old interface, value names did not include underscores (e.g., k_EStoveWebViewModeInvalid). In the current interface, an underscore is inserted between the type name and the value name, as in k_EStoveWebViewMode_Invalid.

Changelog

VersionChange
3.5.0First Published

See Also

  • None

IStoveAccessToken

Kind Struct · Module Base · Version 3.5.0

Description

This is the token structure passed as a callback when the AccessToken is renewed upon calling Stove_AccessTokenRenewed().

The SDK is created and passed only as a callback argument; the caller does not release it.

Declaration

c
typedef struct IStoveAccessToken IStoveAccessToken;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
AccessTokenconst wchar_t*ReadStove_IStoveAccessToken_GetAccessToken()This is the Stove AccessToken value.
ExpireInint32_tReadStove_IStoveAccessToken_GetExpireIn()This is the remaining validity period (in seconds) of the Stove AccessToken.

Memory Management

ItemValue
Creating EntitySDK
Responsibility for TerminationSDK, Passed only as a callback argument and invalidated once the callback completes. The caller does not call Destroy().

Example

c
void __cdecl OnAccessTokenRenewedCallback(const IStoveCallbackResult* callbackResult, const IStoveAccessToken* token)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

    if (Stove_IStoveResult_GetResultCode(result) == k_EStoveCommonResultCode_Success)
    {
        const wchar_t* accessToken = Stove_IStoveAccessToken_GetAccessToken(token);
        int32_t expireIn = Stove_IStoveAccessToken_GetExpireIn(token);
        // Please implement the logic for a successful outcome.
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }

    // The token does not call Destroy().
}

Notes

  • This structure accepts data only through the callback registered as Stove_AccessTokenRenewed(). To immediately look up a currently valid token, use Stove_GetAccessToken.
  • The SDK automatically renews tokens internally; use this callback only if you want to perform the renewal yourself when it is due.

See Also


IStoveAchievement

Kind Struct · Module GameSupport · Version 3.5.0

Description

IStoveAchievement is a type that contains the result information returned when the Achievement Lookup API succeeds. Stove_FetchAchievement passes a single instance of this type as the OnGetAchievementCallback argument, while Stove_FetchAchievements passes a IStoveAchievementList object containing this type as the OnGetAchievementsCallback argument.

This type is created by the SDK and passed via a callback; it is not created directly by the caller.

Declaration

c
typedef struct IStoveAchievement IStoveAchievement;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
Conditionconst IStoveAchievementCondition*ReadStove_IStoveAchievement_GetCondition()These are the requirements for completing the achievement.
Valueint32_tReadStove_IStoveAchievement_GetValue()This is the current progress toward the achievement.
AchievementIdconst wchar_t*ReadStove_IStoveAchievement_GetAchievementId()This is the achievement ID.
Nameconst wchar_t*ReadStove_IStoveAchievement_GetName()This is the localized name of the achievement.
Descriptionconst wchar_t*ReadStove_IStoveAchievement_GetDescription()This is a localized description of the achievement.
DefaultImageconst wchar_t*ReadStove_IStoveAchievement_GetDefaultImage()This is the URL for the "Goal Not Met" status image.
AchievedImageconst wchar_t*ReadStove_IStoveAchievement_GetAchievedImage()This is the URL for the achievement status image.
Statusconst wchar_t*ReadStove_IStoveAchievement_GetStatus()This shows the current status of the achievement. Example: "ONGOING" (In Progress), "ACHIEVED" (Completed)

Memory Management

ItemValue
Creating EntitySDK
Responsibility for DismantlingSDK (Do not disable. It will be invalidated once the callback (Stove_FetchAchievement / Stove_FetchAchievements) is complete.)

Example

c
void OnGetAchievementFinished(const IStoveCallbackResult* callbackResult, const IStoveAchievement* achievement)
{
    if (Stove_IStoveResult_GetResultCode(Stove_IStoveCallbackResult_GetResult(callbackResult)) == 0 && achievement != NULL)
    {
        const wchar_t* status = Stove_IStoveAchievement_GetStatus(achievement);
        int32_t value = Stove_IStoveAchievement_GetValue(achievement);

        // Please implement the logic for a successful outcome.
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

Notes

  • It is not created directly by the caller; it can only be obtained through the Stove_FetchAchievement or Stove_FetchAchievements callbacks.
  • The IStoveAchievementCondition obtained via Condition is also invalidated once the callback associated with this object completes.
  • The ValueOperation/Type values for Status and Condition are passed as strings, not as fixed enumerations.

See Also


IStoveAchievementCondition

Kind Struct · Module GameSupport · Version 3.5.0

Description

IStoveAchievementCondition is a type that contains the conditions required to complete an achievement. It is passed as part of IStoveAchievement.

This type is created by the SDK and passed via a callback; the caller does not create it directly.

Declaration

c
typedef struct IStoveAchievementCondition IStoveAchievementCondition;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
ValueOperationconst wchar_t*ReadStove_IStoveAchievementCondition_GetValueOperation()These are value handling methods. Examples: "DELTA_SUM" (cumulative sum of values), "REPLACE" (replace value), "MAX" (replace with the larger value), "MIN" (replace with the smaller value)
Typeconst wchar_t*ReadStove_IStoveAchievementCondition_GetType()This is how target values and user-entered values are compared. Example: "GTE" (or higher), "LTE" (or lower)
GoalValueint32_tReadStove_IStoveAchievementCondition_GetGoalValue()This is the target value for the achievement.

Memory Management

ItemValue
Creating EntitySDK
Responsibility for DismantlingSDK (Do not release. If the IStoveAchievement callback parameter containing this object is invalidated, it will be invalidated as well)

Example

c
void PrintAchievementCondition(const IStoveAchievement* achievement)
{
    const IStoveAchievementCondition* condition = Stove_IStoveAchievement_GetCondition(achievement);
    const wchar_t* type = Stove_IStoveAchievementCondition_GetType(condition);
    int32_t goalValue = Stove_IStoveAchievementCondition_GetGoalValue(condition);

    // Please implement logic that uses the condition values.
}

Notes

  • It is not created directly by the caller and can only be obtained through IStoveAchievement.
  • The values ValueOperation and Type are passed as strings, not as fixed enumerations.

See Also


IStoveAchievementList

Kind Struct · Module GameSupport · Version 3.5.0

Description

IStoveAchievementList is a container type that wraps the list of achievements passed as OnGetAchievementsCallback. It is passed as the onFinished callback argument of Stove_FetchAchievements.

This type is created by the SDK and passed via a callback; it is not created directly by the caller.

Declaration

c
typedef struct IStoveAchievementList IStoveAchievementList;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
Countuint32_tReadStove_IStoveAchievementList_GetCount()This is the number of achievements included in this response.
,const IStoveAchievement*ReadStove_IStoveAchievementList_GetAt(index)Retrieves achievement entries starting from index 0. If the index is index >= Count, it returns NULL.
TotalCountuint32_tReadStove_IStoveAchievementList_GetTotalCount()This is the total number of achievements. In v3.5.0, the entire list is returned at once, so the value is Count.

Memory Management

ItemValue
Creating EntitySDK
Responsibility for DismantlingSDK (Do not deactivate. It will be invalidated once the Stove_FetchAchievements callback completes)

Example

c
void OnGetAchievementsFinished(const IStoveCallbackResult* callbackResult, const IStoveAchievementList* list)
{
    if (Stove_IStoveResult_GetResultCode(Stove_IStoveCallbackResult_GetResult(callbackResult)) == 0 && list != NULL)
    {
        uint32_t count = Stove_IStoveAchievementList_GetCount(list);
        for (uint32_t i = 0; i < count; i++)
        {
            const IStoveAchievement* achievement = Stove_IStoveAchievementList_GetAt(list, i);
            const wchar_t* achievementId = Stove_IStoveAchievement_GetAchievementId(achievement);

            // Please implement the logic for a successful outcome.
        }
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

Notes

  • It is not created directly by the caller; it can only be obtained through the Stove_FetchAchievements callback.
  • The IStoveAchievement items included in this list will also be invalidated once the callback is complete.
  • In v3.5.0, the entire list of achievements is returned at once. Pagination will be available starting with v3.5.1.

See Also


IStoveCallbackResult

Kind Struct · Module Base · Version 3.5.0

Description

This is the result passed to the asynchronous callback. It wraps IStoveResult and includes additional error information along with the userData pointer provided at the time of the call.

It is passed as the first callback argument to callback-based asynchronous APIs such as Stove_RestartAppIfNecessary() and Stove_AccessTokenRenewed(). The lifetime of this object and its internal pointers is limited to the duration of the callback call. It is created by the SDK and passed only as a callback argument; the caller does not free it.

Once the callback finishes, both this object and IStoveResult*, obtained from GetResult(), will be invalidated. Destroy() will not be called.

Declaration

c
typedef struct IStoveCallbackResult IStoveCallbackResult;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
ResultIStoveResult*ReadStove_IStoveCallbackResult_GetResult()This is an internal result object. It is valid only during the callback call.
ErrorMessageconst wchar_t*ReadStove_IStoveCallbackResult_GetErrorMessage()This is a detailed message explaining why the error occurred.
ExternalErrorint32_tReadStove_IStoveCallbackResult_GetExternalError()This is an external error value (HTTP error code or API response code).
UserDatavoid*ReadStove_IStoveCallbackResult_GetUserData()This is the userData pointer passed by the caller when making an asynchronous API call.

Memory Management

ItemValue
CreatorSDK
Responsibility for DismantlingSDK, Passed only as a callback argument and invalidated once the callback completes. The caller does not call Destroy().

Example

c
void __cdecl OnAccessTokenRenewedCallback(const IStoveCallbackResult* callbackResult, const IStoveAccessToken* token)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

    if (Stove_IStoveResult_GetResultCode(result) == k_EStoveCommonResultCode_Success)
    {
        // Please implement the logic for a successful outcome.
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }

    // `callbackResult`, `result`, and `token` do not call `Destroy()`.
}

Notes

  • Asynchronous callbacks in the SDK (OnRestartAppIfNecessaryCallback, OnAccessTokenRenewedCallback, OnOverImmersionNotificationCallback, OnShutdownNotificationCallback, OnVietnamAgeRatingNotificationCallback, OnVietnamOverimmersionNotificationCallback, OnOpenExternalUrlCallback) in the SDK.
  • The callback runs in the thread that called Stove_RunCallback() (or Stove_RunCallbackWithTimeout()).

See Also


IStoveChargeInfo

Kind Struct · Module IAP · Version 3.5.0

Description

This represents a single payment method (such as coupons, Stove Cash, points, or PG) used for a single purchase. It is passed as an array containing both IStoveStartPurchaseOutcome and IStoveConfirmPurchaseOutcome.

This is a data type that the SDK fills in and passes via a callback. The caller does not create it directly.

The array and each item passed to the callback are owned by the SDK and are no longer valid once the callback call ends. Do not call Destroy(); instead, copy any values you need to preserve within the callback.

Declaration

c
typedef struct IStoveChargeInfo IStoveChargeInfo;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
ChargeDeductValdoubleReadStove_IStoveChargeInfo_GetChargeDeductVal()The amount actually deducted at the time of payment (based on the payment unit)
ChargeDisplayDeductValdoubleReadStove_IStoveChargeInfo_GetChargeDisplayDeductVal()Cash equivalent value of the deduction amount
ChargeTypeint32_tReadStove_IStoveChargeInfo_GetChargeType()Payment method code (charge_type, Int32). 2: Coupon, 98: Stove Cash, 99: Points, Others: PG (payment gateway) payment methods (may be added by the server). Only 2/98/99 are fixed values; the rest are determined by the server.
ChargeTypeNameconst wchar_t*ReadStove_IStoveChargeInfo_GetChargeTypeName()Localized payment method names

Memory Management

ItemValue
Creating EntitySDK
Responsibility for DismantlingSDK (Do not unlock, becomes invalid once the callback is complete)

Example

c
void __cdecl OnConfirmPurchaseCallback(const IStoveCallbackResult* callbackResult, const IStoveConfirmPurchaseOutcome* outcome)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

    // In the Steam launcher flow IsConfirmed is always false; follow the common judgment in the Stove_ConfirmPurchase example.
    if (Stove_IStoveResult_GetResultCode(result) == 0 && Stove_IStoveConfirmPurchaseOutcome_IsConfirmed(outcome))
    {
        uint32_t count = Stove_IStoveConfirmPurchaseOutcome_GetChargeInfoCount(outcome);

        for (uint32_t i = 0; i < count; ++i)
        {
            const IStoveChargeInfo* chargeInfo = Stove_IStoveConfirmPurchaseOutcome_GetChargeInfoAt(outcome, i);

            double deductVal = Stove_IStoveChargeInfo_GetChargeDeductVal(chargeInfo);
            const wchar_t* typeName = Stove_IStoveChargeInfo_GetChargeTypeName(chargeInfo);

            // Please copy and save only the values you need.
        }
        // The `outcome` and its items will be invalidated once this callback completes. Do not call `Destroy()`.
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

Notes

See Also


IStoveConfirmPurchaseOutcome

Kind Struct · Module IAP · Version 3.5.0

Description

This represents the result of the Stove_ConfirmPurchase call. It is passed to the OnConfirmPurchaseCallback callback. Previously, the confirmation flag and the array of product/payment information were passed separately as callback arguments, but now they are combined into a single structure and passed together.

This is a data type that the SDK populates and passes via a callback. The caller does not create it directly.

All values obtained via PurchasedProductAt() / ChargeInfoAt() are owned by the SDK and are no longer valid once the callback completes. Do not call Destroy(); instead, copy any values you need to retain within the callback.

Declaration

c
typedef struct IStoveConfirmPurchaseOutcome IStoveConfirmPurchaseOutcome;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
IsConfirmedboolReadStove_IStoveConfirmPurchaseOutcome_IsConfirmed()Whether the purchase was successfully completed
PurchasedProductCountuint32_tReadStove_IStoveConfirmPurchaseOutcome_GetPurchasedProductCount()Number of items with confirmed purchases
PurchasedProductAt(index)const IStovePurchasedProduct*ReadStove_IStoveConfirmPurchaseOutcome_GetPurchasedProductAt()The purchased item at position index (starting from 0). If the position is index >= PurchasedProductCount, it returns nullptr.
ChargeInfoCountuint32_tReadStove_IStoveConfirmPurchaseOutcome_GetChargeInfoCount()Number of "charge-info" entries
ChargeInfoAt(index)const IStoveChargeInfo*ReadStove_IStoveConfirmPurchaseOutcome_GetChargeInfoAt()The "charge-info" entry at position index (starting from 0). If it is index >= ChargeInfoCount, it returns nullptr.

Memory Management

ItemValue
Creating EntitySDK
Responsibility for DismantlingSDK (Do Not Unlock, Invalid once the callback completes)

Example

c
void __cdecl OnConfirmPurchaseCallback(const IStoveCallbackResult* callbackResult, const IStoveConfirmPurchaseOutcome* outcome)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

    // In the Steam launcher flow IsConfirmed is always false; follow the common judgment in the Stove_ConfirmPurchase example.
    if (Stove_IStoveResult_GetResultCode(result) == 0 && Stove_IStoveConfirmPurchaseOutcome_IsConfirmed(outcome))
    {
        uint32_t productCount = Stove_IStoveConfirmPurchaseOutcome_GetPurchasedProductCount(outcome);
        for (uint32_t i = 0; i < productCount; ++i)
        {
            const IStovePurchasedProduct* product = Stove_IStoveConfirmPurchaseOutcome_GetPurchasedProductAt(outcome, i);
            // Please implement the item distribution logic. Please prevent duplicate distributions by checking the TxnDetailNo.
        }
        // The `outcome` and its items will be invalidated once this callback finishes. Do not call `Destroy()`.
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

Notes

  • It is passed only as the output of Stove_ConfirmPurchase.
  • If IsConfirmed is false, the product/payment information array may be empty.

See Also


IStoveConfirmPurchaseParam

Kind Struct · Module IAP · Version 3.5.0

Description

This is the input parameter passed when calling Stove_ConfirmPurchase. It is used to confirm a purchase using the transaction master number received from IStoveStartPurchaseOutcome.

Create it as Stove_CreateParam(k_EStoveIAPTypeKind_ConfirmPurchaseParam), fill in the value using the setter, and then release it as Destroy() once the call is complete.

Declaration

c
typedef struct IStoveConfirmPurchaseParam IStoveConfirmPurchaseParam;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessRequiredAccessorDescription
TxnMasterNoint64_tReading and WritingYesStove_IStoveConfirmPurchaseParam_GetTxnMasterNo() / Stove_IStoveConfirmPurchaseParam_SetTxnMasterNo()Transaction master number received from IStoveStartPurchaseOutcome

Memory Management

ItemValue
Creating EntityCaller (Stove_CreateParam(k_EStoveIAPTypeKind_ConfirmPurchaseParam))
Responsibility for DismantlingCaller (Destroy() required)

Example

c
IStoveConfirmPurchaseParam* confirmParam = (IStoveConfirmPurchaseParam*)Stove_CreateParam(k_EStoveIAPTypeKind_ConfirmPurchaseParam);

Stove_IStoveConfirmPurchaseParam_SetTxnMasterNo(confirmParam, txnMasterNo);

Stove_ConfirmPurchase(confirmParam, OnConfirmPurchaseCallback, NULL);

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)confirmParam);

Notes

  • For TxnMasterNo, please use the TxnMasterNo value from IStoveStartPurchaseOutcome, which is the result of Stove_StartPurchase, as is.
  • Purchases that begin with Operation == Default must be confirmed using this API after completing payment on the payment page.

See Also


IStoveFetchAchievementParam

Kind Struct · Module GameSupport · Version 3.5.0

Description

IStoveFetchAchievementParam is a parameter type that specifies a single achievement to retrieve. It takes Stove_FetchAchievement as input.

The caller creates it as Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchAchievementParam), fills in the value, and then releases it as Destroy() once the API call is complete.

Declaration

c
typedef struct IStoveFetchAchievementParam IStoveFetchAchievementParam;
// To access members, use the access functions listed in the member table below.

Members

NameTypeRequiredAccessAccessorDescription
AchievementIdconst wchar_t*YesReading and WritingStove_IStoveFetchAchievementParam_GetAchievementId() / SetAchievementId()This is the achievement ID to look up.

Memory Management

ItemValue
Creating EntityCaller (Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchAchievementParam))
Responsibility for DismantlingCaller (Destroy() required)

Example

c
IStoveFetchAchievementParam* param =
    (IStoveFetchAchievementParam*)Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchAchievementParam);
Stove_IStoveFetchAchievementParam_SetAchievementId(param, L"ACHV_FIRST_KILL");

Stove_FetchAchievement(param, OnGetAchievementFinished, NULL);

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param);

Notes

See Also


IStoveFetchAchievementsParam

Kind Struct · Module GameSupport · Version 3.5.0

Description

IStoveFetchAchievementsParam is the parameter type used when retrieving the current user's list of achievements. It takes Stove_FetchAchievements as input.

The caller creates it as Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchAchievementsParam), and releases it as Destroy() once the API call is complete.

Please do not use paginated queries in v3.5.0. If you call the API without filling in AchievementId and PageSize, the entire list of achievements will be retrieved at once, as before. Paginated queries will be available starting with v3.5.1 once the server API specifications have been finalized.

Declaration

c
typedef struct IStoveFetchAchievementsParam IStoveFetchAchievementsParam;
// To access members, use the access functions listed in the member table below.

Members

NameTypeRequiredAccessAccessorDescription
AchievementIdconst wchar_t*NoReading and WritingStove_IStoveFetchAchievementsParam_GetAchievementId() / SetAchievementId()This is the cursor used for page-based queries. Use this starting with v3.5.1, do not enter a value in v3.5.0.
PageSizeuint32_tNoReading and WritingStove_IStoveFetchAchievementsParam_GetPageSize() / SetPageSize()The number of achievements to display per page. Available starting with v3.5.1, do not enter a value in v3.5.0. If no value is specified, the entire list of achievements will be displayed.

Memory Management

ItemValue
Creating EntityCaller (Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchAchievementsParam))
Responsibility for DismantlingCaller (Destroy() required)

Example

c
// View Full List of Achievements (v3.5.0 uses only this format)
IStoveFetchAchievementsParam* param =
    (IStoveFetchAchievementsParam*)Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchAchievementsParam);

Stove_FetchAchievements(param, OnGetAchievementsFinished, NULL);

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param);

Notes

  • If you do not specify a value, the entire list of achievements will be retrieved at once. In v3.5.0, please call this method only in this format.
  • Page-based queries using two values will be available starting with version 3.5.1. Instructions on how to use this feature will be added to this document at that time.

See Also


IStoveFetchProductsParam

Kind Struct · Module IAP · Version 3.5.0

Description

These are the input parameters passed when calling Stove_FetchProducts. They specify the category and page range to query.

Create it as Stove_CreateParam(k_EStoveIAPTypeKind_FetchProductsParam), set its value using the setter, and then release it as Destroy() once the call is complete.

Declaration

c
typedef struct IStoveFetchProductsParam IStoveFetchProductsParam;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessRequiredAccessorDescription
CategoryIdconst wchar_t*Reading and WritingNoStove_IStoveFetchProductsParam_GetCategoryId() / Stove_IStoveFetchProductsParam_SetCategoryId()Category ID filter. Leave this blank to view products from all categories.
PageIndexuint32_tReading and WritingYesStove_IStoveFetchProductsParam_GetPageIndex() / Stove_IStoveFetchProductsParam_SetPageIndex()Page number (starting from 1). This matches the value page_no sent to the server.
PageSizeuint32_tReading and WritingYesStove_IStoveFetchProductsParam_GetPageSize() / Stove_IStoveFetchProductsParam_SetPageSize()Number of products per page

Memory Management

ItemValue
Creating EntityCaller (Stove_CreateParam(k_EStoveIAPTypeKind_FetchProductsParam))
Responsibility for DismantlingCaller (Destroy() required)

Example

c
IStoveFetchProductsParam* param = (IStoveFetchProductsParam*)Stove_CreateParam(k_EStoveIAPTypeKind_FetchProductsParam);

Stove_IStoveFetchProductsParam_SetCategoryId(param, L"");
Stove_IStoveFetchProductsParam_SetPageIndex(param, 1);
Stove_IStoveFetchProductsParam_SetPageSize(param, 20);

Stove_FetchProducts(param, OnFetchProductsCallback, NULL);

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param);

Notes

  • If you leave CategoryId blank, products from all categories will be displayed. To view products from a specific category, please specify the value of CategoryId in IStoveShopCategory.

See Also


IStoveFetchRankingParam

Kind Struct · Module GameSupport · Version 3.5.0

Description

IStoveFetchRankingParam is a parameter type that specifies the leaderboard and page information to retrieve. It accepts an input of Stove_FetchRanking.

The caller creates it as Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchRankingParam), fills in the value, and then releases it as Destroy() once the API call is complete.

Declaration

c
typedef struct IStoveFetchRankingParam IStoveFetchRankingParam;
// To access members, use the access functions listed in the member table below.

Members

NameTypeRequiredAccessAccessorDescription
LeaderboardIdconst wchar_t*YesReading and WritingStove_IStoveFetchRankingParam_GetLeaderboardId() / SetLeaderboardId()This is a leaderboard identifier generated by the studio.
PageIndexuint32_tYesReading and WritingStove_IStoveFetchRankingParam_GetPageIndex() / SetPageIndex()This is the page number to view (1 <= pageIndex).
PageSizeuint32_tYesReading and WritingStove_IStoveFetchRankingParam_GetPageSize() / SetPageSize()The number of rankings to display per page (1 <= pageSize <= 50).
IncludeMyRankboolYesReading and WritingStove_IStoveFetchRankingParam_GetIncludeMyRank() / SetIncludeMyRank()This determines whether the search results should include the logged-in user's own ranking.

Memory Management

ItemValue
Creating EntityCaller (Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchRankingParam))
Responsibility for DismantlingCaller (Destroy() required)

Example

c
IStoveFetchRankingParam* param =
    (IStoveFetchRankingParam*)Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchRankingParam);
Stove_IStoveFetchRankingParam_SetLeaderboardId(param, L"WEEKLY_SCORE");
Stove_IStoveFetchRankingParam_SetPageIndex(param, 1);
Stove_IStoveFetchRankingParam_SetPageSize(param, 20);
Stove_IStoveFetchRankingParam_SetIncludeMyRank(param, true);

Stove_FetchRanking(param, OnGetRankingFinished, NULL);

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param);

Notes

See Also


IStoveFetchStatParam

Kind Struct · Module GameSupport · Version 3.5.0

Description

IStoveFetchStatParam is a parameter type used to specify the statistics (Stat) to retrieve. It uses Stove_FetchStat as input.

The caller creates it as Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchStatParam), fills in the value, and then releases it as Destroy() once the API call is complete.

Declaration

c
typedef struct IStoveFetchStatParam IStoveFetchStatParam;
// To access members, use the access functions listed in the member table below.

Members

NameTypeRequiredAccessAccessorDescription
StatsIdconst wchar_t*YesReading and WritingStove_IStoveFetchStatParam_GetStatsId() / SetStatsId()This is the ID of the statistic to retrieve. Format: [A-Z0-9\-_]*$ (uppercase letters, numbers, underscores, hyphens)

Memory Management

ItemValue
Creating EntityCaller (Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchStatParam))
Responsibility for RevocationCaller (Destroy() required)

Example

c
IStoveFetchStatParam* param =
    (IStoveFetchStatParam*)Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchStatParam);
Stove_IStoveFetchStatParam_SetStatsId(param, L"KILL_COUNT");

Stove_FetchStat(param, OnGetStatFinished, NULL);

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param);

Notes

  • If you do not set StatsId, you will not be able to view the correct statistics.

See Also


IStoveFetchTermsAgreementParam

Kind Struct · Module IAP · Version 3.5.0

Description

These are the input parameters passed when calling Stove_FetchTermsAgreement. It inherits from IStoveWebViewLayoutParam, and the WebView* fields apply only when Operation is not Default.

Create it as Stove_CreateParam(k_EStoveIAPTypeKind_FetchTermsAgreementParam), populate it with a value using the setter, and then release it as Destroy() once the call is complete.

Declaration

c
typedef struct IStoveFetchTermsAgreementParam IStoveFetchTermsAgreementParam;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessRequiredAccessorDescription
OperationEStoveTermsOperationReading and WritingYesStove_IStoveFetchTermsAgreementParam_GetOperation() / Stove_IStoveFetchTermsAgreementParam_SetOperation()Mode Selector
WebViewModeEStoveWebViewModeReading and WritingNoStove_IStoveFetchTermsAgreementParam_GetWebViewMode() / Stove_IStoveFetchTermsAgreementParam_SetWebViewMode()WebView Display Mode (External Browser / SDK-Embedded WebView). Applies only when Operation != Default. This is an inherited member of IStoveWebViewLayoutParam.
WebViewPosXint32_tReading and WritingNoStove_IStoveFetchTermsAgreementParam_GetWebViewPosX() / Stove_IStoveFetchTermsAgreementParam_SetWebViewPosX()WebView x-coordinate (pixels). Applies only when Operation != Default. IStoveWebViewLayoutParam is an inherited member.
WebViewPosYint32_tReading and WritingNoStove_IStoveFetchTermsAgreementParam_GetWebViewPosY() / Stove_IStoveFetchTermsAgreementParam_SetWebViewPosY()WebView y-coordinate (pixels). Applies only when Operation != Default is true. IStoveWebViewLayoutParam is an inherited member.
WebViewWidthint32_tReading and WritingNoStove_IStoveFetchTermsAgreementParam_GetWebViewWidth() / Stove_IStoveFetchTermsAgreementParam_SetWebViewWidth()WebView width (pixels). Applies only when Operation != Default is true. It is an inherited member of IStoveWebViewLayoutParam.
WebViewHeightint32_tReading and WritingNoStove_IStoveFetchTermsAgreementParam_GetWebViewHeight() / Stove_IStoveFetchTermsAgreementParam_SetWebViewHeight()WebView height (pixels). Applies only when Operation != Default. This is an inherited member of IStoveWebViewLayoutParam.

Memory Management

ItemValue
Creating EntityCaller (Stove_CreateParam(k_EStoveIAPTypeKind_FetchTermsAgreementParam))
Responsibility for DismantlingCaller (Destroy() required)

Example

c
IStoveFetchTermsAgreementParam* param = (IStoveFetchTermsAgreementParam*)Stove_CreateParam(k_EStoveIAPTypeKind_FetchTermsAgreementParam);

Stove_IStoveFetchTermsAgreementParam_SetOperation(param, k_EStoveTermsOperation_WithWebView);
Stove_IStoveFetchTermsAgreementParam_SetWebViewMode(param, k_EStoveWebViewMode_Internal);
Stove_IStoveFetchTermsAgreementParam_SetWebViewWidth(param, 480);
Stove_IStoveFetchTermsAgreementParam_SetWebViewHeight(param, 640);

Stove_FetchTermsAgreement(param, OnFetchTermsAgreementCallback, NULL, NULL, NULL);

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param);

Notes

  • Operation If this is Default, the WebView* field is ignored.

See Also


IStoveGds

Kind Struct · Module Base · Version 3.5.0

Description

This is the structure containing the country, regulatory, time zone, and language information passed when calling Stove_GetGds().

The country code based on the logged-in user's IP address is provided by default; if the country cannot be determined from the IP address, it is replaced with the default country code (separated by IsDefault). The SDK creates and returns it via the Stove_GetGds() out parameter, and the caller releases it via Destroy() after use.

Declaration

c
typedef struct IStoveGds IStoveGds;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
IsDefaultboolReadStove_IStoveGds_IsDefault()This indicates whether the default country code was used because the user's IP address could not be used to determine the country code. If the country code was determined based on the IP address, this value is false.
Nationconst wchar_t*ReadStove_IStoveGds_GetNation()This is the country code (ISO 3166-1 ALPHA-2) determined based on the logged-in user's IP address.
Regulationconst wchar_t*ReadStove_IStoveGds_GetRegulation()This is the name of the regulation that applies based on the country code (e.g., GDPR).
Timezoneconst wchar_t*ReadStove_IStoveGds_GetTimezone()This is the logged-in user's time zone (IANA Time Zone Database ID, e.g., L"Asia/Seoul").
UtcOffsetint32_tReadStove_IStoveGds_GetUtcOffset()This is the UTC offset (in minutes) for the user's time zone.
Langconst wchar_t*ReadStove_IStoveGds_GetLang()This is the language of the logged-in user (ISO 639-1 ALPHA-2). Exceptions: Chinese uses "zh" or "zh-tw," and Indonesian uses "in."

Memory Management

ItemValue
CreatorSDK (passed as an out parameter to Stove_GetGds())
Responsibility for DismantlingCaller (Destroy() required)

Example

c
IStoveGds* gds = NULL;
IStoveResult* result = Stove_GetGds(&gds);

if (Stove_IStoveResult_GetResultCode(result) == k_EStoveCommonResultCode_Success)
{
    const wchar_t* nation = Stove_IStoveGds_GetNation(gds);
    const wchar_t* timezone = Stove_IStoveGds_GetTimezone(gds);
    // Please implement the logic for a successful outcome.

    Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)gds);
}
else
{
    // Please implement the logic for when an error occurs.
}

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result);

Notes

  • You must call this after initialization is complete with Stove_Initialize() to receive a valid value.

See Also


IStoveInitializeParam

Kind Struct · Module Base · Version 3.5.0

Description

Contains the parameters required for the Stove_Initialize() call. It is used solely to set the IAP store key and the game's main window handle.

Create it using Stove_CreateParam(k_EStoveBaseTypeKind_InitializeParam), configure the necessary fields, and then release it using Destroy() when the call is complete. If ShopKey is not left empty, Stove_Initialize() will initialize the IAP module as well; if MainWndHandle is set, it will initialize the View module (and the IAP module, if ShopKey is present). If you pass initParam itself as null, only the SDK is initialized.

MainWndHandle is a valid value only after the game's main window has actually been created.

Declaration

c
typedef struct IStoveInitializeParam IStoveInitializeParam;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
ShopKeyconst wchar_t*Reading and WritingStove_IStoveInitializeParam_GetShopKey() / SetShopKey()This is the IAP store key. If the value is not empty, Stove_Initialize() initializes the IAP module. If left empty, IAP initialization is skipped.
MainWndHandleconst void*Reading and WritingStove_IStoveInitializeParam_GetMainWndHandle() / SetMainWndHandle()This is the handle of the game's main window (HWND, passed as const void*). It is valid only after the window has been created; if a value is provided, it initializes the View module (and, if ShopKey is present, the IAP module). If left blank, the View/IAP configuration is skipped.

Memory Management

ItemValue
Creating EntityCaller (Stove_CreateParam(k_EStoveBaseTypeKind_InitializeParam))
Responsibility for DismantlingCaller (Destroy() required), Release this after the API call is complete.

Example

c
IStoveInitializeParam* initParam =
    (IStoveInitializeParam*)Stove_CreateParam(k_EStoveBaseTypeKind_InitializeParam);

Stove_IStoveInitializeParam_SetShopKey(initParam, L"YOUR_SHOP_KEY");
Stove_IStoveInitializeParam_SetMainWndHandle(initParam, hWnd);

IStoveResult* result = Stove_Initialize(initParam);

if (Stove_IStoveResult_GetResultCode(result) == k_EStoveCommonResultCode_Success)
{
    // Please implement the logic for a successful outcome.
}
else
{
    // Please implement the logic for when a failure occurs.
}

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

Notes

  • Environment/GameId/AppKey is not present in this type. In the current interface, it has been moved to IStoveRestartAppIfNecessaryParam, and the SDK reuses the cached value from Stove_RestartAppIfNecessary() when calling Stove_Initialize().
  • ShopKey and MainWndHandle are fields added to initialize the IAP and View modules together following the single binary integration.
  • If Stove_Initialize() succeeds only partially (e.g., SDK/View succeeds, but IAP fails), the SDK may remain in a partially initialized state. To recover, you must call Stove_Uninitialize() and then call Stove_Initialize() again.

See Also


IStoveInventoryItem

Kind Struct · Module IAP · Version 3.5.0

Description

Represents a single user purchase history entry. The result of the Stove_FetchInventory call is stored in IStoveInventoryList and passed to the OnFetchInventoryCallback callback.

This is a data type that the SDK populates and passes via a callback. The caller does not create it directly.

The list and each item passed to the callback are owned by the SDK and are no longer valid once the callback completes. Do not call Destroy(); instead, copy any values you need to preserve within the callback.

Declaration

c
typedef struct IStoveInventoryItem IStoveInventoryItem;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
TxnMasterNoint64_tReadStove_IStoveInventoryItem_GetTxnMasterNo()Transaction Master Number
TxnDetailNoint64_tReadStove_IStoveInventoryItem_GetTxnDetailNo()Transaction Detail Number (TID by Product)
ProductIdint64_tReadStove_IStoveInventoryItem_GetProductId()Platform-Specific Product Identifier
InserviceItemIdconst wchar_t*ReadStove_IStoveInventoryItem_GetInserviceItemId()In-game item identifiers mapped to this product
ProductNameconst wchar_t*ReadStove_IStoveInventoryItem_GetProductName()Localized Product Names
Quantityint32_tReadStove_IStoveInventoryItem_GetQuantity()Quantity Purchased
ThumbnailUrlconst wchar_t*ReadStove_IStoveInventoryItem_GetThumbnailUrl()Product Main Thumbnail Image URL

Memory Management

ItemValue
Creating EntitySDK
Responsibility for RevocationSDK (Do Not Unlock, Invalid Once Callback Completes)

Example

c
void __cdecl OnFetchInventoryCallback(const IStoveCallbackResult* callbackResult, const IStoveInventoryList* list)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

    if (Stove_IStoveResult_GetResultCode(result) == 0)
    {
        uint32_t count = Stove_IStoveInventoryList_GetCount(list);

        for (uint32_t i = 0; i < count; ++i)
        {
            const IStoveInventoryItem* item = Stove_IStoveInventoryList_GetAt(list, i);

            int64_t productId = Stove_IStoveInventoryItem_GetProductId(item);
            int32_t quantity = Stove_IStoveInventoryItem_GetQuantity(item);

            // Please copy and save only the values you need.
        }
        // The list and its items will be invalidated once this callback finishes. Do not call Destroy().
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

Notes

  • It is passed only as the output of Stove_FetchInventory.
  • When verifying whether game items have been awarded, you must prevent duplicate processing based on TxnDetailNo.

See Also


IStoveInventoryList

Kind Struct · Module IAP · Version 3.5.0

Description

OnFetchInventoryCallback is the container passed to the callback. It wraps the IStoveInventoryItem array returned by Stove_FetchInventory.

This is a data type that the SDK populates and passes via a callback. It is not created directly by the caller.

This object and each item obtained via GetAt() are all owned by the SDK and are no longer valid once the callback call ends. Do not call Destroy(); instead, copy any values that need to be preserved within the callback.

Declaration

c
typedef struct IStoveInventoryList IStoveInventoryList;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
Countuint32_tReadStove_IStoveInventoryList_GetCount()Number of purchase history entries included in the results
At(index)const IStoveInventoryItem*ReadStove_IStoveInventoryList_GetAt()The purchase history entry at position index (starting from 0). If the value is index >= Count, it returns nullptr.

Memory Management

ItemValue
Creating EntitySDK
Responsibility for TerminationSDK (Do Not Unlock, Invalid Once Callback Completes)

Example

c
void __cdecl OnFetchInventoryCallback(const IStoveCallbackResult* callbackResult, const IStoveInventoryList* list)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

    if (Stove_IStoveResult_GetResultCode(result) == 0)
    {
        uint32_t count = Stove_IStoveInventoryList_GetCount(list);
        for (uint32_t i = 0; i < count; ++i)
        {
            const IStoveInventoryItem* item = Stove_IStoveInventoryList_GetAt(list, i);
            // Please copy and save only the values you need.
        }
        // The list and its individual items will be invalidated once this callback completes. Do not call Destroy().
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

Notes

  • It is passed only as the output of Stove_FetchInventory.
  • Previously, the array and count were passed as separate callback arguments, but now they are wrapped into this single container and passed together.

See Also


IStoveOrderProductParam

Kind Struct · Module IAP · Version 3.5.0

Description

These are the order items for each product stored in IStoveStartPurchaseParam. One is created for each product to be purchased and passed to SetProducts().

Create it as Stove_CreateParam(k_EStoveIAPTypeKind_OrderProductParam), populate it with a value using the setter, and once the purchase call is complete (or after the parent IStoveStartPurchaseParam is released), you must release it as Destroy().

Declaration

c
typedef struct IStoveOrderProductParam IStoveOrderProductParam;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessRequiredAccessorDescription
ProductIdint64_tReading and WritingYesStove_IStoveOrderProductParam_GetProductId() / Stove_IStoveOrderProductParam_SetProductId()Platform-specific product identifier. Must match ProductId for IStoveProduct.
SalePricedoubleReading and WritingYesStove_IStoveOrderProductParam_GetSalePrice() / Stove_IStoveOrderProductParam_SetSalePrice()The unit price (selling price) of this product as observed by the client. The server uses this to check for price discrepancies between the client and the server.
Quantityint32_tReading and WritingYesStove_IStoveOrderProductParam_GetQuantity() / Stove_IStoveOrderProductParam_SetQuantity()Quantity to Purchase

Memory Management

ItemValue
Creating EntityCaller (Stove_CreateParam(k_EStoveIAPTypeKind_OrderProductParam))
Responsibility for DismantlingCaller (Destroy() required)

Example

c
IStoveOrderProductParam* orderProduct = (IStoveOrderProductParam*)Stove_CreateParam(k_EStoveIAPTypeKind_OrderProductParam);

Stove_IStoveOrderProductParam_SetProductId(orderProduct, productId);
Stove_IStoveOrderProductParam_SetSalePrice(orderProduct, salePrice);
Stove_IStoveOrderProductParam_SetQuantity(orderProduct, 1);

IStoveOrderProductParam* orderProducts[] = { orderProduct };

// Please create the `startPurchaseParam` in advance by referring to the IStoveStartPurchaseParam documentation.
Stove_IStoveStartPurchaseParam_SetProducts(startPurchaseParam, orderProducts, 1);

Stove_StartPurchase(startPurchaseParam, OnStartPurchaseCallback, NULL, NULL, NULL);

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)orderProduct);

Mapping from IStoveProduct

IStoveProduct, returned by the Stove_FetchProducts callback, is a different type from this one, so you can't pass a product as-is. Copy the three values below.

This typeValue to takeNote
SetProductId()IStoveProduct::GetProductId()Copy it as-is.
SetSalePrice()IStoveProduct::GetSalePrice()Sale price for payment. Do not pass GetPrice() (list price) or GetDisplaySalePrice() (display).
SetQuantity()The quantity the user choseIStoveProduct::GetQuantity() is the number of items granted per single purchase, not the purchase quantity.

The list and each product passed to the callback are SDK-owned and can't be used after the callback returns. Copy the product ID and sale price inside the callback, then create and fill this type at purchase time.

c
// Values copied in the lookup callback
typedef struct { int64_t productId; double salePrice; } ShopItem;

void __cdecl OnFetchProductsFinished(const IStoveCallbackResult* callbackResult, const IStoveProductList* list)
{
    if (!Stove_IStoveResult_IsSuccessful(Stove_IStoveCallbackResult_GetResult(callbackResult)))
        return;

    uint32_t count = Stove_IStoveProductList_GetCount(list);
    for (uint32_t i = 0; i < count; ++i)
    {
        const IStoveProduct* product = Stove_IStoveProductList_GetAt(list, i);
        ShopItem item;
        item.productId = Stove_IStoveProduct_GetProductId(product);
        item.salePrice = Stove_IStoveProduct_GetSalePrice(product);
        // Keep item in the game's shop model.
    }
}

// At purchase time: fill from the stored values and the quantity the user chose
IStoveOrderProductParam* orderProduct = (IStoveOrderProductParam*)Stove_CreateParam(k_EStoveIAPTypeKind_OrderProductParam);
Stove_IStoveOrderProductParam_SetProductId(orderProduct, item.productId);
Stove_IStoveOrderProductParam_SetSalePrice(orderProduct, item.salePrice);
Stove_IStoveOrderProductParam_SetQuantity(orderProduct, count);   // purchase quantity, not the Quantity of IStoveProduct

Notes

  • SetProducts() does not take ownership of the object. The caller retains ownership of the IStoveOrderProductParam object and must call Destroy() directly after the purchase call is complete.
  • For SalePrice, please use the same SalePrice value as IStoveProduct. If the values differ, the server may treat this as a price discrepancy.
  • Quantity is the purchase quantity the user chose. Do not copy Quantity of IStoveProduct, which is the number of items granted per purchase.

See Also


IStoveOverImmersionInfo

Kind Struct · Module Base · Version 3.5.0

Description

Stove_OverImmersionNotification() This is the excessive use prevention notice information passed via the callback. This API is for use in South Korea only.

Contains the excessive use warning message, cumulative game playtime (in hours), and the duration the message is displayed. It is created by the SDK and passed only as a callback argument; the caller does not release it.

This callback is not a one-time event; it is sent to the target user repeatedly every hour. You must register it after the time when the notification can be displayed on the screen.

Declaration

c
typedef struct IStoveOverImmersionInfo IStoveOverImmersionInfo;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
Msgconst wchar_t*ReadStove_IStoveOverImmersionInfo_GetMsg()This is a warning about excessive engagement.
ElapsedHoursint32_tReadStove_IStoveOverImmersionInfo_GetElapsedHours()This is the cumulative time spent playing the game (in hours).
ExposureTimeint32_tReadStove_IStoveOverImmersionInfo_GetExposureTime()This is the message display time (in seconds).

Memory Management

ItemValue
Creating EntitySDK
Responsibility for DismantlingSDK, Passed only as a callback argument and invalidated once the callback completes. The caller does not call Destroy().

Example

c
void __cdecl OnOverImmersionNotificationCallback(const IStoveCallbackResult* callbackResult, const IStoveOverImmersionInfo* overImmersion)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

    if (Stove_IStoveResult_GetResultCode(result) == k_EStoveCommonResultCode_Success)
    {
        const wchar_t* msg = Stove_IStoveOverImmersionInfo_GetMsg(overImmersion);
        int32_t elapsedHours = Stove_IStoveOverImmersionInfo_GetElapsedHours(overImmersion);
        // Please implement the logic for a successful operation. (Display a warning message.)
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }

    // overImmersion does not call Destroy().
}

Notes

  • This API is for use in Korea only. Since the callback is not a one-time event but is sent to the target user repeatedly every hour, you must register for it after the point at which the notification can be displayed on the screen.
  • ElapsedHours represents hours. Be careful not to confuse it with ElapsedMinutes, which represents minutes (IStoveVietnamOverimmersionInfo).

See Also


IStoveOwnership

Kind Struct · Module Ownership · Version 3.5.0

Description

Represents one item owned by the logged-in user (base game, DLC, demo, etc.). Stove_FetchOwnerships is passed to OnOwnershipListCallback as IStoveOwnershipList. The legacy name is StovePCOwnership.

It is not created by the caller; it is read-only and has no setter. It is passed only as a callback argument and is invalidated once the callback completes.

If you need to use a value outside the callback, you must copy the field value to a separate variable inside the callback. You must not store the object itself.

Declaration

c
typedef struct IStoveOwnership IStoveOwnership;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
GameIdconst wchar_t*ReadStove_IStoveOwnership_GetGameId()This is the STOVE game ID associated with this ownership entry.
GameCodeint32_tReadStove_IStoveOwnership_GetGameCode()This is the product category for this item. EStoveOwnershipGameCode (Basic / Demo / DLC, etc.)
OwnershipCodeint32_tReadStove_IStoveOwnership_GetOwnershipCode()Ownership status of the item. EStoveOwnershipCode (Acquire / Lose / None)
PurchaseDateuint64_tReadStove_IStoveOwnership_GetPurchaseDate()This is the purchase time of the item. It is expressed as Unix epoch in UTC milliseconds and passes the server value as-is.

Memory Management

ItemValue
Creating EntitySDK
Responsibility for DismantlingSDK (Do Not Unlock), This will be invalidated once the OnOwnershipListCallback callback completes.

Example

c
void __cdecl OnOwnershipList(const IStoveCallbackResult* callbackResult, const IStoveOwnershipList* ownerships)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);
    if (Stove_IStoveResult_GetResultCode(result) == 0)
    {
        uint32_t count = Stove_IStoveOwnershipList_GetCount(ownerships);
        for (uint32_t i = 0; i < count; ++i)
        {
            const IStoveOwnership* ownership = Stove_IStoveOwnershipList_GetAt(ownerships, i);

            const wchar_t* gameId = Stove_IStoveOwnership_GetGameId(ownership);
            int32_t gameCode = Stove_IStoveOwnership_GetGameCode(ownership);
            int32_t ownershipCode = Stove_IStoveOwnership_GetOwnershipCode(ownership);
            uint64_t purchaseDate = Stove_IStoveOwnership_GetPurchaseDate(ownership);

            // Please implement logic that copies the necessary values before the callback ends.
        }
    }
}

Notes

  • The legacy name is StovePCOwnership.
  • This is output data that is passed exclusively via the callback for Stove_FetchOwnerships.
  • PurchaseDate is provided as a Unix epoch in UTC milliseconds, and since purchaseDate in the legacy interface (StovePCOwnership) also returns the same server value in the same format, there is no need to recalculate the value.

See Also


IStoveOwnershipList

Kind Struct · Module Ownership · Version 3.5.0

Description

This is a list wrapper that passes IStoveOwnership to OnOwnershipListCallback of Stove_FetchOwnerships.

It is not created by the caller; it is passed only as a callback argument. It does not call Destroy().

This list object and each IStoveOwnership* returned by GetAt() will all be invalidated once the callback ends. Any values needed outside the callback must be copied beforehand within the callback.

Declaration

c
typedef struct IStoveOwnershipList IStoveOwnershipList;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
Countuint32_tReadStove_IStoveOwnershipList_GetCount()The total number of ownership entries in the list.
At[index]const IStoveOwnership*ReadStove_IStoveOwnershipList_GetAt(index)Returns the indexth ownership entry. If index is out of range, returns nullptr.

Memory Management

ItemValue
Creating EntitySDK
Responsibility for DismantlingSDK (Do Not Unlock), Once the OnOwnershipListCallback callback completes, the list and each item returned by GetAt() will be invalidated.

Example

c
void __cdecl OnOwnershipList(const IStoveCallbackResult* callbackResult, const IStoveOwnershipList* ownerships)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);
    if (Stove_IStoveResult_GetResultCode(result) == 0)
    {
        uint32_t count = Stove_IStoveOwnershipList_GetCount(ownerships);
        for (uint32_t i = 0; i < count; ++i)
        {
            const IStoveOwnership* ownership = Stove_IStoveOwnershipList_GetAt(ownerships, i);
            if (ownership == nullptr)
            {
                continue;
            }

            // Please implement the logic for each item.
        }
    }
}

Notes

  • This is output data that is passed exclusively via the callback for Stove_FetchOwnerships.
  • This is not an out-parameter using the array + count method, but rather an SDK-specific list wrapper type that includes GetCount() and GetAt().

See Also


IStoveProduct

Kind Struct · Module IAP · Version 3.5.0

Description

Represents a single item sold in a store. The result of the Stove_FetchProducts call is stored in IStoveProductList and passed to the OnFetchProductsCallback callback.

This is the data type that the SDK populates and passes via a callback. The caller does not create it directly. Since it contains 32 members, the table below categorizes them by type.

The list and each item passed to the callback are owned by the SDK and are no longer valid once the callback call ends. Do not call Destroy(); instead, copy any values that need to be retained within the callback.

Declaration

c
typedef struct IStoveProduct IStoveProduct;
// To access members, use the access functions listed in the member table below.

Members

Basic Information

NameTypeAccessAccessorDescription
ProductIdint64_tReadStove_IStoveProduct_GetProductId()Platform-Specific Product Identifier
InserviceItemIdconst wchar_t*ReadStove_IStoveProduct_GetInserviceItemId()In-game item identifiers mapped to this product
ProductNameconst wchar_t*ReadStove_IStoveProduct_GetProductName()Localized Product Names
ProductDescriptionconst wchar_t*ReadStove_IStoveProduct_GetProductDescription()Localized Product Descriptions
Quantityint32_tReadStove_IStoveProduct_GetQuantity()Number of items awarded per purchase of this product
ProductTypeCodeEStoveProductTypeCodeReadStove_IStoveProduct_GetProductTypeCode()Product Category Code
CategoryIdconst wchar_t*ReadStove_IStoveProduct_GetCategoryId()The store category identifier for this product
CategoryNameconst wchar_t*ReadStove_IStoveProduct_GetCategoryName()The localized name of the store category to which this product belongs
ThumbnailUrlconst wchar_t*ReadStove_IStoveProduct_GetThumbnailUrl()Product Main Thumbnail Image URL

Price

NameTypeAccessAccessorDescription
CurrencyCodeconst wchar_t*ReadStove_IStoveProduct_GetCurrencyCode()ISO 4217 currency codes (e.g., L"USD", L"KRW")
PricedoubleReadStove_IStoveProduct_GetPrice()List price used for payment processing
DisplayPricedoubleReadStove_IStoveProduct_GetDisplayPrice()List price displayed on screen (may differ from Price due to rounding, etc.)
StrDisplayPriceconst wchar_t*ReadStove_IStoveProduct_GetStrDisplayPrice()Display price string with currency format applied
SalePricedoubleReadStove_IStoveProduct_GetSalePrice()Selling price used for payment processing (same as Price unless a discount is applied)
DisplaySalePricedoubleReadStove_IStoveProduct_GetDisplaySalePrice()Selling price displayed on the screen
StrDisplaySalePriceconst wchar_t*ReadStove_IStoveProduct_GetStrDisplaySalePrice()Display price string with currency format applied

Discount

NameTypeAccessAccessorDescription
IsDiscountedboolReadStove_IStoveProduct_IsDiscounted()Whether there is a current discount
DiscountTypeEStoveDiscountTypeReadStove_IStoveProduct_GetDiscountType()Discount Calculation Method
DiscountTypeValueint32_tReadStove_IStoveProduct_GetDiscountTypeValue()Discount value. If DiscountType is FixedRate, it is a percentage (e.g., 10 = 10% discount); if it is FlatRate, it is a fixed discount amount based on the product's currency.
DiscountStartDateint64_tReadStove_IStoveProduct_GetDiscountStartDate()Discount Start Time (UTC epoch milliseconds)
DiscountEndDateint64_tReadStove_IStoveProduct_GetDiscountEndDate()Discount End Time (UTC epoch milliseconds)

Purchase Quantity and History

NameTypeAccessAccessorDescription
TotalQuantityint32_tReadStove_IStoveProduct_GetTotalQuantity()Total quantity of this product purchased across all categories
MemberQuantityint32_tReadStove_IStoveProduct_GetMemberQuantity()Quantity purchased under the login account (member)
GuidQuantityint32_tReadStove_IStoveProduct_GetGuidQuantity()Quantity purchased within the current character GUID range
HasPurchasedboolReadStove_IStoveProduct_HasPurchased()Whether the user has ever purchased this product
IsWithdrawableboolReadStove_IStoveProduct_IsWithdrawable()Whether the product is subject to the subscription cancellation (consumer protection refund) policy

Purchase Limits and Sales Periods

NameTypeAccessAccessorDescription
PurchaseLimitTypeCodeEStovePurchaseLimitTypeCodeReadStove_IStoveProduct_GetPurchaseLimitTypeCode()Purchase Restriction Policy
PurchaseLimitCountint32_tReadStove_IStoveProduct_GetPurchaseLimitCount()Purchase Limit Under Current Policy
SaleLimitCountint32_tReadStove_IStoveProduct_GetSaleLimitCount()Total sales quantity limit for the product (0 means unlimited)
SalesStartDateint64_tReadStove_IStoveProduct_GetSalesStartDate()Start time of the sales period (UTC epoch milliseconds)
SalesEndDateint64_tReadStove_IStoveProduct_GetSalesEndDate()End Time of the Sales Period (UTC epoch milliseconds)
PurchaseAvailabilityCodeint16_tReadStove_IStoveProduct_GetPurchaseAvailabilityCode()Availability code. 1: Available for purchase, 2: Not available for purchase (purchase limit exceeded), 3: Not available for purchase (out of stock in the web store), 4: Not available for purchase (already claimed in the web store). This set of values may be expanded on the server. It is based on a request to purchase a single unit of a product; results may differ if you request to purchase two or more units together. Since the server API schema defines this field (and other “code” fields) as Int16, the type is int16_t.

Memory Management

ItemValue
Creating EntitySDK
Responsibility for DismantlingSDK (Do Not Release, Invalid Once Callback Completes)

Example

c
void __cdecl OnFetchProductsCallback(const IStoveCallbackResult* callbackResult, const IStoveProductList* list)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

    if (Stove_IStoveResult_GetResultCode(result) == 0)
    {
        uint32_t count = Stove_IStoveProductList_GetCount(list);

        for (uint32_t i = 0; i < count; ++i)
        {
            const IStoveProduct* product = Stove_IStoveProductList_GetAt(list, i);

            int64_t productId = Stove_IStoveProduct_GetProductId(product);
            const wchar_t* productName = Stove_IStoveProduct_GetProductName(product);
            double salePrice = Stove_IStoveProduct_GetSalePrice(product);
            bool onSale = Stove_IStoveProduct_IsDiscounted(product);

            // Please copy and save only the values you need.
        }
        // The list and its items will be invalidated once this callback completes. Do not call Destroy().
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

Notes

  • It is passed only as the output of Stove_FetchProducts.
  • Please use Price / SalePrice for payment processing (server verification), and DisplayPrice / DisplaySalePrice / StrDisplayPrice / StrDisplaySalePrice for display purposes only.
  • Since the system checks for discrepancies with the price observed by the server at the time of purchase, you must pass the SalePrice value for this product as-is to SalePrice in IStoveOrderProductParam.
  • DiscountStartDate / DiscountEndDate / SalesStartDate / SalesEndDate are all integers representing UTC epoch milliseconds (milliseconds since January 1, 1970, UTC). They are not in the YYYYMMDDHHMMSS format.
  • For how to move the values into the purchase parameter, see Mapping from IStoveProduct in IStoveOrderProductParam. Quantity is the number of items granted per purchase, so do not copy it as the purchase quantity.

See Also


IStoveProductList

Kind Struct · Module IAP · Version 3.5.0

Description

OnFetchProductsCallback is the container passed to the callback. It wraps the IStoveProduct array returned by Stove_FetchProducts.

This is a data type that the SDK populates and passes via a callback. The caller does not create it directly.

This object and each item obtained via GetAt() are all owned by the SDK and are no longer valid once the callback completes. Do not call Destroy(); instead, copy any values you need to preserve within the callback.

Declaration

c
typedef struct IStoveProductList IStoveProductList;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
Countuint32_tReadStove_IStoveProductList_GetCount()Number of items in the results
At(index)const IStoveProduct*ReadStove_IStoveProductList_GetAt()The item at position index (starting from 0). If it is index >= Count, it returns nullptr.

Memory Management

ItemValue
Creating EntitySDK
Responsibility for DismantlingSDK (Do not unlock, becomes invalid once the callback is complete)

Example

c
void __cdecl OnFetchProductsCallback(const IStoveCallbackResult* callbackResult, const IStoveProductList* list)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

    if (Stove_IStoveResult_GetResultCode(result) == 0)
    {
        uint32_t count = Stove_IStoveProductList_GetCount(list);
        for (uint32_t i = 0; i < count; ++i)
        {
            const IStoveProduct* product = Stove_IStoveProductList_GetAt(list, i);
            // Please copy and save only the values you need.
        }
        // The list and its items will be invalidated once this callback finishes. Do not call Destroy().
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

Notes

  • It is passed only as the output of Stove_FetchProducts.
  • Previously, the array and count were passed as separate callback arguments, but now they are wrapped together in this single container and passed.

See Also


IStovePurchasedProduct

Kind Struct · Module IAP · Version 3.5.0

Description

Represents a single item in a completed purchase (transaction). It is passed as an array containing both IStoveStartPurchaseOutcome, the result of Stove_StartPurchase, and IStoveConfirmPurchaseOutcome, the result of Stove_ConfirmPurchase.

This is a data type that the SDK populates and passes via a callback. The caller does not create it directly.

The array and each item passed to the callback are owned by the SDK and are no longer valid once the callback completes. Do not call Destroy(); instead, copy any values you need to preserve within the callback.

Declaration

c
typedef struct IStovePurchasedProduct IStovePurchasedProduct;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
TxnDetailNoint64_tReadStove_IStovePurchasedProduct_GetTxnDetailNo()Transaction Detail Number (TID for each product within the master transaction)
ProductIdint64_tReadStove_IStovePurchasedProduct_GetProductId()Platform-Specific Product Identifier
CategoryIdconst wchar_t*ReadStove_IStovePurchasedProduct_GetCategoryId()The store category identifier for this product
TotalQuantityint32_tReadStove_IStovePurchasedProduct_GetTotalQuantity()Total purchase quantity for this item
MemberQuantityint32_tReadStove_IStovePurchasedProduct_GetMemberQuantity()Quantity purchased within the member (account) scope
GuidQuantityint32_tReadStove_IStovePurchasedProduct_GetGuidQuantity()Quantity purchased within the current character GUID range

Memory Management

ItemValue
Creating EntitySDK
Responsibility for DismantlingSDK (Do not unwrap, becomes invalid once the callback completes)

Example

c
void __cdecl OnConfirmPurchaseCallback(const IStoveCallbackResult* callbackResult, const IStoveConfirmPurchaseOutcome* outcome)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

    // In the Steam launcher flow IsConfirmed is always false; follow the common judgment in the Stove_ConfirmPurchase example.
    if (Stove_IStoveResult_GetResultCode(result) == 0 && Stove_IStoveConfirmPurchaseOutcome_IsConfirmed(outcome))
    {
        uint32_t count = Stove_IStoveConfirmPurchaseOutcome_GetPurchasedProductCount(outcome);

        for (uint32_t i = 0; i < count; ++i)
        {
            const IStovePurchasedProduct* purchasedProduct = Stove_IStoveConfirmPurchaseOutcome_GetPurchasedProductAt(outcome, i);

            int64_t productId = Stove_IStovePurchasedProduct_GetProductId(purchasedProduct);
            int32_t totalQuantity = Stove_IStovePurchasedProduct_GetTotalQuantity(purchasedProduct);

            // Please copy and save only the values you need.
        }
        // The `outcome` and its items will be invalidated once this callback finishes. Do not call `Destroy()`.
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

Notes

See Also


IStovePurchaseParam

Kind Struct · Module IAP · Version 3.5.0

Description

This option, contained in IStoveStartPurchaseParam, determines how Stove_StartPurchase behaves. It inherits from IStoveWebViewLayoutParam, and all WebView* fields apply only when Operation is not Default.

Create it as Stove_CreateParam(k_EStoveIAPTypeKind_PurchaseParam), set its value using a setter, and then release it as Destroy() once the purchase call is complete.

Declaration

c
typedef struct IStovePurchaseParam IStovePurchaseParam;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessRequiredAccessorDescription
OperationEStovePurchaseOperationReading and WritingYesStove_IStovePurchaseParam_GetOperation() / Stove_IStovePurchaseParam_SetOperation()Mode Selector
WebViewModeEStoveWebViewModeReading and WritingNoStove_IStovePurchaseParam_GetWebViewMode() / Stove_IStovePurchaseParam_SetWebViewMode()WebView display mode (external browser / SDK-embedded WebView). Applies only when Operation != Default. This is an inherited member of IStoveWebViewLayoutParam.
WebViewPosXint32_tReading and WritingNoStove_IStovePurchaseParam_GetWebViewPosX() / Stove_IStovePurchaseParam_SetWebViewPosX()WebView x-coordinate (pixels). Applies only when Operation != Default. This is an inherited member of IStoveWebViewLayoutParam.
WebViewPosYint32_tReading and WritingNoStove_IStovePurchaseParam_GetWebViewPosY() / Stove_IStovePurchaseParam_SetWebViewPosY()WebView y-coordinate (pixels). Applies only when Operation != Default. This is an inherited member of IStoveWebViewLayoutParam.
WebViewWidthint32_tReading and WritingNoStove_IStovePurchaseParam_GetWebViewWidth() / Stove_IStovePurchaseParam_SetWebViewWidth()WebView width (pixels). Applies only when Operation != Default is true. It is an inherited member of IStoveWebViewLayoutParam.
WebViewHeightint32_tReading and WritingNoStove_IStovePurchaseParam_GetWebViewHeight() / Stove_IStovePurchaseParam_SetWebViewHeight()WebView height (pixels). Applies only when Operation != Default. This is an inherited member of IStoveWebViewLayoutParam.

Memory Management

ItemValue
Creating EntityCaller (Stove_CreateParam(k_EStoveIAPTypeKind_PurchaseParam))
Responsibility for DismantlingCaller (Destroy() required)

Example

c
IStovePurchaseParam* purchaseParam = (IStovePurchaseParam*)Stove_CreateParam(k_EStoveIAPTypeKind_PurchaseParam);

Stove_IStovePurchaseParam_SetOperation(purchaseParam, k_EStovePurchaseOperation_WithWebViewAndConfirmResult);
Stove_IStovePurchaseParam_SetWebViewMode(purchaseParam, k_EStoveWebViewMode_Internal);
Stove_IStovePurchaseParam_SetWebViewWidth(purchaseParam, 480);
Stove_IStovePurchaseParam_SetWebViewHeight(purchaseParam, 640);

// Please create the `startPurchaseParam` in advance by referring to the IStoveStartPurchaseParam documentation.
Stove_IStoveStartPurchaseParam_SetPurchaseParam(startPurchaseParam, purchaseParam);

Stove_StartPurchase(startPurchaseParam, OnStartPurchaseCallback, NULL, NULL, NULL);

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)purchaseParam);

Notes

  • SetPurchaseParam() does not take ownership of this object. The caller retains ownership of this object and must call Destroy() directly after the purchase call is complete.
  • Operation If this is Default, the WebView* field is ignored.

See Also


IStoveRank

Kind Struct · Module GameSupport · Version 3.5.0

Description

IStoveRank is a type that holds a single entry in the leaderboard. Each entry is obtained from IStoveRanking, the result of a query for Stove_FetchRanking, as GetAt(index).

This type is created by the SDK and passed via a callback; it is not created directly by the caller.

Declaration

c
typedef struct IStoveRank IStoveRank;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
Nicknameconst wchar_t*ReadStove_IStoveRank_GetNickname()This is the user's nickname.
ProfileImageconst wchar_t*ReadStove_IStoveRank_GetProfileImage()This is the URL for the user's profile picture.
Scoreint32_tReadStove_IStoveRank_GetScore()Here are the leaderboard scores.
Rankuint32_tReadStove_IStoveRank_GetRank()This is the user's current ranking.

Memory Management

ItemValue
Creating EntitySDK
Responsibility for DismantlingSDK (Do not unwrap. If the IStoveRanking callback parameter containing this object is invalidated, it will be invalidated as well)

Example

c
void OnGetRankingFinished(const IStoveCallbackResult* callbackResult, const IStoveRanking* ranking)
{
    if (Stove_IStoveResult_GetResultCode(Stove_IStoveCallbackResult_GetResult(callbackResult)) == 0 && ranking != NULL)
    {
        uint32_t count = Stove_IStoveRanking_GetCount(ranking);
        for (uint32_t i = 0; i < count; i++)
        {
            const IStoveRank* rank = Stove_IStoveRanking_GetAt(ranking, i);
            const wchar_t* nickname = Stove_IStoveRank_GetNickname(rank);
            uint32_t place = Stove_IStoveRank_GetRank(rank);

            // Please implement the logic for a successful outcome.
        }
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

Notes

  • It is not created directly by the caller; it can only be obtained through IStoveRanking.
  • "Ranking" refers to the entire leaderboard, while "Rank" refers to a single entry on the leaderboard.

See Also


IStoveRanking

Kind Struct · Module GameSupport · Version 3.5.0

Description

IStoveRanking is a container type that wraps a page-based leaderboard, which is passed as OnGetRankingCallback. It is passed as the onFinished callback argument of Stove_FetchRanking.

"Ranking" refers to the entire leaderboard, while "Rank" refers to a single entry within it. This type is created by the SDK and passed via a callback; it is not created directly by the caller.

Declaration

c
typedef struct IStoveRanking IStoveRanking;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
Countuint32_tReadStove_IStoveRanking_GetCount()This is the number of ranking items included on this page.
,const IStoveRank*ReadStove_IStoveRanking_GetAt(index)Retrieves the ranking entry starting from index 0. If the index is index >= Count, it returns NULL.
TotalCountuint32_tReadStove_IStoveRanking_GetTotalCount()This is the total number of ranking items across the entire page.

Memory Management

ItemValue
Creating EntitySDK
Responsibility for DismantlingSDK (Do not disable. It will be invalidated once the Stove_FetchRanking callback completes)

Example

c
void OnGetRankingFinished(const IStoveCallbackResult* callbackResult, const IStoveRanking* ranking)
{
    if (Stove_IStoveResult_GetResultCode(Stove_IStoveCallbackResult_GetResult(callbackResult)) == 0 && ranking != NULL)
    {
        uint32_t count = Stove_IStoveRanking_GetCount(ranking);
        uint32_t totalCount = Stove_IStoveRanking_GetTotalCount(ranking);

        for (uint32_t i = 0; i < count; i++)
        {
            const IStoveRank* rank = Stove_IStoveRanking_GetAt(ranking, i);
            // Please implement the logic for the success case.
        }
    }
    else
    {
        // Please implement the logic for when a failure occurs.
    }
}

Notes

  • It is not created directly by the caller and can only be obtained through the Stove_FetchRanking callback.
  • The IStoveRank items contained herein will also be invalidated once the callback completes, along with this list.

See Also


IStoveRestartAppIfNecessaryOutcome

Kind Struct · Module Base · Version 3.5.0

Description

Stove_RestartAppIfNecessary() Holds the result of an asynchronous call. requiresRestart It is designed to wrap a single flag in a domain entity so that the callback signature remains unchanged even if fields are added in the future.

The SDK is created and passed only as a callback argument; the caller does not release it.

Declaration

c
typedef struct IStoveRestartAppIfNecessaryOutcome IStoveRestartAppIfNecessaryOutcome;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
IsRestartRequiredboolReadStove_IStoveRestartAppIfNecessaryOutcome_IsRestartRequired()If true, you must restart the app via the Stove launcher (the current process must be terminated). If false, you may proceed.

Memory Management

ItemValue
Creating EntitySDK
Responsibility for DismantlingSDK, Passed only as a callback argument and is invalidated once the callback completes. The caller does not call Destroy().

Example

c
void __cdecl OnRestartAppIfNecessaryCallback(const IStoveCallbackResult* callbackResult, const IStoveRestartAppIfNecessaryOutcome* outcome)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

    if (Stove_IStoveResult_GetResultCode(result) == k_EStoveCommonResultCode_Success)
    {
        if (Stove_IStoveRestartAppIfNecessaryOutcome_IsRestartRequired(outcome))
        {
            // Please implement the logic to close the app.
        }
        else
        {
            // Please implement the logic that keeps the process running (such as calling Stove_Initialize(), etc.).
        }
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }

    // outcome does not call Destroy().
}

Notes

  • Stove_RestartAppIfNecessary() must be called before Stove_Initialize().
  • If IsRestartRequired() is true and you do not terminate the process, the SDK may not function correctly afterward.

See Also


IStoveRestartAppIfNecessaryParam

Kind Struct · Module Base · Version 3.5.0

Description

Contains the parameters required for the Stove_RestartAppIfNecessary() call. This includes the Stove environment, game ID, application key, platform name, and options related to launcher verification.

Create it using Stove_CreateParam(k_EStoveBaseTypeKind_RestartAppIfNecessaryParam), configure each field, and then release it using Destroy() when the call is complete.

Declaration

c
typedef struct IStoveRestartAppIfNecessaryParam IStoveRestartAppIfNecessaryParam;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
Environmentconst wchar_t*Reading and WritingStove_IStoveRestartAppIfNecessaryParam_GetEnvironment() / SetEnvironment()These are the Stove environment values.
GameIdconst wchar_t*Reading and WritingStove_IStoveRestartAppIfNecessaryParam_GetGameId() / SetGameId()This is the Stove game ID.
AppKeyconst wchar_t*Reading and WritingStove_IStoveRestartAppIfNecessaryParam_GetAppKey() / SetAppKey()This is the Stove application key value.
WaitTimeMilliSecuint32_tReading and WritingStove_IStoveRestartAppIfNecessaryParam_GetWaitTimeMilliSec() / SetWaitTimeMilliSec()This is the wait time (in milliseconds) used to determine whether the app was launched via the launcher.
LaunchStoveLauncherboolReading and WritingStove_IStoveRestartAppIfNecessaryParam_GetLaunchStoveLauncher() / SetLaunchStoveLauncher()This determines whether to launch the Stove launcher when it is not currently running.
PlatformNameconst wchar_t*Reading and WritingStove_IStoveRestartAppIfNecessaryParam_GetPlatformName() / SetPlatformName()This is the platform name. It is a selectable field and should only be specified when integrating with platforms other than Stove (such as Steam). If not set, it is an empty string; an empty string or L"Stove" indicates integration with Stove only.

Memory Management

ItemValue
Creating EntityCaller (Stove_CreateParam(k_EStoveBaseTypeKind_RestartAppIfNecessaryParam))
Responsibility for DismantlingCaller (Destroy() required), Release this after the API call is complete.

Example

c
IStoveRestartAppIfNecessaryParam* param =
    (IStoveRestartAppIfNecessaryParam*)Stove_CreateParam(k_EStoveBaseTypeKind_RestartAppIfNecessaryParam);

Stove_IStoveRestartAppIfNecessaryParam_SetEnvironment(param, L"real");
Stove_IStoveRestartAppIfNecessaryParam_SetGameId(param, L"YOUR_GAME_ID");
Stove_IStoveRestartAppIfNecessaryParam_SetAppKey(param, L"YOUR_APP_KEY");
Stove_IStoveRestartAppIfNecessaryParam_SetLaunchStoveLauncher(param, true);

Stove_RestartAppIfNecessary(param, OnRestartAppIfNecessaryCallback, NULL);

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param);

Notes

  • Stove_RestartAppIfNecessary() must be called before Stove_Initialize(). The SDK reuses the cached Environment/GameId/AppKey from this call in the subsequent Stove_Initialize() call as well.
  • In the previous interface, Environment/GameId/AppKey were located in IStoveInitializeParam, but in the current interface, they have been moved to this type. These fields are no longer present in IStoveInitializeParam.
  • PlatformName is used to specify the IPC path for communicating with the launcher. If the value is left blank or L"Stove" is specified, the existing path is used. If you enter an arbitrary value not supported by the launcher, the path will change, causing k_EStoveResultCode_IpcConnectFailed (307) or k_EStoveResultCode_IpcTimeout (309) to occur; therefore, do not configure this setting unless you plan to integrate with platforms other than Stove.

See Also


IStoveResult

Kind Struct · Module Base · Version 3.5.0

Description

Contains the results of a synchronous API call. It includes the method code that identifies the API that generated the result and the result code.

Most synchronous APIs, such as Stove_Initialize() and Stove_GetUser(), return this type. The returned object must be released using Destroy() after use.

Declaration

c
typedef struct IStoveResult IStoveResult;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
MethodCodeuint32_tReadStove_IStoveResult_GetMethodCode()This is a globally unique method code that identifies the API that generated this result. It encodes modules in blocks of 1,000 (see EStove<Module>MethodCode per module).
ResultCodeuint32_tReadStove_IStoveResult_GetResultCode()This is the result code. A value of 0 (Success) indicates success; any value other than 0 indicates failure. The common code is EStoveCommonResultCode (0–299), and the module-specific code is EStoveResultCode (300–).
IsSuccessfulboolReadStove_IStoveResult_IsSuccessful()Whether it succeeds (the same check as whether ResultCode is 0).

Memory Management

ItemValue
Creating EntitySDK (Return Value of a Synchronous API Call)
Responsibility for DismantlingCaller (Destroy() required)

Example

c
IStoveResult* result = Stove_Uninitialize();

if (Stove_IStoveResult_GetResultCode(result) == k_EStoveCommonResultCode_Success)
{
    // Please implement the logic for a successful outcome.
}
else
{
    // Please implement the logic for when a failure occurs.
}

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result);

Notes

  • It is used as the return value for synchronous APIs (such as Stove_Initialize and Stove_GetUser) that do not use callbacks. The results of asynchronous API callbacks are passed via IStoveCallbackResult.
  • The result code is either EStoveCommonResultCode (general, 0–299) or EStoveResultCode (module-specific, 300–). The previous module-specific code EStoveBaseResultCode has been discontinued and consolidated into EStoveResultCode.
  • The flat C access function includes Stove_IStoveResult_IsSuccessful(), which allows you to immediately obtain the same result as GetResultCode() == 0.

See Also


IStoveSendLogParam

Kind Struct · Module Log · Version 3.5.0

Description

This is an input parameter of Stove_SendLog. Create it as Stove_CreateParam(k_EStoveLogTypeKind_SendLogParam), populate it with values using the setters in the member table below, and release it once the call is complete.

You do not need to fill in fields for which you do not know the value. Numeric fields will retain the default value 0, and string fields will remain empty/nullptr.

The game only needs to populate the fields exposed in this structure. The SDK automatically populates and transmits the remaining items, such as device information, GDS information, session ID, timestamp, game ID, and environment, along with the data.

Declaration

c
typedef struct IStoveSendLogParam IStoveSendLogParam;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
Auidint64_tReading and WritingStove_IStoveSendLogParam_GetAuid() / SetAuid()This is the account UID (STOVE account identifier).
Cuidint64_tReading and WritingStove_IStoveSendLogParam_GetCuid() / SetCuid()This is the character UID (in-game character identifier).
MktType1const wchar_t*Reading and WritingStove_IStoveSendLogParam_GetMktType1() / SetMktType1()This is the name of the integrated third-party marketing service (Slot 1).
MktId1const wchar_t*Reading and WritingStove_IStoveSendLogParam_GetMktId1() / SetMktId1()This is an identifier (campaign/referrer ID) issued by Slot 1 Marketing Services.
MktType2const wchar_t*Reading and WritingStove_IStoveSendLogParam_GetMktType2() / SetMktType2()This is the name of the integrated third-party marketing service (Slot 2).
MktId2const wchar_t*Reading and WritingStove_IStoveSendLogParam_GetMktId2() / SetMktId2()This is an identifier issued by Slot 2 Marketing Services.
GameVersionconst wchar_t*Reading and WritingStove_IStoveSendLogParam_GetGameVersion() / SetGameVersion()This is the game client version string (e.g., L"1.2.3").
LogGroupIdconst wchar_t*Reading and WritingStove_IStoveSendLogParam_GetLogGroupId() / SetLogGroupId()A correlation ID that groups multiple related log entries into a single set.
ServerCodeconst wchar_t*Reading and WritingStove_IStoveSendLogParam_GetServerCode() / SetServerCode()This is the server code for the world/region the user is connected to.
ServerCodeDetailconst wchar_t*Reading and WritingStove_IStoveSendLogParam_GetServerCodeDetail() / SetServerCodeDetail()ServerCode These are the detailed codes for sub-servers, channels, shards, and other elements under this level.
LevelCodeconst wchar_t*Reading and WritingStove_IStoveSendLogParam_GetLevelCode() / SetLevelCode()This is the account level at the time the log was recorded.
LevelCodeDetailconst wchar_t*Reading and WritingStove_IStoveSendLogParam_GetLevelCodeDetail() / SetLevelCodeDetail()This is the character level at the time the log was recorded. Although the name includes "Detail," this is not a sub-level of LevelCode; rather, it corresponds to the character level value within the account range LevelCode.
ExternalIdconst wchar_t*Reading and WritingStove_IStoveSendLogParam_GetExternalId() / SetExternalId()This identifier is used to link and track everything from ad attribution to in-game behavior. Games integrated with Singular (MMP) transmit the SDID (Singular Device ID).
Contentsconst wchar_t*Reading and WritingStove_IStoveSendLogParam_GetContents() / SetContents()This is a free-form log payload not covered by the fields above (typically a JSON document encoded as a wide string). It corresponds to the action_param field in the legacy 81plug.

Memory Management

ItemValue
CreatorCaller (Stove_CreateParam(k_EStoveLogTypeKind_SendLogParam))
Responsibility for DismantlingCaller (Stove_IStoveTypeBase_Destroy() required), Stove_SendLog() can be released immediately after the call returns.

Example

c
IStoveSendLogParam* logParam = (IStoveSendLogParam*)Stove_CreateParam(k_EStoveLogTypeKind_SendLogParam);

Stove_IStoveSendLogParam_SetAuid(logParam, auid);
Stove_IStoveSendLogParam_SetCuid(logParam, cuid);
Stove_IStoveSendLogParam_SetContents(logParam, L"{\"event\":\"login\"}");

Stove_SendLog(logParam, OnSendLogFinished, nullptr);

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)logParam);

Notes

  • MktType1/MktId1 and MktType2/MktId2 are two independent slots. Since they do not have a primary/fallback relationship, fill in only the corresponding slot.
  • Contrary to its name, LevelCodeDetail is not a subvalue of LevelCode but a separate value within the character range.
  • Contents corresponds to the action_param field in the legacy 81plug.

See Also


IStoveSetGameProfileParam

Kind Struct · Module Base · Version 3.5.0

Description

This is the game profile structure passed when calling Stove_SetGameProfile(). It contains the game's world identifier and the character number within that world.

Create it using Stove_CreateParam(k_EStoveBaseTypeKind_SetGameProfileParam), configure each field, and then release it using Destroy() when the call is complete.

Declaration

c
typedef struct IStoveSetGameProfileParam IStoveSetGameProfileParam;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
WorldIdconst wchar_t*Reading and WritingStove_IStoveSetGameProfileParam_GetWorldId() / SetWorldId()This is the game's world identifier.
CharacterNoint64_tReading and WritingStove_IStoveSetGameProfileParam_GetCharacterNo() / SetCharacterNo()This is the character number on the server.

Memory Management

ItemValue
Creating EntityCaller (Stove_CreateParam(k_EStoveBaseTypeKind_SetGameProfileParam))
Responsibility for DismantlingCaller (Destroy() required), Release this after the API call is complete.

Example

c
IStoveSetGameProfileParam* profileParam =
    (IStoveSetGameProfileParam*)Stove_CreateParam(k_EStoveBaseTypeKind_SetGameProfileParam);

Stove_IStoveSetGameProfileParam_SetWorldId(profileParam, L"world_01");
Stove_IStoveSetGameProfileParam_SetCharacterNo(profileParam, 12345);

IStoveResult* result = Stove_SetGameProfile(profileParam);

if (Stove_IStoveResult_GetResultCode(result) == k_EStoveCommonResultCode_Success)
{
    // Please implement the logic for a successful outcome.
}
else
{
    // Please implement the logic for when an error occurs.
}

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result);
Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)profileParam);

Notes

  • Its former name was StoveGameProfileParams. In the old structure, the CharacterNo field was incorrectly labeled as "worldId Length", it is actually a character number, and the CharacterNo label in the current interface accurately reflects its meaning.

See Also


IStoveSetStatOutcome

Kind Struct · Module GameSupport · Version 3.5.0

Description

IStoveSetStatOutcome is a type that contains the result information returned when the statistics (Stat) modification API completes. It is passed as the onFinished callback (OnSetStatCallback) argument of Stove_SetStat.

This type is created by the SDK and passed via a callback; it is not created directly by the caller.

Declaration

c
typedef struct IStoveSetStatOutcome IStoveSetStatOutcome;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
ErrorMessageconst wchar_t*ReadStove_IStoveSetStatOutcome_GetErrorMessage()This is an exception message that may occur while updating statistical values. Values may be populated even if the call was successful; currently, only integer overflow is returned (other values may be added in the future). If integer overflow is returned, it means the value you are trying to set exceeds the int32 range and has been truncated. It consists solely of ASCII characters.
CurrentValueint32_tReadStove_IStoveSetStatOutcome_GetCurrentValue()This is the current (updated) value of the statistics reflecting the changes.
IsUpdatedboolReadStove_IStoveSetStatOutcome_IsUpdated()This indicates whether the statistical value has actually changed. If you set it to the same value as the existing one, the value will not change, so it will result in false. Even in this case, the call itself is successful.

Memory Management

ItemValue
CreatorSDK
Responsibility for DismantlingSDK (Do not disable. It will be invalidated once the Stove_SetStat callback completes)

Example

c
void OnSetStatFinished(const IStoveCallbackResult* callbackResult, const IStoveSetStatOutcome* statOutcome)
{
    if (Stove_IStoveResult_GetResultCode(Stove_IStoveCallbackResult_GetResult(callbackResult)) == 0 && statOutcome != NULL)
    {
        if (Stove_IStoveSetStatOutcome_IsUpdated(statOutcome))
        {
            int32_t currentValue = Stove_IStoveSetStatOutcome_GetCurrentValue(statOutcome);
            // Please implement the logic for a successful outcome.
        }
    }
    else
    {
        // Please implement the logic for when a failure occurs.
    }
}

Notes

  • It is not created directly by the caller; it can only be obtained through the Stove_SetStat callback.
  • Even if you set the value back to its original value, the call itself succeeds, and in this case, IsUpdated is passed as false. This does not indicate a failure; it simply means the value has not changed, so it should not be treated as an error.
  • ErrorMessage may be populated even when the call is successful.
  • If the value you are trying to set exceeds the int32 range, it will be truncated to 2147483647. Even in this case, the call will succeed, and IsUpdated will be passed as true.
  • You can check whether the value has been truncated by seeing if integer overflow is stored in ErrorMessage.

See Also


IStoveSetStatParam

Kind Struct · Module GameSupport · Version 3.5.0

Description

IStoveSetStatParam is a parameter type that specifies the statistic (Stat) to be modified and the new value to be applied. It uses Stove_SetStat as its input.

The caller creates it as Stove_CreateParam(k_EStoveGameSupportTypeKind_SetStatParam), populates it with a value, and then releases it as Destroy() once the API call is complete.

Declaration

c
typedef struct IStoveSetStatParam IStoveSetStatParam;
// To access members, use the access functions listed in the member table below.

Members

NameTypeRequiredAccessAccessorDescription
StatsIdconst wchar_t*YesReading and WritingStove_IStoveSetStatParam_GetStatsId() / SetStatsId()This is the ID of the statistic to be edited. Format: [A-Z0-9\-_]*$ (uppercase letters, numbers, underscores, hyphens)
StatValueint32_tYesReading and WritingStove_IStoveSetStatParam_GetStatValue() / SetStatValue()This is the new value to be applied to the statistic. It does not represent an increment added to the existing value; rather, it replaces (sets) the statistic value with this value.

Memory Management

ItemValue
Creating EntityCaller (Stove_CreateParam(k_EStoveGameSupportTypeKind_SetStatParam))
Responsibility for DismantlingCaller (Destroy() required)

Example

c
IStoveSetStatParam* param =
    (IStoveSetStatParam*)Stove_CreateParam(k_EStoveGameSupportTypeKind_SetStatParam);
Stove_IStoveSetStatParam_SetStatsId(param, L"KILL_COUNT");
Stove_IStoveSetStatParam_SetStatValue(param, 42);

Stove_SetStat(param, OnSetStatFinished, NULL);

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param);

Notes

  • You must configure both StatsId and StatValue to be able to submit edit requests properly.
  • StatValue is not an increment or decrement operation, but a set (or replace) operation. To accumulate the value, you must first retrieve the current value and then pass the sum of that value and the new value.
  • The processing result (whether the operation was successful and the updated value) is passed as an argument to the IStoveSetStatOutcome callback.

See Also


IStoveShopCategory

Kind Struct · Module IAP · Version 3.5.0

Description

Represents a single item in the store category tree. It is returned by the Stove_FetchShopCategories call, stored in IStoveShopCategoryList, and passed to the OnFetchShopCategoriesCallback callback.

This is a data type that the SDK populates and passes via a callback. The caller does not create it directly.

The list and each item passed to the callback are owned by the SDK and are no longer valid once the callback call ends. Do not call Destroy(); instead, copy any values that need to be preserved within the callback.

Declaration

c
typedef struct IStoveShopCategory IStoveShopCategory;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
CategoryIdconst wchar_t*ReadStove_IStoveShopCategory_GetCategoryId()Category Identifier
CategoryParentIdconst wchar_t*ReadStove_IStoveShopCategory_GetCategoryParentId()Parent category identifier. The top-level category is empty.
CategoryDisplayNoint32_tReadStove_IStoveShopCategory_GetCategoryDisplayNo()Display Order Within the Same Tier
CategoryNameconst wchar_t*ReadStove_IStoveShopCategory_GetCategoryName()Localized category names
CategoryDepthint32_tReadStove_IStoveShopCategory_GetCategoryDepth()Depth in the category tree (0 = top level)

Memory Management

ItemValue
Creating EntitySDK
Responsibility for DismantlingSDK (Do Not Unlock, Invalid Once Callback Completes)

Example

c
void __cdecl OnFetchShopCategoriesCallback(const IStoveCallbackResult* callbackResult, const IStoveShopCategoryList* list)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

    if (Stove_IStoveResult_GetResultCode(result) == 0)
    {
        uint32_t count = Stove_IStoveShopCategoryList_GetCount(list);

        for (uint32_t i = 0; i < count; ++i)
        {
            const IStoveShopCategory* category = Stove_IStoveShopCategoryList_GetAt(list, i);

            const wchar_t* categoryId = Stove_IStoveShopCategory_GetCategoryId(category);
            const wchar_t* categoryName = Stove_IStoveShopCategory_GetCategoryName(category);
            int32_t depth = Stove_IStoveShopCategory_GetCategoryDepth(category);

            // Please copy and save only the values you need.
        }
        // The list and its items will be invalidated once this callback finishes. Do not call Destroy().
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

Notes

  • It is passed only as the output of Stove_FetchShopCategories.
  • If CategoryParentId is empty, this is the top-level category.
  • IStoveProduct's CategoryId and CategoryName correspond to this entry.

See Also


IStoveShopCategoryList

Kind Struct · Module IAP · Version 3.5.0

Description

OnFetchShopCategoriesCallback is the container passed to the callback. It wraps the Stove_FetchShopCategories array returned by IStoveShopCategory.

This is a data type that the SDK populates and passes via a callback. The caller does not create it directly.

This object and each item obtained via GetAt() are owned by the SDK and are no longer valid once the callback completes. Do not call Destroy(); instead, copy any values you need to preserve within the callback.

Declaration

c
typedef struct IStoveShopCategoryList IStoveShopCategoryList;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
Countuint32_tReadStove_IStoveShopCategoryList_GetCount()Number of store categories included in the results
At(index)const IStoveShopCategory*ReadStove_IStoveShopCategoryList_GetAt()The store category at position index (starting from 0). If the value is index >= Count, it returns nullptr.

Memory Management

ItemValue
CreatorSDK
Responsibility for DismantlingSDK (Do Not Unlock, Invalid Once Callback Completes)

Example

c
void __cdecl OnFetchShopCategoriesCallback(const IStoveCallbackResult* callbackResult, const IStoveShopCategoryList* list)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

    if (Stove_IStoveResult_GetResultCode(result) == 0)
    {
        uint32_t count = Stove_IStoveShopCategoryList_GetCount(list);
        for (uint32_t i = 0; i < count; ++i)
        {
            const IStoveShopCategory* category = Stove_IStoveShopCategoryList_GetAt(list, i);
            // Please copy and save only the values you need.
        }
        // The list and its individual items will be invalidated once this callback completes. Do not call Destroy().
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

Notes

  • It is passed only as the output of Stove_FetchShopCategories.
  • Previously, the array and count were passed as separate callback arguments, but now they are wrapped together and passed as a single container.

See Also


IStoveShutdownInfo

Kind Struct · Module Base · Version 3.5.0

Description

Stove_ShutdownNotification() This is the shutdown notice information passed to the callback.

Contains the shutdown notification message, the message display duration, and the time remaining until shutdown. It is created by the SDK and passed only as a callback argument; the caller does not release it.

If your account has been suspended, this notification will appear both in Korea and overseas.

Declaration

c
typedef struct IStoveShutdownInfo IStoveShutdownInfo;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
Msgconst wchar_t*ReadStove_IStoveShutdownInfo_GetMsg()This is a shutdown notification message.
ExposureTimeint32_tReadStove_IStoveShutdownInfo_GetExposureTime()This is the shutdown message display time (in seconds).
InadvanceMinutesint32_tReadStove_IStoveShutdownInfo_GetInadvanceMinutes()This is the time remaining (in minutes) until the user's session is shut down.

Memory Management

ItemValue
Creating EntitySDK
Responsibility for DismantlingSDK, Passed only as a callback argument and invalidated once the callback completes. The caller does not call Destroy().

Example

c
void __cdecl OnShutdownNotificationCallback(const IStoveCallbackResult* callbackResult, const IStoveShutdownInfo* shutdown)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

    if (Stove_IStoveResult_GetResultCode(result) == k_EStoveCommonResultCode_Success)
    {
        const wchar_t* msg = Stove_IStoveShutdownInfo_GetMsg(shutdown);
        int32_t inadvanceMinutes = Stove_IStoveShutdownInfo_GetInadvanceMinutes(shutdown);
        // Please implement the logic for a successful outcome. (Display a shutdown notice)
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }

    // shutdown does not call Destroy().
}

Notes

  • ShutdownNotification is not limited to South Korea. It works overseas as well, even for accounts subject to a shutdown.
  • This callback is not a one-time event. It is called once at each of the pre-notification times provided by the server (e.g., 30 minutes before shutdown, 10 minutes before shutdown, etc.), and once more when the actual shutdown time arrives.

See Also


IStoveSignin

Kind Struct · Module Base · Version 3.5.0

Description

This is the structure containing the login credentials passed when calling Stove_GetSignin().

This contains information on whether user authentication and email verification have been completed, the country of registration, and the authentication method (IDP) used during registration. The SDK creates this and returns it as the out parameter of Stove_GetSignin(), and the caller releases it via Destroy() after use.

Declaration

c
typedef struct IStoveSignin IStoveSignin;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
IsPersonVerifiedboolReadStove_IStoveSignin_IsPersonVerified()This indicates whether the user has completed identity verification.
IsEmailVerifiedboolReadStove_IStoveSignin_IsEmailVerified()This indicates whether the user has completed email verification.
RegisteredCountryCodeconst wchar_t*ReadStove_IStoveSignin_GetRegisteredCountryCode()This is the country code for the Stove platform (ISO 3166-1 ALPHA-2).
ProviderCodeconst wchar_t*ReadStove_IStoveSignin_GetProviderCode()This is an IDP classification code (string) that indicates the authentication method used to log in to Stove. Examples: SO (Stove email), FB (Facebook), GP (Google), STEAM, VTCO, etc.
AccountTypeint32_tReadStove_IStoveSignin_GetAccountType()This is the account type code (numeric, server-managed). Examples: 2=Facebook, 3=Twitter, 6=Naver, 9=Google+, 11=Stove PC registration, 12=Apple, 13=LINE, 14=LINE Games, 15=Steam, 16=VTCO, etc. Since the value-to-meaning mapping is not fixed by any public standard, please refer to ProviderCode instead to identify the IDP/account type (e.g., STEAM vs. STEAM_SHADOW).

Memory Management

ItemValue
Creating EntitySDK (passed as an out parameter to Stove_GetSignin())
Responsibility for DismantlingCaller (Destroy() required)

Example

c
IStoveSignin* signin = NULL;
IStoveResult* result = Stove_GetSignin(&signin);

if (Stove_IStoveResult_GetResultCode(result) == k_EStoveCommonResultCode_Success)
{
    bool personVerified = Stove_IStoveSignin_IsPersonVerified(signin);
    const wchar_t* providerCode = Stove_IStoveSignin_GetProviderCode(signin);
    // Please implement the logic for a successful outcome.

    Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)signin);
}
else
{
    // Please implement the logic for when a failure occurs.
}

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result);

Notes

  • You must call this after initialization with Stove_Initialize() to receive a valid value.
  • AccountType is a numeric code, and ProviderCode is a string code; they represent the same authentication method using different notations. Use ProviderCode when you need to precisely identify the IDP or account type.

See Also


IStoveStartPurchaseOutcome

Kind Struct · Module IAP · Version 3.5.0

Description

This represents the result of the Stove_StartPurchase call. It is passed to the OnStartPurchaseCallback callback. Which fields are populated depends on the value of Operation in IStovePurchaseParam.

  • Operation If this is Default, TempPaymentUrl will be filled in for manual payment processing.
  • Operation If this is WithWebViewAndConfirmResult, then IsPurchased, PurchasedProduct*, and ChargeInfo* will be populated when the payment is successful.

This is a data type that the SDK populates and passes via a callback. The caller does not create it directly.

The array referenced by TxnDetailNos and the items obtained via PurchasedProductAt() / ChargeInfoAt() are all owned by the SDK and are no longer valid once the callback completes. Do not call Destroy(); instead, copy any values you need to preserve within the callback.

Declaration

c
typedef struct IStoveStartPurchaseOutcome IStoveStartPurchaseOutcome;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
TxnMasterNoint64_tReadStove_IStoveStartPurchaseOutcome_GetTxnMasterNo()Transaction Master Number (TID per purchase)
TxnDetailNosconst int64_t*ReadStove_IStoveStartPurchaseOutcome_GetTxnDetailNos()A pointer to the array of transaction detail numbers by product. It is owned by the SDK and is invalidated once the callback completes.
TxnDetailNosCountuint32_tReadStove_IStoveStartPurchaseOutcome_GetTxnDetailNosCount()The number of elements in the array pointed to by TxnDetailNos
TempPaymentUrlconst wchar_t*ReadStove_IStoveStartPurchaseOutcome_GetTempPaymentUrl()A one-time payment URL. Provided when Operation == Default.
PurchaseProgressEStovePurchaseProgressReadStove_IStoveStartPurchaseOutcome_GetPurchaseProgress()Purchase Status
IsPurchasedboolReadStove_IStoveStartPurchaseOutcome_IsPurchased()Operation == WithWebViewAndConfirmResult, and if the payment was successfully completed, true. Otherwise, false.
ExtraDataconst wchar_t*ReadStove_IStoveStartPurchaseOutcome_GetExtraData()Echo of the ExtraData string passed when calling Stove_StartPurchase
PurchasedProductCountuint32_tReadStove_IStoveStartPurchaseOutcome_GetPurchasedProductCount()Number of items purchased. Operation == WithWebViewAndConfirmResult; this field is populated when the payment is successful.
PurchasedProductAt(index)const IStovePurchasedProduct*ReadStove_IStoveStartPurchaseOutcome_GetPurchasedProductAt()The purchased item at position index (starting from 0). If it is index >= PurchasedProductCount, it returns nullptr.
ChargeInfoCountuint32_tReadStove_IStoveStartPurchaseOutcome_GetChargeInfoCount()The number of "charge-info" entries describing the currency used for the payment
ChargeInfoAt(index)const IStoveChargeInfo*ReadStove_IStoveStartPurchaseOutcome_GetChargeInfoAt()The "charge-info" entry at position index (starting from 0). If the value is index >= ChargeInfoCount, it returns nullptr.

Memory Management

ItemValue
Creating EntitySDK
Responsibility for DismantlingSDK (Do Not Unlock, Invalid once the callback is complete)

Example

c
void __cdecl OnStartPurchaseCallback(const IStoveCallbackResult* callbackResult, const IStoveStartPurchaseOutcome* outcome)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

    if (Stove_IStoveResult_GetResultCode(result) == 0)
    {
        int32_t progress = Stove_IStoveStartPurchaseOutcome_GetPurchaseProgress(outcome);

        if (progress == k_EStovePurchaseProgress_NeedPaymentWindow)
        {
            const wchar_t* paymentUrl = Stove_IStoveStartPurchaseOutcome_GetTempPaymentUrl(outcome);
            // Please open the `paymentUrl` to proceed with the payment, and then call `Stove_ConfirmPurchase()`.
        }
        else if (Stove_IStoveStartPurchaseOutcome_IsPurchased(outcome))
        {
            uint32_t productCount = Stove_IStoveStartPurchaseOutcome_GetPurchasedProductCount(outcome);
            for (uint32_t i = 0; i < productCount; ++i)
            {
                const IStovePurchasedProduct* product = Stove_IStoveStartPurchaseOutcome_GetPurchasedProductAt(outcome, i);
                // Please copy and save only the values you need.
            }
        }
        // The `outcome` and the arrays/items it contains will be invalidated once this callback finishes. Do not call `Destroy()`.
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

Notes

  • It is passed only as the output of Stove_StartPurchase.
  • If PurchaseProgress is NeedPaymentWindow, open the payment window at TempPaymentUrl, and after completing payment, confirm the purchase at Stove_ConfirmPurchase.
  • ExtraData returns the ExtraData of IStoveStartPurchaseParam as-is.
  • The old name for this type is IStovePurchaseResult (TypeKind old name: PurchaseResult). Please keep this in mind when migrating legacy integrations.

See Also


IStoveStartPurchaseParam

Kind Struct · Module IAP · Version 3.5.0

Description

These are the input parameters passed when calling Stove_StartPurchase. They contain both the list of items to purchase (IStoveOrderProductParam) and the purchase action options (IStovePurchaseParam).

Create it as Stove_CreateParam(k_EStoveIAPTypeKind_StartPurchaseParam), set its value using the setter, and then release it as Destroy() once the call is complete.

Declaration

c
typedef struct IStoveStartPurchaseParam IStoveStartPurchaseParam;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessRequiredAccessorDescription
Productsconst IStoveOrderProductParam* const* / IStoveOrderProductParam**Reading and WritingYesStove_IStoveStartPurchaseParam_GetProducts() / Stove_IStoveStartPurchaseParam_SetProducts()Arrangement of Order Items by Product to Be Purchased
ProductsCountuint32_tRead,Stove_IStoveStartPurchaseParam_GetProductsCount()Products The number of elements in the array. It is specified when SetProducts() is called.
PurchaseParamconst IStovePurchaseParam* / IStovePurchaseParam*Reading and WritingYesStove_IStoveStartPurchaseParam_GetPurchaseParam() / Stove_IStoveStartPurchaseParam_SetPurchaseParam()Purchase Behavior Options (Including Web View Placement)
ServiceTxnNoconst wchar_t*Reading and WritingNoStove_IStoveStartPurchaseParam_GetServiceTxnNo() / Stove_IStoveStartPurchaseParam_SetServiceTxnNo()Service-side transaction number issued by the game (optional)
ExtraDataconst wchar_t*Reading and WritingNoStove_IStoveStartPurchaseParam_GetExtraData() / Stove_IStoveStartPurchaseParam_SetExtraData()Additional request data (typically a JSON string; optional). It is returned as-is from IStoveStartPurchaseOutcome to ExtraData.

Memory Management

ItemValue
Creating EntityCaller (Stove_CreateParam(k_EStoveIAPTypeKind_StartPurchaseParam))
Responsibility for DismantlingCaller (Destroy() required)

Example

c
IStoveOrderProductParam* orderProduct = (IStoveOrderProductParam*)Stove_CreateParam(k_EStoveIAPTypeKind_OrderProductParam);
Stove_IStoveOrderProductParam_SetProductId(orderProduct, productId);
Stove_IStoveOrderProductParam_SetSalePrice(orderProduct, salePrice);
Stove_IStoveOrderProductParam_SetQuantity(orderProduct, 1);

IStovePurchaseParam* purchaseParam = (IStovePurchaseParam*)Stove_CreateParam(k_EStoveIAPTypeKind_PurchaseParam);
Stove_IStovePurchaseParam_SetOperation(purchaseParam, k_EStovePurchaseOperation_WithWebViewAndConfirmResult);

IStoveStartPurchaseParam* startPurchaseParam = (IStoveStartPurchaseParam*)Stove_CreateParam(k_EStoveIAPTypeKind_StartPurchaseParam);

IStoveOrderProductParam* orderProducts[] = { orderProduct };
Stove_IStoveStartPurchaseParam_SetProducts(startPurchaseParam, orderProducts, 1);
Stove_IStoveStartPurchaseParam_SetPurchaseParam(startPurchaseParam, purchaseParam);
Stove_IStoveStartPurchaseParam_SetExtraData(startPurchaseParam, L"{\"orderFrom\":\"shop\"}");

Stove_StartPurchase(startPurchaseParam, OnStartPurchaseCallback, NULL, NULL, NULL);

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)startPurchaseParam);
Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)purchaseParam);
Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)orderProduct);

Notes

  • SetProducts() and SetPurchaseParam() do not acquire ownership. The caller retains ownership of the passed IStoveOrderProductParam and IStovePurchaseParam objects and can call Destroy() directly on each of them at any time after Stove_StartPurchase() is returned. Since Stove_StartPurchase() synchronously copies all necessary values from these child objects before the call returns, these objects are not referenced while the asynchronous callback is executing.
  • Destroy() does not release the subobjects (Products, PurchaseParam) that make up this parameter. Each object must be released individually.

See Also


IStoveStat

Kind Struct · Module GameSupport · Version 3.5.0

Description

IStoveStat is a type that contains the result information returned when a statistics (Stat) query API call succeeds. It is passed as the onFinished callback (OnGetStatCallback) argument of Stove_FetchStat.

This type is created by the SDK and passed via a callback; it is not created directly by the caller.

Declaration

c
typedef struct IStoveStat IStoveStat;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
StatsFullIdconst IStoveStatFullId*ReadStove_IStoveStat_GetStatsFullId()This is the complete set of identifying information for the statistics.
UpdatedAtuint64_tReadStove_IStoveStat_GetUpdatedAt()This is the last update time (epoch time, in milliseconds).
CurrentValueint32_tReadStove_IStoveStat_GetCurrentValue()This is the current value of the statistic.

Memory Management

ItemValue
Creating EntitySDK
Responsibility for DismantlingSDK (Do not disable. It will be invalidated once the Stove_FetchStat callback completes)

Example

c
void OnGetStatFinished(const IStoveCallbackResult* callbackResult, const IStoveStat* stat)
{
    if (Stove_IStoveResult_GetResultCode(Stove_IStoveCallbackResult_GetResult(callbackResult)) == 0 && stat != NULL)
    {
        int32_t currentValue = Stove_IStoveStat_GetCurrentValue(stat);
        uint64_t updatedAt = Stove_IStoveStat_GetUpdatedAt(stat);

        // Please implement the logic for a successful outcome.
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

Notes

  • It is not created directly by the caller and can only be obtained through the Stove_FetchStat callback.
  • The IStoveStatFullId obtained via StatsFullId is also invalidated along with this object once the callback completes.

See Also


IStoveStatFullId

Kind Struct · Module GameSupport · Version 3.5.0

Description

IStoveStatFullId is a type that contains information that fully identifies a single statistic (Stat). It is included in IStoveStat, the result of query Stove_FetchStat, and is passed along.

This type is created by the SDK and passed via a callback; it is not created directly by the caller.

Declaration

c
typedef struct IStoveStatFullId IStoveStatFullId;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
GameIdconst wchar_t*ReadStove_IStoveStatFullId_GetGameId()This is the game ID associated with these statistics.
StatsIdconst wchar_t*ReadStove_IStoveStatFullId_GetStatsId()This is a statistics ID. Format: [A-Z0-9\-_]*$ (uppercase letters, numbers, underscores, hyphens)

Memory Management

ItemValue
Creating EntitySDK (passed as part of the IStoveStat callback argument)
Responsibility for DismantlingSDK (Do not release. If the IStoveStat callback parameter containing this object is invalidated, this object will also be invalidated.)

Example

c
void OnGetStatFinished(const IStoveCallbackResult* callbackResult, const IStoveStat* stat)
{
    if (Stove_IStoveResult_GetResultCode(Stove_IStoveCallbackResult_GetResult(callbackResult)) == 0 && stat != NULL)
    {
        const IStoveStatFullId* fullId = Stove_IStoveStat_GetStatsFullId(stat);
        const wchar_t* statsId = Stove_IStoveStatFullId_GetStatsId(fullId);

        // Please implement the logic for a successful outcome.
    }
}

Notes

  • It is not created directly by the caller and can only be obtained through IStoveStat.
  • The StatsId format follows the same rules as the StatsId in IStoveFetchStatParam, which is used when requesting statistics.

See Also


IStoveTermsAgreementOutcome

Kind Struct · Module IAP · Version 3.5.0

Description

Displays the result of call Stove_FetchTermsAgreement. It is passed to the callback OnFetchTermsAgreementCallback.

This is a data type that the SDK populates and passes via a callback. It is not created directly by the caller.

This object belongs to the SDK and is no longer valid once the callback call has finished. Do not call Destroy(); instead, copy any values that need to be retained within the callback.

Declaration

c
typedef struct IStoveTermsAgreementOutcome IStoveTermsAgreementOutcome;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
IsAgreedboolReadStove_IStoveTermsAgreementOutcome_IsAgreed()Whether the user has already agreed to the latest Terms of Service. If true is true, Url is an empty string.
Urlconst wchar_t*ReadStove_IStoveTermsAgreementOutcome_GetUrl()The URL of the Terms and Conditions page that the caller must open (or has already opened in a WebView). If IsAgreed is true, this field is empty.

Memory Management

ItemValue
Creating EntitySDK
Responsibility for DismantlingSDK (Do Not Unlock, Invalid Once Callback Completes)

Example

c
void __cdecl OnFetchTermsAgreementCallback(const IStoveCallbackResult* callbackResult, const IStoveTermsAgreementOutcome* outcome)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

    if (Stove_IStoveResult_GetResultCode(result) == 0)
    {
        if (!Stove_IStoveTermsAgreementOutcome_IsAgreed(outcome))
        {
            const wchar_t* url = Stove_IStoveTermsAgreementOutcome_GetUrl(outcome);
            // If Operation == Default, please open the Terms and Conditions page directly via the URL.
        }
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

Notes

See Also


IStoveTypeBase

Kind Struct · Module Base · Version 3.5.0

Description

This is the root interface inherited by all SDK-owned objects that are passed across DLL boundaries. It provides runtime type identification (GetTypeKind()) and an explicit Destroy() deallocation mechanism.

Not only IStoveResult and IStoveUser, but all object types handled by the SDK, including payment, ownership, statistics, achievements, popups, PC Bang, and logs, inherit from this interface. Objects are never created directly; instead, this interface defines the common behavior of objects returned by other APIs or passed via callbacks. The responsibility for releasing each instance is handled by ShouldDestroy().

Instances (such as objects passed as callback arguments) where ShouldDestroy() returns false must not call Destroy().

Declaration

c
typedef struct IStoveTypeBase IStoveTypeBase;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
TypeKindint32_tReadStove_IStoveTypeBase_GetTypeKind()Returns the concrete type type (one of the EStoveBaseTypeKind values).
ShouldDestroyboolReadStove_IStoveTypeBase_ShouldDestroy()This determines whether the caller is responsible for calling Destroy() on this instance. If true, the caller owns the instance (e.g., return values), so Destroy() must be called exactly once after use; if false, the SDK manages the instance’s lifecycle (e.g., callback parameters), so Destroy() must not be called.
,voidDongjakStove_IStoveTypeBase_Destroy() (Non-const)Releases the object. This method must be called exactly once for each instance it owns.
QueryExtvoid*ReadStove_IStoveTypeBase_QueryExt(extId)Returns an extension interface pointer (nullptr if none exists). extId range: 0=reserved, 1–0xFFFF=range reserved for future extensions of this root interface itself, 0x10000 and above=extension ID ranges defined by individual functions such as billing, ownership, and statistics. Since there are currently no registered extensions in the SDK, it always returns nullptr regardless of the extId value passed.

Memory Management

ItemValue
Creating EntityIt depends on the subtype, either the result or data type returned or passed by the SDK, or the parameter type created by the caller using Stove_CreateParam().
Responsibility for DismantlingInstances for which ShouldDestroy() returns true call Destroy(). Instances passed as callback arguments are those for which ShouldDestroy() returns false and are not released.

Example

c
IStoveResult* result = Stove_Uninitialize();

if (Stove_IStoveTypeBase_ShouldDestroy((IStoveTypeBase*)result))
{
    Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result);
}

Notes

  • Not only IStoveResult, IStoveUser, and IStoveGds, but all object types handled by the SDK, including payment, ownership, statistics and achievements, pop-ups, PC Bang, and logs, inherit from this interface. This includes, without exception, any other structures not covered in this document.
  • QueryExt() is a reserved function that always returns nullptr, regardless of the extId passed to it, since no extensions have actually been registered for it yet.
  • Since the instances passed as callback arguments (such as IStoveCallbackResult and IStoveAccessToken) are invalidated once the callback ends, Destroy() is not called.

See Also


IStoveUser

Kind Struct · Module Base · Version 3.5.0

Description

This is the user information structure passed when calling Stove_GetUser().

Contains the nickname and game user ID of the user logged in via the launcher. The SDK creates this and returns it as the out parameter of Stove_GetUser(); the caller releases it via Destroy() after use.

Declaration

c
typedef struct IStoveUser IStoveUser;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
NickNameconst wchar_t*ReadStove_IStoveUser_GetNickName()This is the Stove nickname of the user logged in to the launcher.
UserIduint64_tReadStove_IStoveUser_GetUserId()This is the GameUserId of the user logged in to the launcher.

Memory Management

ItemValue
Creating EntitySDK (passed as an out parameter to Stove_GetUser())
Responsibility for DismantlingCaller (Destroy() required)

Example

c
IStoveUser* user = NULL;
IStoveResult* result = Stove_GetUser(&user);

if (Stove_IStoveResult_GetResultCode(result) == k_EStoveCommonResultCode_Success)
{
    const wchar_t* nickName = Stove_IStoveUser_GetNickName(user);
    uint64_t userId = Stove_IStoveUser_GetUserId(user);
    // Please implement the logic for a successful outcome.

    Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)user);
}
else
{
    // Please implement the logic for when an error occurs.
}

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result);

Notes

  • You must call this function after initialization with Stove_Initialize() to receive a valid value.

See Also


IStoveVietnamAgeRatingInfo

Kind Struct · Module Base · Version 3.5.0

Description

Stove_VietnamAgeRatingNotification() This is the age rating notification overlay information passed via callback. This API is for Vietnam only.

Contains the overlay's display status, shape, size/position, game age rating, and notification message. It is created by the SDK and passed only as a callback argument; the caller does not release it.

Since this is a one-time callback, it must be called after rendering is complete.

Declaration

c
typedef struct IStoveVietnamAgeRatingInfo IStoveVietnamAgeRatingInfo;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
OverlayModeint32_tReadStove_IStoveVietnamAgeRatingInfo_GetOverlayMode()The overlay is currently displayed (SHOW: Show overlay, HIDE: Hide overlay). The value is EStoveOverlayMode.
OverlayTypeint32_tReadStove_IStoveVietnamAgeRatingInfo_GetOverlayType()This is the overlay type (0=Black: white text on a dark background (RGB(33,33,33)), 1=White: black text on a white background (RGB(255,255,255)); the default is White).
OverlayScalefloatReadStove_IStoveVietnamAgeRatingInfo_GetOverlayScale()This is the overlay scale (0.0 to 1.0).
OverlayOpacityfloatReadStove_IStoveVietnamAgeRatingInfo_GetOverlayOpacity()This is the overlay opacity (0.0 to 1.0).
AgeRatingint32_tReadStove_IStoveVietnamAgeRatingInfo_GetAgeRating()These are the game age ratings (0 = All Ages, 12 = Ages 12 and up, 16 = Ages 16 and up, 18 = Ages 18 and up).
Msgconst wchar_t*ReadStove_IStoveVietnamAgeRatingInfo_GetMsg()This is an age rating notification message.
DisplayPositionXfloatReadStove_IStoveVietnamAgeRatingInfo_GetDisplayPositionX()The x-coordinate of the message display location. Measured from the left edge of the screen (0.0 to 1.0).
DisplayPositionYfloatReadStove_IStoveVietnamAgeRatingInfo_GetDisplayPositionY()The y-coordinate of the message's display position. Relative to the top of the screen (0.0 to 1.0).
Languageconst wchar_t*ReadStove_IStoveVietnamAgeRatingInfo_GetLanguage()These are language codes for selecting fonts (e.g., L"ko", L"en", L"ja", L"vi", L"zh-cn", L"zh-tw", L"th").

Memory Management

ItemValue
Creating EntitySDK
Responsibility for DismantlingSDK, Passed only as a callback argument and invalidated once the callback completes. The caller does not call Destroy().

Example

c
void __cdecl OnVietnamAgeRatingNotificationCallback(const IStoveCallbackResult* callbackResult, const IStoveVietnamAgeRatingInfo* ageRatingInfo)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

    if (Stove_IStoveResult_GetResultCode(result) == k_EStoveCommonResultCode_Success)
    {
        int32_t overlayMode = Stove_IStoveVietnamAgeRatingInfo_GetOverlayMode(ageRatingInfo);
        const wchar_t* msg = Stove_IStoveVietnamAgeRatingInfo_GetMsg(ageRatingInfo);
        // Please implement the logic for when the operation is successful. (Show/hide the overlay based on `overlayMode`.)
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }

    // ageRatingInfo does not call Destroy().
}

Notes

  • This is an API specific to Vietnam, and since it is a one-time callback, it must be called after rendering is complete.
  • OverlayMode uses the value of EStoveOverlayMode.

See Also


IStoveVietnamOverimmersionInfo

Kind Struct · Module Base · Version 3.5.0

Description

Stove_VietnamOverimmersionNotification() This is the information for the anti-excessive-use notification overlay passed via callback. This API is exclusive to Vietnam.

Contains the overlay display status, shape, size/position, game age rating, and warning messages (general/styled). It is created by the SDK and passed only as a callback argument; the caller does not release it.

Since this is a one-time callback, it must be called after rendering is complete.

Declaration

c
typedef struct IStoveVietnamOverimmersionInfo IStoveVietnamOverimmersionInfo;
// To access members, use the access functions listed in the member table below.

Members

NameTypeAccessAccessorDescription
OverlayModeint32_tReadStove_IStoveVietnamOverimmersionInfo_GetOverlayMode()The overlay is currently displayed (SHOW: Show overlay, HIDE: Hide overlay). The value is EStoveOverlayMode.
OverlayTypeint32_tReadStove_IStoveVietnamOverimmersionInfo_GetOverlayType()This is the overlay type (0=Black: white text on a dark background (RGB(33,33,33)), 1=White: black text on a white background (RGB(255,255,255)); the default is White).
OverlayScalefloatReadStove_IStoveVietnamOverimmersionInfo_GetOverlayScale()This is the overlay scale (0.0–1.0).
OverlayOpacityfloatReadStove_IStoveVietnamOverimmersionInfo_GetOverlayOpacity()This is the overlay opacity (0.0 to 1.0).
AgeRatingint32_tReadStove_IStoveVietnamOverimmersionInfo_GetAgeRating()These are the game age ratings (0 = All Ages, 12 = Ages 12 and up, 16 = Ages 16 and up, 18 = Ages 18 and up).
Msgconst wchar_t*ReadStove_IStoveVietnamOverimmersionInfo_GetMsg()This is a warning about excessive engagement.
StyledMsgconst wchar_t*ReadStove_IStoveVietnamOverimmersionInfo_GetStyledMsg()This is a style (translation) warning message containing markup tags such as <b> and <color=#RRGGBBAA>. It is used for rich text rendering.
ElapsedMinutesint32_tReadStove_IStoveVietnamOverimmersionInfo_GetElapsedMinutes()This is the cumulative game play time (in minutes).
ExposureTimeint32_tReadStove_IStoveVietnamOverimmersionInfo_GetExposureTime()This is the message display time (in seconds).
ExpandAnimationTimefloatReadStove_IStoveVietnamOverimmersionInfo_GetExpandAnimationTime()This is the duration (in seconds) of the animation in which the overlay expands when switching between "Show" and "Expand."
DisplayPositionXfloatReadStove_IStoveVietnamOverimmersionInfo_GetDisplayPositionX()The x-coordinate of the message's display position. Measured from the left edge of the screen (0.0 to 1.0).
DisplayPositionYfloatReadStove_IStoveVietnamOverimmersionInfo_GetDisplayPositionY()The y-coordinate of the message's display position. Relative to the top of the screen (0.0 to 1.0).
Languageconst wchar_t*ReadStove_IStoveVietnamOverimmersionInfo_GetLanguage()These are language codes for selecting fonts (e.g., L"ko", L"en", L"ja", L"vi", L"zh-cn", L"zh-tw", L"th").

Memory Management

ItemValue
Creating EntitySDK
Responsibility for DismantlingSDK, Passed only as a callback argument and invalidated once the callback completes. The caller does not call Destroy().

Example

c
void __cdecl OnVietnamOverimmersionNotificationCallback(const IStoveCallbackResult* callbackResult, const IStoveVietnamOverimmersionInfo* overimmersionInfo)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

    if (Stove_IStoveResult_GetResultCode(result) == k_EStoveCommonResultCode_Success)
    {
        int32_t overlayMode = Stove_IStoveVietnamOverimmersionInfo_GetOverlayMode(overimmersionInfo);
        const wchar_t* styledMsg = Stove_IStoveVietnamOverimmersionInfo_GetStyledMsg(overimmersionInfo);
        // Please implement the logic for when the operation succeeds. (Show/hide/expand the overlay based on `overlayMode`.)
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }

    // `overimmersionInfo` does not call `Destroy()`.
}

Notes

  • This is an API specific to Vietnam, and since it is a one-time callback, it must be called after rendering is complete.
  • OverlayMode uses the value EStoveOverlayMode and also supports k_EStoveOverlayMode_Expanded (expanded display).
  • ElapsedMinutes is the unit "minute." Be careful not to confuse it with ElapsedHours, which is the unit "hour" (IStoveOverImmersionInfo).

See Also


IStoveWebViewLayoutParam

Kind Struct · Module IAP · Version 3.5.0

Description

IStovePurchaseParam, IStoveFetchTermsAgreementParam, and IStoveWithdrawGameParam are a set of WebView layout fields that these three parameter types all inherit.

This type cannot be created on its own as Stove_CreateParam() (there is no corresponding EStoveIAPTypeKind value). It always exists only as a base of one of the three concrete type types listed above, and when reading or writing its value, you must use the respective flat access functions (e.g., Stove_IStovePurchaseParam_GetWebViewMode()) of concrete type. There are no access functions of the Stove_IStoveWebViewLayoutParam_* type.

Declaration

c
// This is an abstract shared base class. It is not intended for standalone `typedef`s or as a target for `Stove_CreateParam()`.
// For actual usage, please refer to the concrete type document below.

Members

NameTypeDescription
WebViewModeEStoveWebViewModeWebView Display Mode (External Browser / SDK-Embedded WebView)
WebViewPosXint32_tWebView x-coordinate (pixels)
WebViewPosYint32_tWebView y-coordinate (pixels)
WebViewWidthint32_tWeb View Width (pixels)
WebViewHeightint32_tWebView Height (pixels)

For information on whether these members are accessible or required, please refer to the member tables in the concrete type documents (IStovePurchaseParam, IStoveFetchTermsAgreementParam, IStoveWithdrawGameParam) that are actually in use.

Memory Management

This type is not created or deleted on its own. It is always created and deleted as part of concrete type (IStovePurchaseParam, etc.). For instructions on how to delete it, please refer to the respective concrete type documents.

Example

c
// Do not create an `IStoveWebViewLayoutParam` directly.
// Use the fields inherited via concrete type as shown below.
IStovePurchaseParam* purchaseParam = (IStovePurchaseParam*)Stove_CreateParam(k_EStoveIAPTypeKind_PurchaseParam);
Stove_IStovePurchaseParam_SetWebViewMode(purchaseParam, k_EStoveWebViewMode_Internal);
Stove_IStovePurchaseParam_SetWebViewWidth(purchaseParam, 480);
Stove_IStovePurchaseParam_SetWebViewHeight(purchaseParam, 640);

Notes

  • In IStovePurchaseParam and IStoveFetchTermsAgreementParam, these fields apply only when the Operation value for each type is not Default.
  • Since IStoveWithdrawGameParam does not contain Operation, these fields always apply.

See Also


Stove_AccessTokenRenewed

Kind Function · Module Base · Version 3.5.0

Description

When the AccessToken is renewed, the newly issued token is passed via a callback. This is used when specific actions are required at the time the token is renewed.

Declaration

c
void Stove_AccessTokenRenewed(const IStoveTypeBase* param, OnAccessTokenRenewedCallback onFinished, void* userData);

Parameters

NameTypeRequiredDescription
paramconst IStoveTypeBase*NThe reserved argument ...Param TypeKind is not defined.
onFinishedOnAccessTokenRenewedCallbackYThis is the callback that will receive the results.
userDatavoid*NThis is the user data that is passed directly to the callback.

Returns

None

The method code for this function is k_EStoveBaseMethodCode_AccessTokenRenewed.

Callback

c
typedef void(__cdecl* OnAccessTokenRenewedCallback)(const IStoveCallbackResult* callbackResult, const IStoveAccessToken* token);
NameTypeDescription
callbackResultconst IStoveCallbackResult*Here are the results of the call.
tokenconst IStoveAccessToken*Here is the information on the newly issued tokens. Look them up using Stove_IStoveAccessToken_GetAccessToken() and Stove_IStoveAccessToken_GetExpireIn().

The callback runs in the thread that called Stove_RunCallback(). It is passed repeatedly each time the AccessToken is renewed.

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
5k_EStoveCommonResultCode_InvalidParamonFinished is nullptr.x
16k_EStoveCommonResultCode_BaseNotInitializedIt was called before being initialized.x
253k_EStoveCommonResultCode_UnmanagedExceptionAn unknown exception occurred during execution.OA temporary issue has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionAn exception occurred during execution.OA temporary issue has occurred. Please try again. [OK]

At the lower level (token processing logic), k_EStoveResultCode_RenewTokenMaxRetryCountExceeded (306) or k_EStoveCommonResultCode_Fail (1) may be passed.

Complete list: EStoveCommonResultCode, EStoveResultCode

Memory Management

ObjectOwnerRelease
paramCallerIf delivered, Stove_IStoveTypeBase_Destroy() Required
Callback callbackResult, tokenSDKDo not unlock. This will be invalidated once the callback is complete.

Example

c
Stove_AccessTokenRenewed(nullptr, [](const IStoveCallbackResult* callbackResult, const IStoveAccessToken* token)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);
    if (Stove_IStoveResult_IsSuccessful(result))
    {
        // Please implement the logic for a successful outcome.
        const wchar_t* newAccessToken = Stove_IStoveAccessToken_GetAccessToken(token);
        int32_t expireIn = Stove_IStoveAccessToken_GetExpireIn(token);
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}, nullptr);

Notes

  • This is a callback that is called repeatedly every time the token is renewed. It is not a one-time callback.
  • If you don't need the latest token every time, you can simply look it up using Stove_GetAccessToken as needed.

See Also


Stove_CloseAllPopups

Kind Function · Module Base · Version 3.5.0

Description

Closes all pop-ups displayed by the SDK. This applies to both IAP pop-ups and View pop-ups.

Following the integration of the single binary (BaseSDK Consolidation), this single function replaces the separate Stove_IAP_CloseAllPopups() and Stove_View_CloseAllPopups() functions that were previously used for each module. Now, a single call closes all SDK pop-ups at once.

Declaration

c
IStoveResult* Stove_CloseAllPopups();

Parameters

None

Returns

TypeDescription
IStoveResult*Here are the results of the call. A value of Stove_IStoveResult_IsSuccessful(result) indicates success.

The method code for this function is k_EStoveBaseMethodCode_CloseAllPopups.

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccess (IAP · Close View Popup, All Successful)x
68k_EStoveCommonResultCode_CloseAllPopupsFailedFailed to close one or more pop-ups for IAP or View (the specific error code is normalized to this single value and is not displayed)x
253k_EStoveCommonResultCode_UnmanagedExceptionAn unknown exception occurred during execution.OA temporary issue has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionAn internal exception occurred during executionOA temporary issue has occurred. Please try again. [OK]

This function internally always closes the pop-ups for both the IAP module and the View module. If either of the two operations fails (IAP is checked first), that result is adopted; all other failures, excluding the adopted result codes of success (0), UnmanagedException (253), and ManagedException (254), are normalized to a single value, CloseAllPopupsFailed (68), and returned. In other words, it is not possible to distinguish the specific cause of failure for each module, View or IAP, (e.g., WebView not initialized, no popup data, etc.) based solely on this function’s return value.

Complete list: EStoveCommonResultCode, EStoveResultCode

Memory Management

ObjectOwnerRelease
Returned IStoveResult*CallerStove_IStoveTypeBase_Destroy((IStoveTypeBase*)result) Required

Example

c
IStoveResult* result = Stove_CloseAllPopups();
if (Stove_IStoveResult_IsSuccessful(result))
{
    // Please implement the logic for a successful outcome.
}
else
{
    // Please implement the logic for when an error occurs.
}

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result);

Notes

  • Following the integration of the single binary, both the IAP popup and the View popup are closed with a single call. Both modules are always attempted, and if they fail, the returned error code is normalized to a single value: CloseAllPopupsFailed(68).
  • This function is synchronous and does not accept callbacks.

Stove_ConfirmPurchase

Kind Function · Module IAP · Version 3.5.0

Description

If the Operation (EStovePurchaseOperation) value of Stove_StartPurchase is not WithWebViewAndConfirmResult, call this function after the payment is complete to confirm the purchase. Set param to the IStoveStartPurchaseOutcome::GetTxnMasterNo() value received as the result of Stove_StartPurchase.

The confirmation results are sent via the onFinished callback, along with information on whether the transaction was confirmed, the list of purchased items, and the currency (charge) used for payment.

Declaration

c
void Stove_ConfirmPurchase(const IStoveConfirmPurchaseParam* param, OnConfirmPurchaseCallback onFinished, void* userData);

Parameters

NameTypeRequiredDescription
paramconst IStoveConfirmPurchaseParam*YThis is the master number (TxnMasterNo) parameter for the transaction to be finalized.
onFinishedOnConfirmPurchaseCallbackYThis is the callback that will receive the final results.
userDatavoid*NThis is the user data that is passed directly to the callback.

Returns

None

The method code for this function is k_EStoveIAPMethodCode_ConfirmPurchase.

Callback

c
typedef void(__cdecl* OnConfirmPurchaseCallback)(const IStoveCallbackResult* callbackResult, const IStoveConfirmPurchaseOutcome* outcome);
NameTypeDescription
callbackResultconst IStoveCallbackResult*Here are the results of the call.
outcomeconst IStoveConfirmPurchaseOutcome*These are the final results. Use Stove_IStoveConfirmPurchaseOutcome_IsConfirmed() to check whether the transaction has been finalized, and use GetPurchasedProductCount()/GetPurchasedProductAt() and GetChargeInfoCount()/GetChargeInfoAt() to view information about the purchased items and currency.

The callback runs in the thread that called Stove_RunCallback(). It is passed only once per call.

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
17k_EStoveCommonResultCode_NotInitializedThe payment feature is not initialized.x
21k_EStoveCommonResultCode_NullEntityLanguage information is not available (check whether Stove_SetLanguage was called).x
253k_EStoveCommonResultCode_UnmanagedExceptionAn unhandled exception occurred during execution.OA temporary issue has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionA managed exception occurred during execution (including missing internal entities such as login tokens).OA temporary problem has occurred. Please try again. [OK]

Network/server response errors are propagated through the lower HTTP layers.

Complete list: EStoveCommonResultCode, EStoveResultCode

Memory Management

ObjectOwnerRelease
paramCallerStove_IStoveTypeBase_Destroy((IStoveTypeBase*)param) Required. Release after the call returns.
Callback callbackResultSDKDo not unlock. This will be invalidated once the callback is complete.
The outcome in the callback (and each IStovePurchasedProduct and IStoveChargeInfo within it)SDKDo not unwrap. This will be invalidated once the callback completes, so you must copy any necessary values within the callback.

Example

c
// true if PCSDK was launched through the External Platform Integration Module (Steam) authentication path. The SDK picks the Steam payment flow from the SteamUserId passed at that point, so set this flag at the same moment.
static bool g_isSteamPayment = false;

void __cdecl OnConfirmPurchaseFinished(const IStoveCallbackResult* callbackResult, const IStoveConfirmPurchaseOutcome* outcome)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);
    if (!Stove_IStoveResult_IsSuccessful(result))
    {
        // The call failed. Check Stove_IStoveCallbackResult_GetExternalError() for the cause. (22001 = not approved on Steam)
        return;
    }

    if (g_isSteamPayment || Stove_IStoveConfirmPurchaseOutcome_IsConfirmed(outcome))
    {
        // Purchase confirmed. In the Steam launcher flow IsConfirmed is always false, so a successful call means confirmed.
        // In the Steam launcher flow PurchasedProducts arrives empty, so use the product info you kept at StartPurchase.
        uint32_t count = Stove_IStoveConfirmPurchaseOutcome_GetPurchasedProductCount(outcome);
        for (uint32_t i = 0; i < count; ++i)
        {
            const IStovePurchasedProduct* purchasedProduct = Stove_IStoveConfirmPurchaseOutcome_GetPurchasedProductAt(outcome, i);
            int64_t productId = Stove_IStovePurchasedProduct_GetProductId(purchasedProduct);
        }
        return;
    }

    // STOVE launcher flow, not confirmed (cancelled, not paid yet, or not yet recorded). Don't grant; if the window was just closed, query again once after 5 seconds.
}

// Call (txnMasterNo is the IStoveStartPurchaseOutcome::GetTxnMasterNo() value from the Stove_StartPurchase() result)
IStoveConfirmPurchaseParam* param = (IStoveConfirmPurchaseParam*)Stove_CreateParam(k_EStoveIAPTypeKind_ConfirmPurchaseParam);
Stove_IStoveConfirmPurchaseParam_SetTxnMasterNo(param, txnMasterNo);

Stove_ConfirmPurchase(param, OnConfirmPurchaseFinished, nullptr);

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param);

Notes

  • This function is asynchronous, and the result is returned only via the onFinished callback.
  • If Operation of Stove_StartPurchase is WithWebViewAndConfirmResult, the SDK automatically calls this function, so there is no need to call it separately.
  • Whether callbackResult is successful and outcome's IsConfirmed() are two separate matters. Even if the call itself is successful, if IsConfirmed() is false, the purchase has not been finalized.
  • In the Steam launcher flow, IsConfirmed() is always delivered as false regardless of the server response. In that flow, treat a successful call (IsSuccessful true) as the purchase being confirmed, and don't reference PurchasedProducts or ChargeInfos, which arrive as empty arrays. See the example above and the Steam Payment section of the Payment guide for judging both the STOVE launcher and the Steam launcher with one condition.
  • In the old interface, these results were passed as individual arguments, such as status, purchasedProducts, and chargeInfos. Now, they are passed as a single wrapped argument, IStoveConfirmPurchaseOutcome.

See Also


Stove_CreateParam

Kind Function · Module Base · Version 3.5.0

Description

Stove_CreateParam is a single object creation interface shared by all modules in the SDK. It creates and returns a IStoveTypeBase derived object corresponding to the value passed as kind.

You can pass any EStove*TypeKind value to kind, regardless of the module. The TypeKind enumerations for each module are divided into integer ranges that do not overlap, so this single function can be used to distinguish and generate any module type (e.g., k_EStoveBaseTypeKind_InitializeParam, k_EStoveIAPTypeKind_FetchProductsParam). However, only TypeKind values from the ...Param family for each module are valid; passing TypeKind values from the outcome/data families (Outcome, Info, List) or unknown values will not result in an error but will return nullptr.

Following the integration of the single binary (BaseSDK Consolidation), the Stove_<Module>CreateParam() factory functions, which were previously separated by module, have been replaced by this single function.

Declaration

c
IStoveTypeBase* Stove_CreateParam(int kind);

Parameters

NameTypeRequiredDescription
kindintYThis is the EStove*TypeKind value that specifies the type of object to be created. For the Base module, pass a value from the ...Param series of EStoveBaseTypeKind (e.g., k_EStoveBaseTypeKind_InitializeParam).

Returns

TypeDescription
IStoveTypeBase*This is a pointer to the created object. If the value of kind is not of the ...Param type or is unknown, return nullptr. Always check whether nullptr is true, then cast it to the requested type before using it (e.g., (IStoveInitializeParam*)).

Error Codes

None. This is a pure factory function that does not return IStoveResult; failure is determined solely by whether the return value is nullptr. There are no individual error codes.

Memory Management

ObjectOwnerRelease
Returned IStoveTypeBase*CallerStove_IStoveTypeBase_Destroy() Required

Example

c
IStoveTypeBase* base = Stove_CreateParam(k_EStoveBaseTypeKind_InitializeParam);
if (base != nullptr)
{
    IStoveInitializeParam* initParam = (IStoveInitializeParam*)base;

    Stove_IStoveInitializeParam_SetShopKey(initParam, L"YOUR_SHOP_KEY");
    Stove_IStoveInitializeParam_SetMainWndHandle(initParam, hWnd);

    // Be sure to call `Destroy` after using `initParam`.
    Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)initParam);
}
else
{
    // Please implement the logic for handling cases where the "kind" value is incorrect.
}

Notes

  • For information on what values can be assigned to kind, refer to the TypeKind documentation for each module. The Base module refers to EStoveBaseTypeKind.
  • All objects created with this function must be released using Stove_IStoveTypeBase_Destroy() after use.

See Also


Stove_FetchAchievement

Kind Function · Module GameSupport · Version 3.5.0

Description

Stove_FetchAchievement() is a function that retrieves the progress and details of a specified achievement ID. The results are passed to the onFinished callback.

The statistics and achievements features do not have a separate initialization process; their lifecycle is tied to the SDK initialization. Call them after Stove_Initialize() has succeeded.

Declaration

c
void Stove_FetchAchievement(const IStoveFetchAchievementParam* param, OnGetAchievementCallback onFinished, void* userData);

Parameters

NameTypeRequiredDescription
paramconst IStoveFetchAchievementParam*YA parameter containing the ID of the achievement to look up. Create it as Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchAchievementParam).
onFinishedOnGetAchievementCallbackYCallback to receive query results
userDatavoid*NUser data passed directly to the callback

Returns

None (void)

The method code for this function is k_EStoveGameSupportMethodCode_FetchAchievement.

Callback

c
typedef void(__cdecl* OnGetAchievementCallback)(const IStoveCallbackResult* callbackResult, const IStoveAchievement* achievement);
NameTypeDescription
callbackResultconst IStoveCallbackResult*Call Results
achievementconst IStoveAchievement*Achievement Information Found

This callback runs in the thread that called Stove_RunCallback(). It is passed only once per call to Stove_FetchAchievement().

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
5k_EStoveCommonResultCode_InvalidParamThe achievement ID (AchievementId) for param is an empty stringx
253k_EStoveCommonResultCode_UnmanagedExceptionAn unknown exception occurred during processingOA temporary issue has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionAn internal exception occurred during processing (e.g., failure to retrieve an entity)OA temporary issue has occurred. Please try again. [OK]

Errors corresponding to HTTP communication failures (HttpError=22, ResponseError=23, ResponseInvalidCode=24, ResponseValueIsNull=25, ResponseInvalidValueFormat=26, NetworkTransportError=249) are passed from the lower communication layer and are not set directly by this function.

The old interface (GameSupport_Achievement) has a separate gate that returns NotInitialized (17) when the module has not been initialized, but the new flat C surface, Stove_FetchAchievement(), does not have this gate. In other words, this function does not return 17.

Complete list: EStoveCommonResultCode

Memory Management

ObjectOwnerRelease
paramCallerStove_IStoveTypeBase_Destroy((IStoveTypeBase*)param) Required (Can be released immediately after the Stove_FetchAchievement() call returns)
Callback callbackResultSDKDo not unlock. This will be invalidated once the callback is complete.
Callback achievementSDKDo not unlock. This will be invalidated once the callback is complete.

Example

c
void OnFetchAchievementFinished(const IStoveCallbackResult* callbackResult, const IStoveAchievement* achievement)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

    if (Stove_IStoveResult_IsSuccessful(result) && achievement != NULL)
    {
        const wchar_t* status = Stove_IStoveAchievement_GetStatus(achievement);

        // Please implement the logic for a successful outcome.
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

IStoveFetchAchievementParam* param =
    (IStoveFetchAchievementParam*)Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchAchievementParam);
Stove_IStoveFetchAchievementParam_SetAchievementId(param, L"FIRST_WIN");

Stove_FetchAchievement(param, OnFetchAchievementFinished, NULL);

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param);

Notes

  • This function executes the underlying logic immediately without checking whether it has been initialized. If called before initialization, it may result in ManagedException(254).
  • To view the complete list of a logged-in user's achievements, use Stove_FetchAchievements.
  • The statistics and achievements features are available exclusively in the Store.

See Also


Stove_FetchAchievements

Kind Function · Module GameSupport · Version 3.5.0

Description

Stove_FetchAchievements() is a function that retrieves the complete achievement information for the currently logged-in user. The results are passed to the onFinished callback.

Please do not use paginated queries in v3.5.0. If you make a call without filling in AchievementId and PageSize, the entire list of achievements will be retrieved at once, as before. Paginated queries will be available starting with v3.5.1 once the server API specifications have been finalized.

The statistics and achievements features do not have a separate initialization process; their lifecycle depends on the SDK initialization. Call them after Stove_Initialize() has succeeded.

Declaration

c
void Stove_FetchAchievements(const IStoveFetchAchievementsParam* param, OnGetAchievementsCallback onFinished, void* userData);

Parameters

NameTypeRequiredDescription
paramconst IStoveFetchAchievementsParam*YQuery parameter. Create it as Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchAchievementsParam). In v3.5.0, pass it as is without filling in a value.
onFinishedOnGetAchievementsCallbackYCallback to receive query results
userDatavoid*NUser data passed directly to the callback

Returns

None (void)

The method code for this function is k_EStoveGameSupportMethodCode_FetchAchievements.

Callback

c
typedef void(__cdecl* OnGetAchievementsCallback)(const IStoveCallbackResult* callbackResult, const IStoveAchievementList* list);
NameTypeDescription
callbackResultconst IStoveCallbackResult*Call Results
listconst IStoveAchievementList*List of Achievements Found

This callback runs in the thread that called Stove_RunCallback(). It is passed only once per call to Stove_FetchAchievements().

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
253k_EStoveCommonResultCode_UnmanagedExceptionAn unknown exception occurred during processingOA temporary problem has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionAn internal exception occurred during processing (e.g., failure to retrieve an entity)OA temporary issue has occurred. Please try again. [OK]

Errors corresponding to HTTP communication failures (HttpError=22, ResponseError=23, ResponseInvalidCode=24, ResponseValueIsNull=25, ResponseInvalidValueFormat=26, NetworkTransportError=249) are passed from the underlying communication layer and are not set directly by this function.

No separate InvalidParam(5) validation is applied to the values of the fields in param (AchievementId, PageSize), if no values are entered, the entire list will be retrieved without errors.

The old interface (GameSupport_AllAchievement) has a separate gate that returns NotInitialized(17) when the module has not been initialized, but the new flat C surface, Stove_FetchAchievements(), does not have this gate. In other words, this function does not return 17.

Complete list: EStoveCommonResultCode

Memory Management

ObjectOwnerRelease
paramCallerStove_IStoveTypeBase_Destroy((IStoveTypeBase*)param) Required (Can be released immediately after the Stove_FetchAchievements() call returns)
Callback callbackResultSDKDo Not Unlock. This will be invalidated once the callback is complete.
The list in Callback (and each achievement item within it)SDKDo Not Unlock. This will be invalidated once the callback is complete.

Example

c
void OnFetchAchievementsFinished(const IStoveCallbackResult* callbackResult, const IStoveAchievementList* list)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

    if (Stove_IStoveResult_IsSuccessful(result) && list != NULL)
    {
        uint32_t count = Stove_IStoveAchievementList_GetCount(list);
        for (uint32_t i = 0; i < count; ++i)
        {
            const IStoveAchievement* achievement = Stove_IStoveAchievementList_GetAt(list, i);
            // Please implement the logic for a successful outcome.
        }
    }
    else
    {
        // Please implement the logic for when a failure occurs.
    }
}

IStoveFetchAchievementsParam* param =
    (IStoveFetchAchievementsParam*)Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchAchievementsParam);
// In v3.5.0, the value is passed as-is without being filled in.

Stove_FetchAchievements(param, OnFetchAchievementsFinished, NULL);

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param);

Notes

  • This function executes the underlying logic immediately without checking whether it has been initialized. If called before initialization, it may result in ManagedException (254).
  • To look up a specific achievement, use Stove_FetchAchievement.
  • In v3.5.0, do not fill in AchievementId or PageSize. If you leave these fields blank, the entire list of achievements will be retrieved at once.
  • Page-based queries using two values will be available starting with version 3.5.1, once the server API specifications have been finalized.
  • The statistics and achievements features are available exclusively in the Store.

See Also


Stove_FetchInventory

Kind Function · Module IAP · Version 3.5.0

Description

Retrieves the purchase history of the currently logged-in user. The list of retrieved inventory items is passed to the onFinished callback in the format IStoveInventoryList.

Declaration

c
void Stove_FetchInventory(const IStoveTypeBase* param, OnFetchInventoryCallback onFinished, void* userData);

Parameters

NameTypeRequiredDescription
paramconst IStoveTypeBase*NThis is a reserved parameter. Since it is not currently used, always pass nullptr.
onFinishedOnFetchInventoryCallbackYThis is the callback that receives the list of inventory items.
userDatavoid*NThis is the user data that is passed directly to the callback.

Returns

None

The method code for this function is k_EStoveIAPMethodCode_FetchInventory.

Callback

c
typedef void(__cdecl* OnFetchInventoryCallback)(const IStoveCallbackResult* callbackResult, const IStoveInventoryList* list);
NameTypeDescription
callbackResultconst IStoveCallbackResult*Here are the results of the call.
listconst IStoveInventoryList*This is a list of the inventory items found. It loops through Stove_IStoveInventoryList_GetCount() / Stove_IStoveInventoryList_GetAt().

The callback runs in the thread that called Stove_RunCallback(). It is passed only once per call.

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
17k_EStoveCommonResultCode_NotInitializedThe payment feature is not initialized.x
253k_EStoveCommonResultCode_UnmanagedExceptionAn unhandled exception occurred during execution.OA temporary issue has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionA managed exception occurred during execution (including missing internal entities such as the login token).OA temporary problem has occurred. Please try again. [OK]

Network/server response errors are passed down to the lower HTTP layer.

Complete list: EStoveCommonResultCode, EStoveResultCode

Memory Management

ObjectOwnerRelease
paramCallerSince this is a reservation parameter that is no longer in use, there is nothing to deactivate.
Callback callbackResultSDKDo not unlock. This will be invalidated once the callback is complete.
The list in the callback (and each IStoveInventoryItem within it)SDKDo not unwrap. This will be invalidated once the callback completes, so you must copy any necessary values within the callback.

Example

c
void __cdecl OnFetchInventoryFinished(const IStoveCallbackResult* callbackResult, const IStoveInventoryList* list)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);
    if (Stove_IStoveResult_IsSuccessful(result))
    {
        // Please implement the logic for a successful outcome.
        uint32_t count = Stove_IStoveInventoryList_GetCount(list);
        for (uint32_t i = 0; i < count; ++i)
        {
            const IStoveInventoryItem* item = Stove_IStoveInventoryList_GetAt(list, i);
            const wchar_t* productName = Stove_IStoveInventoryItem_GetProductName(item);
        }
    }
    else
    {
        // Please implement the logic for when a failure occurs.
    }
}

// Call
Stove_FetchInventory(nullptr, OnFetchInventoryFinished, nullptr);

Notes

  • This function is asynchronous, and the result is returned only via the onFinished callback.
  • Since param is a reserved parameter that is no longer in use, always pass nullptr.

See Also


Stove_FetchOwnerships

Kind Function · Module Ownership · Version 3.5.0

Description

Retrieves the ownership entries for the currently running game (base game, DLC, demo, etc.) held by the logged-in user. The query results are passed to the callback as IStoveOwnershipList.

This must be called after the SDK has been initialized.

Declaration

c
void Stove_FetchOwnerships(const IStoveTypeBase* param, OnOwnershipListCallback onFinished, void* userData);

Parameters

NameTypeRequiredDescription
paramconst IStoveTypeBase*NThis is a reserved parameter. Since this call has no dedicated parameter type, pass nullptr.
onFinishedOnOwnershipListCallbackYThis is the callback that will receive the query results.
userDatavoid*NThis is the user data that is passed directly to the callback.

Returns

None

The method code for this function is k_EStoveOwnershipMethodCode_FetchOwnerships.

Callback

c
typedef void(__cdecl* OnOwnershipListCallback)(const IStoveCallbackResult* callbackResult, const IStoveOwnershipList* ownerships);
NameTypeDescription
callbackResultconst IStoveCallbackResult*Here are the results of the query.
ownershipsconst IStoveOwnershipList*This is a list of ownership entries. It iterates through GetCount() / GetAt().

The callback runs in the thread that called Stove_RunCallback() and is passed once for each call to Stove_FetchOwnerships().

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
5k_EStoveCommonResultCode_InvalidParamonFinished is nullptr.x
17k_EStoveCommonResultCode_NotInitializedThe SDK has not been initialized (internal check within the operation)x
253k_EStoveCommonResultCode_UnmanagedExceptionAn unknown exception has occurred.OA temporary issue has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionA handled exception has occurredOA temporary issue has occurred. Please try again. [OK]

Other HTTP/response-related codes are passed down from the lower layer.

Complete list: EStoveCommonResultCode, EStoveResultCode

Memory Management

ObjectOwnerRelease
paramCallerSince this is a reservation parameter that is currently not in use, pass nullptr; there is no need to disable it separately.
Callback callbackResultSDKDo not unlock. This will be invalidated once the callback is complete.
Each item returned by the callbacks ownerships and GetAt()SDKDo not unwrap. All values will be discarded once the callback ends. Copy any values you need to preserve within the callback.

Example

c
void __cdecl OnFetchOwnerships(const IStoveCallbackResult* callbackResult, const IStoveOwnershipList* ownerships)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);
    if (Stove_IStoveResult_IsSuccessful(result))
    {
        uint32_t count = Stove_IStoveOwnershipList_GetCount(ownerships);
        for (uint32_t i = 0; i < count; ++i)
        {
            const IStoveOwnership* ownership = Stove_IStoveOwnershipList_GetAt(ownerships, i);
            if (ownership == nullptr)
            {
                continue;
            }

            const wchar_t* gameId = Stove_IStoveOwnership_GetGameId(ownership);
            int32_t ownershipCode = Stove_IStoveOwnership_GetOwnershipCode(ownership);

            // Please implement the logic for a successful outcome.
        }
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

Stove_FetchOwnerships(nullptr, OnFetchOwnerships, nullptr);

// The callback will only be executed if it is called repeatedly within the game loop.
while (isGameRunning)
{
    Stove_RunCallback();
}

Notes

  • This function is asynchronous, and the result is returned only via a callback.
  • Since param is a reserved slot that is currently unused, you can pass nullptr instead.
  • ownerships is not an out-parameter in the form of an array plus a count, but rather an SDK-specific list wrapper type that includes GetCount()/GetAt().

See Also


Stove_FetchProducts

Kind Function · Module IAP · Version 3.5.0

Description

Retrieves a list of products that match the category ID and page conditions passed via params. The retrieved product list is returned via the onFinished callback in the format IStoveProductList.

If you leave the category ID blank, products from all categories will be displayed. To display only products from a specific category, set CategoryId, obtained from Stove_FetchShopCategories, as the filter.

Declaration

c
void Stove_FetchProducts(const IStoveFetchProductsParam* params, OnFetchProductsCallback onFinished, void* userData);

Parameters

NameTypeRequiredDescription
paramsconst IStoveFetchProductsParam*YThese are category filter and page condition parameters.
onFinishedOnFetchProductsCallbackYThis is the callback that will receive the product list.
userDatavoid*NThis is the user data that is passed directly to the callback.

Returns

None

The method code for this function is k_EStoveIAPMethodCode_FetchProducts.

Callback

c
typedef void(__cdecl* OnFetchProductsCallback)(const IStoveCallbackResult* callbackResult, const IStoveProductList* list);
NameTypeDescription
callbackResultconst IStoveCallbackResult*Here are the results of the call.
listconst IStoveProductList*Here is the list of products found. It ranges from Stove_IStoveProductList_GetCount() to Stove_IStoveProductList_GetAt().

The callback runs in the thread that called Stove_RunCallback(). It is passed only once per call.

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
17k_EStoveCommonResultCode_NotInitializedThe payment feature is not initialized.x
253k_EStoveCommonResultCode_UnmanagedExceptionAn unhandled exception occurred during execution.OA temporary issue has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionA managed exception occurred during execution (including missing internal entities such as the login token).OA temporary issue has occurred. Please try again. [OK]

Network/server response errors are passed down to the lower HTTP layers.

Complete list: EStoveCommonResultCode, EStoveResultCode

Memory Management

ObjectOwnerRelease
paramsCallerStove_IStoveTypeBase_Destroy((IStoveTypeBase*)params) Required. Release after the call returns.
Callback callbackResultSDKDo not unlock. This will be invalidated once the callback is complete.
The list of the callback (and each IStoveProduct within it)SDKDo not unwrap. This will be invalidated once the callback ends, so you must copy any necessary values within the callback.

Example

c
void __cdecl OnFetchProductsFinished(const IStoveCallbackResult* callbackResult, const IStoveProductList* list)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);
    if (Stove_IStoveResult_IsSuccessful(result))
    {
        // Please implement the logic for a successful outcome.
        uint32_t count = Stove_IStoveProductList_GetCount(list);
        for (uint32_t i = 0; i < count; ++i)
        {
            const IStoveProduct* product = Stove_IStoveProductList_GetAt(list, i);
            int64_t productId = Stove_IStoveProduct_GetProductId(product);
            const wchar_t* productName = Stove_IStoveProduct_GetProductName(product);
        }
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

// Call
IStoveFetchProductsParam* params = (IStoveFetchProductsParam*)Stove_CreateParam(k_EStoveIAPTypeKind_FetchProductsParam);
Stove_IStoveFetchProductsParam_SetCategoryId(params, L"");
Stove_IStoveFetchProductsParam_SetPageIndex(params, 1);
Stove_IStoveFetchProductsParam_SetPageSize(params, 20);

Stove_FetchProducts(params, OnFetchProductsFinished, nullptr);

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)params);

Notes

  • This call performs the extended action for retrieving a product list (corresponding to the Ex variant in the old interface).
  • This function is asynchronous, and the result is returned only via the onFinished callback.
  • params is generated from Stove_CreateParam(k_EStoveIAPTypeKind_FetchProductsParam).
  • The ProductId value for the retrieved product is used as the product identifier for the order line item when calling Stove_StartPurchase.

See Also


Stove_FetchRanking

Kind Function · Module GameSupport · Version 3.5.0

Description

Stove_FetchRanking() is a function that retrieves ranking information for a specified leaderboard on a per-page basis. The results are passed to the onFinished callback.

The statistics and achievements features do not have a separate initialization process; their lifecycle is tied to the SDK initialization. Call them after Stove_Initialize() succeeds.

Declaration

c
void Stove_FetchRanking(const IStoveFetchRankingParam* rankParams, OnGetRankingCallback onFinished, void* userData);

Parameters

NameTypeRequiredDescription
rankParamsconst IStoveFetchRankingParam*YA parameter containing the leaderboard ID to retrieve and the pagination conditions. It is generated as Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchRankingParam).
onFinishedOnGetRankingCallbackYCallback to receive query results
userDatavoid*NUser data passed directly to the callback

Returns

None (void)

The method code for this function is k_EStoveGameSupportMethodCode_FetchRanking.

Callback

c
typedef void(__cdecl* OnGetRankingCallback)(const IStoveCallbackResult* callbackResult, const IStoveRanking* ranking);
NameTypeDescription
callbackResultconst IStoveCallbackResult*Call Results
rankingconst IStoveRanking*List of Rankings (Current Page)

This callback runs in the thread that called Stove_RunCallback(). It is passed only once per call to Stove_FetchRanking().

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
5k_EStoveCommonResultCode_InvalidParamThe leaderboard ID (LeaderboardId) for rankParams is an empty stringx
253k_EStoveCommonResultCode_UnmanagedExceptionAn unknown exception occurred during processingOA temporary issue has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionAn internal exception occurred during processing (e.g., failed to retrieve an entity)OA temporary issue has occurred. Please try again. [OK]

Errors corresponding to HTTP communication failures (HttpError=22, ResponseError=23, ResponseInvalidCode=24, ResponseValueIsNull=25, ResponseInvalidValueFormat=26, NetworkTransportError=249) are passed from the lower communication layer and are not set directly by this function.

The old interface (GameSupport_Rank) has a separate gate that returns NotInitialized (17) when the module is not initialized, but the new flat C surface, Stove_FetchRanking(), does not have this gate. In other words, this function does not return 17.

Complete list: EStoveCommonResultCode

Memory Management

ObjectOwnerRelease
rankParamsCallerStove_IStoveTypeBase_Destroy((IStoveTypeBase*)rankParams) Required (Can be released immediately after the Stove_FetchRanking() call returns)
Callback callbackResultSDKDo not unlock. This will be invalidated once the callback is complete.
The ranking of the callback (and each ranking item within it)SDKDo not unlock. This will be invalidated once the callback is complete.

Example

c
void OnFetchRankingFinished(const IStoveCallbackResult* callbackResult, const IStoveRanking* ranking)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

    if (Stove_IStoveResult_IsSuccessful(result) && ranking != NULL)
    {
        uint32_t count = Stove_IStoveRanking_GetCount(ranking);
        for (uint32_t i = 0; i < count; ++i)
        {
            const IStoveRank* rank = Stove_IStoveRanking_GetAt(ranking, i);
            // Please implement the logic for a successful outcome.
        }
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

IStoveFetchRankingParam* rankParams =
    (IStoveFetchRankingParam*)Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchRankingParam);
Stove_IStoveFetchRankingParam_SetLeaderboardId(rankParams, L"WEEKLY_SCORE");
Stove_IStoveFetchRankingParam_SetPageIndex(rankParams, 1);
Stove_IStoveFetchRankingParam_SetPageSize(rankParams, 50);
Stove_IStoveFetchRankingParam_SetIncludeMyRank(rankParams, true);

Stove_FetchRanking(rankParams, OnFetchRankingFinished, NULL);

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)rankParams);

Notes

  • This function executes the underlying logic immediately without checking whether initialization has been performed. If called before initialization is complete, it may result in ManagedException(254).
  • PageIndex starts at 1.
  • PageSize must be set to a value between 1 and 50, inclusive.
  • If you set IncludeMyRank to true, the search results will include the logged-in user's rank.
  • The statistics and achievements features are available only in the Store.

See Also


Stove_FetchShopCategories

Kind Function · Module IAP · Version 3.5.0

Description

Retrieves the list of categories registered for the store. The retrieved list of categories is passed to the onFinished callback in the format IStoveShopCategoryList.

Since you can filter products by category ID when calling Stove_FetchProducts, when setting up your storefront, use this function first to retrieve the list of categories, and then use it to retrieve the products belonging to each category.

Declaration

c
void Stove_FetchShopCategories(const IStoveTypeBase* param, OnFetchShopCategoriesCallback onFinished, void* userData);

Parameters

NameTypeRequiredDescription
paramconst IStoveTypeBase*NThis is a reserved parameter. Since it is not currently in use, always pass nullptr.
onFinishedOnFetchShopCategoriesCallbackYThis is the callback that will receive the category list.
userDatavoid*NThis is the user data that is passed directly to the callback.

Returns

None

The method code for this function is k_EStoveIAPMethodCode_FetchShopCategories.

Callback

c
typedef void(__cdecl* OnFetchShopCategoriesCallback)(const IStoveCallbackResult* callbackResult, const IStoveShopCategoryList* list);
NameTypeDescription
callbackResultconst IStoveCallbackResult*Here are the results of the call.
listconst IStoveShopCategoryList*Here is the list of categories found. It cycles through Stove_IStoveShopCategoryList_GetCount() and Stove_IStoveShopCategoryList_GetAt().

The callback runs in the thread that called Stove_RunCallback(). It is passed only once per call.

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
17k_EStoveCommonResultCode_NotInitializedThe payment feature is not initialized.x
253k_EStoveCommonResultCode_UnmanagedExceptionAn unhandled exception occurred during execution.OThere was a temporary issue. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionA managed exception occurred during execution (including missing internal entities such as login tokens).OA temporary problem has occurred. Please try again. [OK]

Network/server response errors are passed down to the lower HTTP layer.

Complete list: EStoveCommonResultCode, EStoveResultCode

Memory Management

ObjectOwnerRelease
paramCallerSince this is a reservation parameter that is no longer in use, there is nothing to deactivate.
Callback callbackResultSDKDo Not Unlock. This will be invalidated once the callback is complete.
The list in the callback (and each IStoveShopCategory within it)SDKDo not unwrap. The callback will be invalidated once it completes, so you must copy any necessary values within the callback.

Example

c
void __cdecl OnFetchShopCategoriesFinished(const IStoveCallbackResult* callbackResult, const IStoveShopCategoryList* list)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);
    if (Stove_IStoveResult_IsSuccessful(result))
    {
        // Please implement the logic for a successful outcome.
        uint32_t count = Stove_IStoveShopCategoryList_GetCount(list);
        for (uint32_t i = 0; i < count; ++i)
        {
            const IStoveShopCategory* category = Stove_IStoveShopCategoryList_GetAt(list, i);
            const wchar_t* categoryId = Stove_IStoveShopCategory_GetCategoryId(category);
            const wchar_t* categoryName = Stove_IStoveShopCategory_GetCategoryName(category);
        }
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

// Call
Stove_FetchShopCategories(nullptr, OnFetchShopCategoriesFinished, nullptr);

Notes

  • This function is asynchronous, and the result is returned only via the onFinished callback.
  • Since param is a reserved parameter that is no longer in use, always pass nullptr.
  • The CategoryId for the retrieved category can be used as a category filter when calling Stove_FetchProducts.

See Also


Stove_FetchStat

Kind Function · Module GameSupport · Version 3.5.0

Description

Stove_FetchStat() is a function that retrieves the current value of the specified statistic (Stat) ID. The result is passed to the onFinished callback.

The statistics and achievements features do not have a separate initialization process; their lifecycle is tied to the SDK initialization. Call them after Stove_Initialize() succeeds.

Declaration

c
void Stove_FetchStat(const IStoveFetchStatParam* param, OnGetStatCallback onFinished, void* userData);

Parameters

NameTypeRequiredDescription
paramconst IStoveFetchStatParam*YA parameter containing the ID of the statistic to retrieve. It is generated as Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchStatParam).
onFinishedOnGetStatCallbackYCallback to receive query results
userDatavoid*NUser data passed directly to the callback

Returns

None (void)

The method code for this function is k_EStoveGameSupportMethodCode_FetchStat.

Callback

c
typedef void(__cdecl* OnGetStatCallback)(const IStoveCallbackResult* callbackResult, const IStoveStat* stat);
NameTypeDescription
callbackResultconst IStoveCallbackResult*Call Results
statconst IStoveStat*Statistical Information Retrieved

This callback runs in the thread that called Stove_RunCallback(). It is passed only once per call to Stove_FetchStat().

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
5k_EStoveCommonResultCode_InvalidParamThe statistics ID (StatsId) for param is an empty stringx
253k_EStoveCommonResultCode_UnmanagedExceptionAn unknown exception occurred during processingOA temporary issue has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionAn internal exception occurred during processing (e.g., failure to retrieve an entity)OA temporary issue has occurred. Please try again. [OK]

Errors codes corresponding to HTTP communication failures (HttpError=22, ResponseError=23, ResponseInvalidCode=24, ResponseValueIsNull=25, ResponseInvalidValueFormat=26, NetworkTransportError=249) are passed from the lower communication layer and are not set directly by this function.

The old interface (GameSupport_Stat) has a separate gate that returns NotInitialized(17) when the module is not initialized, but the new flat C surface, Stove_FetchStat(), does not have this gate. In other words, this function does not return 17.

Complete List: EStoveCommonResultCode

Memory Management

ObjectOwnerRelease
paramCallerStove_IStoveTypeBase_Destroy((IStoveTypeBase*)param) Required (Can be released immediately after Stove_FetchStat() returns)
Callback callbackResultSDKDo not unlock. This will be invalidated once the callback is complete.
Callback statSDKDo not unlock. It will be invalidated once the callback is complete.

Example

c
void OnFetchStatFinished(const IStoveCallbackResult* callbackResult, const IStoveStat* stat)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

    if (Stove_IStoveResult_IsSuccessful(result) && stat != NULL)
    {
        int32_t currentValue = Stove_IStoveStat_GetCurrentValue(stat);

        // Please implement the logic for when the operation is successful.
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

IStoveFetchStatParam* param =
    (IStoveFetchStatParam*)Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchStatParam);
Stove_IStoveFetchStatParam_SetStatsId(param, L"KILL_COUNT");

Stove_FetchStat(param, OnFetchStatFinished, NULL);

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param);

Notes

  • This function executes the underlying logic immediately without checking whether it has been initialized. If called before initialization, it may result in ManagedException(254).
  • To change the statistical value, use Stove_SetStat.
  • The format of the statistics ID for param is [A-Z0-9\-_]*$ (uppercase letters, numbers, underscores, and hyphens).
  • The statistics and achievements features are available exclusively in the Store.

See Also


Stove_FetchTermsAgreement

Kind Function · Module IAP · Version 3.5.0

Description

Checks whether the user has agreed to the current terms and conditions. If the user has already agreed, the IsAgreed() in the result passed to onFinished is true, and Url is an empty string. If the user has not agreed, the behavior varies depending on the value of Operation (EStoveTermsOperation) in param.

  • Default: The caller must open the Terms and Conditions page directly using Url, which is passed to onFinished.
  • WithWebView: The SDK displays the Terms and Conditions page directly in Stove Webview.

For all failures (such as failure to initialize or exceptions) where the WebView is not created at all and the call terminates, onDestroy is called once along with PopupNotCreated (33). For more details, see the "Error Codes and Callbacks" section.

Declaration

c
void Stove_FetchTermsAgreement(const IStoveFetchTermsAgreementParam* param,
                                OnFetchTermsAgreementCallback onFinished, OnIAPPopupDestroyCallback onDestroy,
                                void* userData1, void* userData2);

Parameters

NameTypeRequiredDescription
paramconst IStoveFetchTermsAgreementParam*YThese are the parameters for the Terms and Conditions lookup operation and WebView layout.
onFinishedOnFetchTermsAgreementCallbackYThis is a callback to receive the consent status and the URL for the terms and conditions.
onDestroyOnIAPPopupDestroyCallbackNThis is a callback that is called when all pop-ups created by the SDK have been closed.
userData1void*NThis is user data that is passed directly to onFinished.
userData2void*NThis is user data that is passed directly to onDestroy.

Returns

None

The method code for this function is k_EStoveIAPMethodCode_FetchTermsAgreement.

Callback

c
typedef void(__cdecl* OnFetchTermsAgreementCallback)(const IStoveCallbackResult* callbackResult, const IStoveTermsAgreementOutcome* outcome);

typedef void(__cdecl* OnIAPPopupDestroyCallback)(const IStoveCallbackResult* callbackResult, const IStoveTypeBase* reserved);
NameTypeDescription
callbackResultconst IStoveCallbackResult*Here are the results of the call.
outcomeconst IStoveTermsAgreementOutcome*Here is the link to the terms and conditions and the consent form. You can view them at Stove_IStoveTermsAgreementOutcome_IsAgreed() / Stove_IStoveTermsAgreementOutcome_GetUrl().
reservedconst IStoveTypeBase*This is a reserved parameter. It is currently always nullptr.

Both callbacks run on the thread that called Stove_RunCallback().

  • onFinished is passed only once per call.
  • onDestroy is returned once after all pop-ups created by this call have been closed (if Operation == WithWebView). Even if no pop-ups are created and the call terminates, it is called once with the result code PopupNotCreated (33).

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccess (including cases where consent has already been given)x
17k_EStoveCommonResultCode_NotInitializedThe payment feature is not initialized.x
60k_EStoveCommonResultCode_ViewUiNotInitializedSince Operation is not Default, the Terms and Conditions page must be opened in a WebView, but the WebView/pop-up UI subsystem has not been initialized.x
65k_EStoveCommonResultCode_WebviewCloseAllFailBefore opening the Terms and Conditions web view, the system failed to close all previously open IAP web views.x
62k_EStoveCommonResultCode_WebviewCreateFailThe attempt to create the Terms and Conditions web view failed.x
64k_EStoveCommonResultCode_WebviewCreateCookieFailFailed to set the language (locale) cookie.OYou must agree to the terms and conditions to make a purchase. We were unable to load the terms and conditions screen. Please try again. [OK]
63k_EStoveCommonResultCode_WebviewLoadUrlFailFailed to load the Terms and Conditions page URL in the Terms and Conditions web view.x
66k_EStoveCommonResultCode_WebviewCloseFailAn internal closure operation failed during the normal closing process of the WebView. This error is logged as onDestroy, not onFinished.x
253k_EStoveCommonResultCode_UnmanagedExceptionAn unhandled exception occurred during execution.OA temporary issue has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionA managed exception occurred during execution (including missing internal entities such as login tokens).OA temporary issue has occurred. Please try again. [OK]
33k_EStoveCommonResultCode_PopupNotCreatedThe call ended without creating a popup. It is passed only to onDestroy.x

Network/server response errors (including failures to retrieve the SSO key when the terms of service are either accepted or not accepted) are passed down to the lower HTTP layer.

Complete list: EStoveCommonResultCode, EStoveResultCode

Memory Management

ObjectOwnerRelease
paramCallerStove_IStoveTypeBase_Destroy((IStoveTypeBase*)param) Required. Release after the call returns.
Callback callbackResultSDKDo not unlock. This will be invalidated once the callback is complete.
Callback outcomeSDKDo not unwrap. This will be invalidated once the callback ends, so you must copy any necessary values (e.g., Url) within the callback.

Example

c
void __cdecl OnFetchTermsAgreementFinished(const IStoveCallbackResult* callbackResult, const IStoveTermsAgreementOutcome* outcome)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);
    if (Stove_IStoveResult_IsSuccessful(result))
    {
        // Please implement the logic for a successful outcome.
        if (!Stove_IStoveTermsAgreementOutcome_IsAgreed(outcome))
        {
            const wchar_t* url = Stove_IStoveTermsAgreementOutcome_GetUrl(outcome);
            // Please open the Terms and Conditions page via the URL.
        }
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

void __cdecl OnFetchTermsAgreementPopupDestroyed(const IStoveCallbackResult* callbackResult, const IStoveTypeBase* reserved)
{
    // Please implement the logic that triggers when all the Terms and Conditions page pop-ups have been closed.
}

// Call
IStoveFetchTermsAgreementParam* param = (IStoveFetchTermsAgreementParam*)Stove_CreateParam(k_EStoveIAPTypeKind_FetchTermsAgreementParam);
Stove_IStoveFetchTermsAgreementParam_SetOperation(param, k_EStoveTermsOperation_Default);

Stove_FetchTermsAgreement(param, OnFetchTermsAgreementFinished, OnFetchTermsAgreementPopupDestroyed, nullptr, nullptr);

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param);

Notes

  • This function is asynchronous, and the result is returned only via the onFinished callback.
  • Using Operation == WithWebView eliminates the need for the caller to implement the Terms and Conditions page UI directly.
  • The WebView* field (WebView position and size, an inherited member of IStoveWebViewLayoutParam) applies only when Operation != Default is true.

See Also


Stove_GetAccessToken

Kind Function · Module Base · Version 3.5.0

Description

Retrieves the currently valid AccessToken. The SDK automatically renews the token internally to ensure that a valid token is always available.

Declaration

c
IStoveResult* Stove_GetAccessToken(wchar_t* outAccessToken, uint32_t length);

Parameters

NameTypeRequiredDescription
outAccessTokenwchar_t*YThis is the buffer that will receive the AccessToken string.
lengthuint32_tYoutAccessToken is the length of the buffer.

Returns

TypeDescription
IStoveResult*Here are the results of the call. If Stove_IStoveResult_GetResultCode() equals 0, the call was successful.

The method code for this function is k_EStoveBaseMethodCode_GetAccessToken.

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
5k_EStoveCommonResultCode_InvalidParamoutAccessToken is nullptr, length is 0, or the buffer is too small, so the value was truncated.x
16k_EStoveCommonResultCode_BaseNotInitializedIt was called before being initialized.x
19k_EStoveCommonResultCode_InvalidAccessTokenThe AccessToken is invalid.OYour login session has expired. Please close the game and restart it. [OK]
253k_EStoveCommonResultCode_UnmanagedExceptionAn unknown exception occurred during execution.OA temporary issue has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionAn exception occurred during execution.OA temporary issue has occurred. Please try again. [OK]

If you receive the code below, you must exit the game. The game cannot proceed normally.

  • 19 k_EStoveCommonResultCode_InvalidAccessToken, Your login session has expired and needs to be refreshed

Complete list: EStoveCommonResultCode

Memory Management

ObjectOwnerRelease
outAccessTokenCallerThis is a buffer allocated by the caller. It is not a target for destruction.
Returned IStoveResult*CallerStove_IStoveTypeBase_Destroy() Required

Example

c
wchar_t accessToken[1024] = { 0 };
IStoveResult* result = Stove_GetAccessToken(accessToken, 1024);
if (Stove_IStoveResult_IsSuccessful(result))
{
    // Please implement the logic for a successful operation. Use the accessToken.
}
else
{
    // Please implement the logic for when a failure occurs.
}

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result);

Notes

  • Since the SDK automatically renews tokens internally, this function always returns a valid token.
  • Do not keep the retrieved token in the game and reuse it later. The SDK renews the token periodically, so a stored value can expire. Call this function every time a token is needed and use the value returned at that moment.
  • Use Stove_AccessTokenRenewed to receive a separate notification when the token is renewed.

See Also


Stove_GetCloudSavingPath

Kind Function · Module Base · Version 3.5.0

Description

This is a synchronous function that retrieves the cloud storage path.

This must be called after the SDK has been initialized.

Declaration

c
IStoveResult* Stove_GetCloudSavingPath(wchar_t* outPath, uint32_t length);

Parameters

NameTypeRequiredDescription
outPathwchar_t*YThis is a buffer to receive the cloud storage path string. It is preallocated by the caller.
lengthuint32_tYoutPath is the length (in characters) of the buffer.

Returns

TypeDescription
IStoveResult*Here are the results of the call. A value of Stove_IStoveResult_IsSuccessful(result) indicates success.

The method code for this function is k_EStoveBaseMethodCode_GetCloudSavingPath.

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
5k_EStoveCommonResultCode_InvalidParamoutPath is nullptr, length is 0, or the path string is truncated (STRUNCATE) because the buffer is too small.x
16k_EStoveCommonResultCode_BaseNotInitializedThe SDK did not initializex
253k_EStoveCommonResultCode_UnmanagedExceptionAn unknown exception occurred during execution.OA temporary issue has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionAn internal exception occurred during executionOA temporary issue has occurred. Please try again. [OK]

Complete list: EStoveCommonResultCode, EStoveResultCode

Memory Management

ObjectOwnerRelease
outPathCallerThis is a buffer allocated by the caller. It is not a Destroy target.
Returned IStoveResult*CallerStove_IStoveTypeBase_Destroy((IStoveTypeBase*)result) Required

Example

c
wchar_t cloudPath[512] = { 0 };
IStoveResult* result = Stove_GetCloudSavingPath(cloudPath, 512);
if (Stove_IStoveResult_IsSuccessful(result))
{
    // Please implement the logic for when the operation succeeds. The cloud storage path is stored in `cloudPath`.
}
else
{
    // Please implement the logic for when an error occurs.
}

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result);

Notes

  • This function is synchronous and does not accept callbacks.
  • This function is available only after the game has been released on Stove. Since no cloud save path is provided while the game is being tested by the studio, you cannot obtain the path during the development phase.
  • outPath If the buffer is smaller than the resulting string, the string is truncated and InvalidParam(5) is returned. Make sure to allocate a buffer that is large enough.

Stove_GetGds

Kind Function · Module Base · Version 3.5.0

Description

Retrieves the logged-in user's GDS (Country and Time Zone) information.

Declaration

c
IStoveResult* Stove_GetGds(IStoveGds** outGds);

Parameters

NameTypeRequiredDescription
outGdsIStoveGds**YThis is the variable that will receive the GDS information pointer. After use, you must call Destroy().

Returns

TypeDescription
IStoveResult*Here are the results of the call. If Stove_IStoveResult_GetResultCode() equals 0, the call was successful.

The method code for this function is k_EStoveBaseMethodCode_GetGds.

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
5k_EStoveCommonResultCode_InvalidParamoutGds is nullptr.x
16k_EStoveCommonResultCode_BaseNotInitializedIt was called before being initialized.x
253k_EStoveCommonResultCode_UnmanagedExceptionAn unknown exception occurred during execution.OA temporary issue has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionAn exception occurred during execution.OThere was a temporary issue. Please try again. [OK]

Complete list: EStoveCommonResultCode

Memory Management

ObjectOwnerRelease
*outGdsThe SDK is created, and ownership is transferred to the callerStove_IStoveTypeBase_Destroy((IStoveTypeBase*)gds) Required
Returned IStoveResult*CallerStove_IStoveTypeBase_Destroy() Required

Example

c
IStoveGds* gds = nullptr;
IStoveResult* result = Stove_GetGds(&gds);
if (Stove_IStoveResult_IsSuccessful(result))
{
    // Please implement the logic for a successful outcome.
    const wchar_t* nation = Stove_IStoveGds_GetNation(gds);
    const wchar_t* timezone = Stove_IStoveGds_GetTimezone(gds);

    Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)gds);
}
else
{
    // Please implement the logic for when an error occurs.
}

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result);

Notes

  • If the system cannot determine the country code from the IP address and uses the default country code instead, Stove_IStoveGds_IsDefault() returns true.

See Also


Stove_GetSignin

Kind Function · Module Base · Version 3.5.0

Description

Retrieves the sign-in information for the logged-in user.

Declaration

c
IStoveResult* Stove_GetSignin(IStoveSignin** outSignin);

Parameters

NameTypeRequiredDescription
outSigninIStoveSignin**YThis is the variable that will receive the registration information pointer. After use, you must call Destroy().

Returns

TypeDescription
IStoveResult*Here are the results of the call. If Stove_IStoveResult_GetResultCode() equals 0, the call was successful.

The method code for this function is k_EStoveBaseMethodCode_GetSignin.

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
5k_EStoveCommonResultCode_InvalidParamoutSignin is nullptr.x
16k_EStoveCommonResultCode_BaseNotInitializedIt was called before it was initialized.x
253k_EStoveCommonResultCode_UnmanagedExceptionAn unknown exception occurred during execution.OA temporary issue has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionAn exception occurred during execution.OThere was a temporary issue. Please try again. [OK]

Complete list: EStoveCommonResultCode

Memory Management

ObjectOwnerRelease
*outSigninThe SDK is created, and ownership is transferred to the callerStove_IStoveTypeBase_Destroy((IStoveTypeBase*)signin) Required
Returned IStoveResult*CallerStove_IStoveTypeBase_Destroy() Required

Example

c
IStoveSignin* signin = nullptr;
IStoveResult* result = Stove_GetSignin(&signin);
if (Stove_IStoveResult_IsSuccessful(result))
{
    // Please implement the logic for a successful outcome.
    bool personVerified = Stove_IStoveSignin_IsPersonVerified(signin);
    const wchar_t* providerCode = Stove_IStoveSignin_GetProviderCode(signin);

    Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)signin);
}
else
{
    // Please implement the logic for when an error occurs.
}

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result);

Notes

  • Account types (Stove_IStoveSignin_GetAccountType()) are provided as numeric codes. For example: 2 = Facebook, 3 = Twitter, 6 = Naver, 9 = Google+, 11 = Stove PC registration, 12 = Apple, 13 = LINE, 14 = LINE Games, 15 = Steam, 16 = VTCO, etc. However, since the published specifications do not explicitly define a fixed value-meaning mapping table, use Stove_IStoveSignin_GetProviderCode() when identifying IDP types (e.g., distinguishing between STEAM and STEAM_SHADOW).

See Also


Stove_GetUser

Kind Function · Module Base · Version 3.5.0

Description

Retrieves information about the logged-in user.

Declaration

c
IStoveResult* Stove_GetUser(IStoveUser** outUser);

Parameters

NameTypeRequiredDescription
outUserIStoveUser**YThis is the variable that will receive the user information pointer. After use, you must call Destroy().

Returns

TypeDescription
IStoveResult*Here are the results of the call. If Stove_IStoveResult_GetResultCode() equals 0, the call was successful.

The method code for this function is k_EStoveBaseMethodCode_GetUser.

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
5k_EStoveCommonResultCode_InvalidParamoutUser is nullptr.x
16k_EStoveCommonResultCode_BaseNotInitializedIt was called before being initialized.x
253k_EStoveCommonResultCode_UnmanagedExceptionAn unknown exception occurred during execution.OA temporary issue has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionAn exception occurred during execution.OThere was a temporary issue. Please try again. [OK]

Complete List: EStoveCommonResultCode

Memory Management

ObjectOwnerRelease
*outUserThe SDK is created, and ownership is transferred to the callerStove_IStoveTypeBase_Destroy((IStoveTypeBase*)user) Required
Returned IStoveResult*CallerStove_IStoveTypeBase_Destroy() Required

Example

c
IStoveUser* user = nullptr;
IStoveResult* result = Stove_GetUser(&user);
if (Stove_IStoveResult_IsSuccessful(result))
{
    // Please implement the logic for a successful outcome.
    const wchar_t* nickName = Stove_IStoveUser_GetNickName(user);
    uint64_t userId = Stove_IStoveUser_GetUserId(user);

    Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)user);
}
else
{
    // Please implement the logic for when an error occurs.
}

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result);

Notes

  • The logged-in user's country and region information is retrieved separately via Stove_GetGds, and their registration information via Stove_GetSignin.

See Also


Stove_GetVersion

Kind Function · Module Base · Version 3.5.0

Description

This is a synchronous function that retrieves SDK version information.

Declaration

c
IStoveResult* Stove_GetVersion(wchar_t* outVersion, uint32_t length);

Parameters

NameTypeRequiredDescription
outVersionwchar_t*YThis is the buffer that will receive the version string. It is preallocated by the caller.
lengthuint32_tYoutVersion is the length (in characters) of the buffer.

Returns

TypeDescription
IStoveResult*Here are the results of the call. A value of Stove_IStoveResult_IsSuccessful(result) indicates success.

The method code for this function is k_EStoveBaseMethodCode_BaseGetVersion.

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
5k_EStoveCommonResultCode_InvalidParamoutVersion is nullptr, length is 0, or the buffer is too small, causing the version string to be truncated (STRUNCATE)x
251k_EStoveCommonResultCode_PcsdkDllNotFoundThe DLL path was not found in the executable file pathx
253k_EStoveCommonResultCode_UnmanagedExceptionAn unknown exception occurred during execution.OA temporary problem has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionAn internal exception occurred during executionOA temporary issue has occurred. Please try again. [OK]

Complete list: EStoveCommonResultCode, EStoveResultCode

Memory Management

ObjectOwnerRelease
outVersionCallerThis buffer was allocated by the caller. It is not a target for destruction.
Returned IStoveResult*CallerStove_IStoveTypeBase_Destroy((IStoveTypeBase*)result) Required

Example

c
wchar_t version[64] = { 0 };
IStoveResult* result = Stove_GetVersion(version, 64);
if (Stove_IStoveResult_IsSuccessful(result))
{
    // Please implement the logic for when the operation succeeds. The `version` variable contains the version string.
}
else
{
    // Please implement the logic for when an error occurs.
}

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result);

Notes

  • This function is synchronous and does not accept callbacks.

Stove_Initialize

Kind Function · Module Base · Version 3.5.0

Description

Initializes the SDK. Following the consolidation into a single binary (BaseSDK Consolidation), this function also handles the initialization of the View module and the IAP module.

The SDK reuses the environment, game ID, and app key values cached by Stove_RestartAppIfNecessary(). In addition, if the main window handle (SetMainWndHandle) is set in initParam, the View module is initialized, and if the store key (SetShopKey) is also set, the IAP module is initialized as well. If initParam is passed to nullptr, only the SDK is initialized.

If the initialization fails, the SDK may remain partially initialized (e.g., the SDK and View are initialized, but IAP fails). In this case, you must call Stove_Uninitialize() and then retry Stove_Initialize() from a clean state. If you call it again without Uninitialize, ALREADY_INITIALIZED will be returned, and the initialization of the module that failed will not be retried.

Declaration

c
IStoveResult* Stove_Initialize(const IStoveInitializeParam* initParam);

Parameters

NameTypeRequiredDescription
initParamIStoveInitializeParam*NThis is initialization information. If you pass nullptr, only the SDK will be initialized.

Returns

TypeDescription
IStoveResult*Here are the results of the call. If Stove_IStoveResult_GetResultCode() is 0, the call was successful. You can use Stove_IStoveResult_GetMethodCode() to determine which module caused the failure.

The method code for this function is k_EStoveBaseMethodCode_BaseInitialize.

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
5k_EStoveCommonResultCode_InvalidParamAt least one of the following is empty: environment, game ID, or app key (check the value passed when calling Stove_RestartAppIfNecessary()).x
18k_EStoveCommonResultCode_AlreadyInitializedIt is already initialized.x
304k_EStoveResultCode_NeedStoveLauncherYou must first call Stove_RestartAppIfNecessary() to complete the launcher connection.OThe game is closing because it is not running through the Stove PC client. Please launch the game again from the client. If you do not have the client installed, please install it from the Stove website.[OK]
251k_EStoveCommonResultCode_PcsdkDllNotFoundThe result of the failed internal version lookup (GetVersion) was returned as-is.x
253k_EStoveCommonResultCode_UnmanagedExceptionAn unknown exception occurred during execution.OA temporary problem has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionAn exception occurred during execution (including lower-level errors such as failure to parse required information).OThere was a temporary issue. Please try again. [OK]

If you receive the code below, you must exit the game. The game cannot proceed normally.

  • 304 k_EStoveResultCode_NeedStoveLauncher, This is not running via the Stove PC client, so it needs to be restarted.

At the lower level (token processing logic), k_EStoveCommonResultCode_Fail(1) or k_EStoveResultCode_NotFoundRequiredInformation(302) may be passed.

Complete list: EStoveCommonResultCode, EStoveResultCode

Memory Management

ObjectOwnerRelease
initParamCallerIf delivered, Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)initParam) Required
Returned IStoveResult*CallerStove_IStoveTypeBase_Destroy() Required

Example

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

IStoveResult* result = Stove_Initialize(initParam);
if (Stove_IStoveResult_IsSuccessful(result))
{
    // Please implement the logic for a successful outcome.
}
else
{
    // Please implement the logic for when an error occurs.
    // Use Stove_IStoveResult_GetMethodCode() or Stove_IStoveResult_GetResultCode() to determine which module failed.
}

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

Notes

  • If you set the main window handle in initParam, the View module is initialized along with it, and if you also set the store key, the IAP module is initialized as well.
  • When retrying after a failure, you must first call Stove_Uninitialize().
  • If you call Stove_RestartAppIfNecessary() first, it will reuse the cached environment, game ID, and app key values from that call.

See Also


Stove_OpenExternalUrl

Kind Function · Module Base · Version 3.5.0

Description

Opens the URL in an external browser. When opening an Onstove-related domain (e.g., *.onstove.com), SSO processing is performed at the same time.

Declaration

c
void Stove_OpenExternalUrl(const wchar_t* url, OnOpenExternalUrlCallback onFinished, void* userData);

Parameters

NameTypeRequiredDescription
urlconst wchar_t*YThis is the URL you want to open.
onFinishedOnOpenExternalUrlCallbackYThis is the callback that will receive the results.
userDatavoid*NThis is the user data that is passed directly to the callback.

Returns

None

The method code for this function is k_EStoveBaseMethodCode_OpenExternalUrl.

Callback

c
typedef void(__cdecl* OnOpenExternalUrlCallback)(const IStoveCallbackResult* callbackResult, const IStoveTypeBase* reserved);
NameTypeDescription
callbackResultconst IStoveCallbackResult*Here are the results of the call.
reservedconst IStoveTypeBase*This is a reserved field with a predefined number of parameters to accommodate future expansion. In the current SDK, it is always nullptr.

The callback runs in the thread that called Stove_RunCallback() (or Stove_RunCallbackWithTimeout()).

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccess (URL opened successfully in the browser)x
5k_EStoveCommonResultCode_InvalidParamonFinished is nullptrx
16k_EStoveCommonResultCode_BaseNotInitializedThe SDK did not initializex
253k_EStoveCommonResultCode_UnmanagedExceptionThe browser failed to launch, or an unknown exception occurred while it was running.OA temporary issue has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionAn internal exception occurred during executionOA temporary issue has occurred. Please try again. [OK]

If the internal lookup for the SSO key (simKey) fails when opening an Onstove-related domain, the resulting code is passed down to the lower layers as-is.

Complete list: EStoveCommonResultCode, EStoveResultCode

Memory Management

ObjectOwnerRelease
urlCallerThis is a string argument. It is not a target for destruction.
Callback callbackResult, reservedSDKDo not unlock. This will be invalidated once the callback is complete.

Example

c
void OnOpenExternalUrl(const IStoveCallbackResult* callbackResult, const IStoveTypeBase* reserved)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);
    if (Stove_IStoveResult_IsSuccessful(result))
    {
        // Please implement the logic for a successful outcome.
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

Stove_OpenExternalUrl(L"https://www.onstove.com", OnOpenExternalUrl, nullptr);

// The callback will be delivered only if it is called periodically within the game loop.
Stove_RunCallback();

Notes

  • When opening Onstove-related domains (such as *.onstove.com), SSO is handled at the same time.
  • The reserved argument of the callback is currently always nullptr. You can check if (reserved) to see if it will be extended in the future.

Stove_OverImmersionNotification

Kind Function · Module Base · Version 3.5.0

Description

This service sends hourly reminders via callback to users subject to South Korea's regulations on preventing excessive use. This API is exclusive to South Korea.

This callback is not a one-time event; it is sent to the target user repeatedly every hour.

Declaration

c
void Stove_OverImmersionNotification(const IStoveTypeBase* param, OnOverImmersionNotificationCallback onFinished, void* userData);

Parameters

NameTypeRequiredDescription
paramconst IStoveTypeBase*NAs a reserved argument, a dedicated TypeKind has not been defined.
onFinishedOnOverImmersionNotificationCallbackYThis is the callback that will receive the results.
userDatavoid*NThis is the user data that is passed directly to the callback.

Returns

None

The method code for this function is k_EStoveBaseMethodCode_OverImmersionNotification.

Callback

c
typedef void(__cdecl* OnOverImmersionNotificationCallback)(const IStoveCallbackResult* callbackResult, const IStoveOverImmersionInfo* overImmersion);
NameTypeDescription
callbackResultconst IStoveCallbackResult*Here are the results of the call.
overImmersionconst IStoveOverImmersionInfo*This is information regarding the anti-excessive-play alert. It provides the warning message (GetMsg()), cumulative playtime (GetElapsedHours(), in hours), and message display duration (GetExposureTime(), in seconds).

The callback runs in the thread that called Stove_RunCallback() (or Stove_RunCallbackWithTimeout()). It is delivered to the target user repeatedly every hour.

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
5k_EStoveCommonResultCode_InvalidParamonFinished is nullptrx
16k_EStoveCommonResultCode_BaseNotInitializedThe SDK did not initializex
31k_EStoveCommonResultCode_NotSupportedCountryThe GDS country code for the login account is not South Korea (kr)x
253k_EStoveCommonResultCode_UnmanagedExceptionAn unknown exception occurred during execution.OThere was a temporary issue. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionAn internal exception occurred during executionOA temporary issue has occurred. Please try again. [OK]

Complete list: EStoveCommonResultCode, EStoveResultCode

Memory Management

ObjectOwnerRelease
paramCallerIf delivered, Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param) Required
Callback callbackResult, overImmersionSDKDo not unlock. This will be invalidated once the callback is complete.

Example

c
void OnOverImmersionNotification(const IStoveCallbackResult* callbackResult, const IStoveOverImmersionInfo* overImmersion)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);
    if (Stove_IStoveResult_IsSuccessful(result))
    {
        // Please implement the logic for the success case.
        const wchar_t* msg = Stove_IStoveOverImmersionInfo_GetMsg(overImmersion);
        int32_t exposureTime = Stove_IStoveOverImmersionInfo_GetExposureTime(overImmersion);
    }
    else
    {
        // Please implement the logic for when a failure occurs.
    }
}

Stove_OverImmersionNotification(nullptr, OnOverImmersionNotification, nullptr);

// The callback will be passed only if it is called periodically within the game loop.
Stove_RunCallback();

Notes

  • This API is for use in Korea only.
  • This is a callback that is sent repeatedly every hour to the target user. It is not a one-time callback.

See Also


Stove_RestartAppIfNecessary

Kind Function · Module Base · Version 3.5.0

Description

Checks whether the PCSDK was launched via the Stove launcher. If it was not launched via the launcher, the app will be relaunched through the launcher, and the current process will be terminated.

This function must be called before Stove_Initialize(). The environment, game ID, and app key values stored in initParam will be reused when Stove_Initialize() is called later.

If a re-run is required, the current process will terminate, so the code following this function call may not execute.

Declaration

c
void Stove_RestartAppIfNecessary(const IStoveRestartAppIfNecessaryParam* initParam, OnRestartAppIfNecessaryCallback onFinished, void* userData);

Parameters

NameTypeRequiredDescription
initParamIStoveRestartAppIfNecessaryParam*YThis information, such as Environment, Game ID, and App Key, is required to verify the launcher.
onFinishedOnRestartAppIfNecessaryCallbackYThis is the callback that will receive the results.
userDatavoid*NThis is the user data that is passed directly to the callback.

Returns

None

The method code for this function is k_EStoveBaseMethodCode_RestartAppIfNecessaryAsync.

Callback

c
typedef void(__cdecl* OnRestartAppIfNecessaryCallback)(const IStoveCallbackResult* callbackResult, const IStoveRestartAppIfNecessaryOutcome* outcome);
NameTypeDescription
callbackResultconst IStoveCallbackResult*Here are the results of the call.
outcomeconst IStoveRestartAppIfNecessaryOutcome*Whether re-execution is necessary. Check using Stove_IStoveRestartAppIfNecessaryOutcome_IsRestartRequired().

The callback runs in the thread that called Stove_RunCallback() (or Stove_RunCallbackWithTimeout()). The callback is also passed even if a re-execution is required.

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccess (IPC status reaches "Normal," or the previous call is confirmed to have already completed)x
29k_EStoveCommonResultCode_AsyncOperationInProgressThe previous asynchronous restart request is still being processed.x
30k_EStoveCommonResultCode_BaseUninitializedThe IPC state changed to an uninitialized state while waiting.x
307k_EStoveResultCode_IpcConnectFailedThe IPC connection to the launcher failed.OThe game is closing because it is not running through the Stove PC client. Please launch the game again from the client. If you do not have the client installed, please install it from the Stove website.[OK]
308k_EStoveResultCode_IpcAesKeyNotReceivedThe AES key was not received from the launcher.OThe game is closing because it is not running through the Stove PC client. Please launch the game again from the client. If you do not have the client installed, please install it from the Stove website.[OK]
309k_EStoveResultCode_IpcTimeoutThe timeout (waitTimeMillisec) has been exceeded.OThe game is closing because it is not running through the Stove PC client. Please launch the game again from the client. If you do not have the client installed, please install it from the Stove website.[OK]
253k_EStoveCommonResultCode_UnmanagedExceptionAn unknown exception occurred during execution.OA temporary problem has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionAn exception occurred during execution.OA temporary issue has occurred. Please try again. [OK]

If you receive the code below, you must exit the game. The game cannot proceed normally.

  • 307 k_EStoveResultCode_IpcConnectFailed, Connection to the launcher failed; please try again.
  • 308 k_EStoveResultCode_IpcAesKeyNotReceived, Failed to establish communication with the launcher; a retry is required
  • 309 k_EStoveResultCode_IpcTimeout, Communication with the launcher timed out; a retry is required

Complete list: EStoveCommonResultCode, EStoveResultCode

Memory Management

ObjectOwnerRelease
initParamCallerStove_IStoveTypeBase_Destroy((IStoveTypeBase*)initParam) Required
Callback callbackResult, outcomeSDKDo not unlock. This will be invalidated once the callback is complete.

Example

c
IStoveRestartAppIfNecessaryParam* initParam = (IStoveRestartAppIfNecessaryParam*)Stove_CreateParam(k_EStoveBaseTypeKind_RestartAppIfNecessaryParam);
Stove_IStoveRestartAppIfNecessaryParam_SetEnvironment(initParam, L"REAL");
Stove_IStoveRestartAppIfNecessaryParam_SetGameId(initParam, L"YOUR_GAME_ID");
Stove_IStoveRestartAppIfNecessaryParam_SetAppKey(initParam, L"YOUR_APP_KEY");

Stove_RestartAppIfNecessary(initParam, [](const IStoveCallbackResult* callbackResult, const IStoveRestartAppIfNecessaryOutcome* outcome)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);
    if (Stove_IStoveResult_IsSuccessful(result))
    {
        // Please implement the logic for a successful outcome.
        if (!Stove_IStoveRestartAppIfNecessaryOutcome_IsRestartRequired(outcome))
        {
            // If no re-execution is necessary, proceed by calling Stove_Initialize().
        }
    }
    else
    {
        // Please implement the logic for when a failure occurs.
    }
}, nullptr);

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)initParam);

Notes

  • It must be called before Stove_Initialize().
  • If the app needs to be rerun, it will be launched again through the launcher, and the current process will be terminated.
  • The environment, game ID, and app key values used in this function are reused by Stove_Initialize().

See Also


Stove_RunCallback

Kind Function · Module Base · Version 3.5.0

Description

This dispatches the result (callback function) of an asynchronous API call. It must be called from the game's UI (main) thread.

All asynchronous API callbacks throughout the SDK are passed exclusively through this function (or Stove_RunCallbackWithTimeout). Callbacks are executed on the thread that called this function, not on an internal SDK thread.

This function must be called periodically within the game loop (e.g., every frame or every tick). Do not use it by repeatedly calling only this function in the form while(true).

Declaration

c
void Stove_RunCallback();

Parameters

None

Returns

None

Error Codes

None

Memory Management

This function does not create or return a separate object.

Example

c
// Example of a Game Loop
while (isGameRunning)
{
    // ... Game Logic ...

    Stove_RunCallback();

    // ... rendering and the rest of the loop logic ...
}

Notes

  • Callbacks for all asynchronous APIs are executed on the thread that called this function.
  • Callbacks must be called periodically within the game loop to ensure they are processed without delay.
  • To specify a wait time, use Stove_RunCallbackWithTimeout.

See Also


Stove_RunCallbackWithTimeout

Kind Function · Module Base · Version 3.5.0

Description

This is the timeout version of Stove_RunCallback. You can set the wait time to timeoutMillisec.

This function must be called from the game's UI (main) thread, and any registered callbacks will execute on the thread that called this function.

Declaration

c
void Stove_RunCallbackWithTimeout(uint32_t timeoutMillisec);

Parameters

NameTypeRequiredDescription
timeoutMillisecuint32_tYThis is the wait time (in milliseconds).

Returns

None

Error Codes

None

Memory Management

This function does not create or return a separate object.

Example

c
// Game Loop Example (Maximum 10 ms Wait)
while (isGameRunning)
{
    // ... Game Logic ...

    Stove_RunCallbackWithTimeout(10);

    // ... the rest of the loop logic, such as rendering ...
}

Notes

  • Callbacks for all asynchronous APIs are executed on the thread that called this function.
  • Use Stove_RunCallback for general purposes, and use this function when you need to control the wait time.

See Also


Stove_SendLog

Kind Function · Module Log · Version 3.5.0

Description

Sends a single log entry to the STOVE log backend. The value stored in logSendParam is sent as-is as the log entry.

The log feature does not have separate initialization or termination APIs. Since the SDK handles lifecycle management, you can call it immediately after Stove_Initialize() succeeds.

onFinished The callback is **called with a "SUCCESS" result immediately after the log is saved to the local database. The HTTP transmission to the actual server is handled via a separate internal forwarding path, and the result (whether successful or not) is never passed to this callback.

Declaration

c
void Stove_SendLog(const IStoveSendLogParam* logSendParam, OnSendLogCallback onFinished, void* userData);

Parameters

NameTypeRequiredDescription
logSendParamconst IStoveSendLogParam*YThis is the value of the log entry to be transmitted. It is generated as Stove_CreateParam(k_EStoveLogTypeKind_SendLogParam).
onFinishedOnSendLogCallbackYThis is the callback that receives the transmission results.
userDatavoid*NThis is the user data that is passed directly to the callback.

Returns

None

The method code for this function is k_EStoveLogMethodCode_SendLog.

Callback

c
typedef void(__cdecl* OnSendLogCallback)(const IStoveCallbackResult* callbackResult, const IStoveTypeBase* reserved);
NameTypeDescription
callbackResultconst IStoveCallbackResult*These are the results of the transmission call. They only indicate whether the data was successfully saved to the local database; they do not reflect the actual results of the transmission to the server.
reservedconst IStoveTypeBase*This is a reserved slot where the number of callback arguments is pre-set to accommodate future payload expansion. In the current SDK, this value is always nullptr. You can check whether the value exists by checking for if (reserved).

The callback runs in the thread that called Stove_RunCallback(). For each call to Stove_SendLog(), the callback is invoked once when a log entry is written (or a write fails) to the local database.

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessThe log record has been successfully inserted into the local database (this does not mean that the data has been successfully transferred to the production server).x
5k_EStoveCommonResultCode_InvalidParamonFinished is nullptr, or contents is not empty, but this is not valid JSON.x
17k_EStoveCommonResultCode_NotInitializedThe SDK has not been initialized.x
44k_EStoveCommonResultCode_LocalDbWriteFailedFailed to write a log record to the local database (formerly known as LOCAL_DB_BACKUP_LOG_FAILED)x
82k_EStoveCommonResultCode_PayloadSizeExceededThe log content encoded in UTF-8 exceeded 50 KB (formerly known as LOG_SIZE_EXCEEDED)x
253k_EStoveCommonResultCode_UnmanagedExceptionAn unknown exception has occurred.OA temporary issue has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionA handled exception has occurredOA temporary issue has occurred. Please try again. [OK]

k_EStoveCommonResultCode_InvalidParam(5) is the result of INVALID_LOG_PARAMETER(85), which was previously code specific to the old LogSDK, being deprecated and incorporated into the general-purpose code.

There is code that is never passed to this callback. HTTP requests to the actual server are handled via a separate internal path after data has been saved to the local database, and this path is implemented so that failures are not separately reported to the game, so HttpError(22)·ResponseError(23)·ResponseValueIsNull(25)·NetworkTransportError(249)·UnmanagedException(253)·ManagedException(254, request layer), failures related to server communication are not passed to onFinished.

Complete list: EStoveCommonResultCode, EStoveResultCode

Memory Management

ObjectOwnerRelease
logSendParamCallerStove_IStoveTypeBase_Destroy((IStoveTypeBase*)logSendParam) Required. You can release it immediately after the call returns.
Callback callbackResultSDKDo not unlock. This will be invalidated once the callback is complete.
Callback reservedSDKThe current value is always nullptr. Even if a value is present, it must not be disabled, and it will be invalidated once the callback completes.

Example

c
IStoveSendLogParam* logSendParam = (IStoveSendLogParam*)Stove_CreateParam(k_EStoveLogTypeKind_SendLogParam);

Stove_IStoveSendLogParam_SetAuid(logSendParam, auid);
Stove_IStoveSendLogParam_SetCuid(logSendParam, cuid);
Stove_IStoveSendLogParam_SetContents(logSendParam, L"{\"event\":\"login\"}");

Stove_SendLog(logSendParam, OnSendLogFinished, nullptr);

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)logSendParam);

// ...

void __cdecl OnSendLogFinished(const IStoveCallbackResult* callbackResult, const IStoveTypeBase* reserved)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

    if (Stove_IStoveResult_IsSuccessful(result))
    {
        // This means the data was successfully saved to the local database. The actual result of the transmission to the server is unknown.
        // Please implement the logic for when the operation is successful.
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

// The callback will only be executed if it is called repeatedly within the game loop.
while (isGameRunning)
{
    Stove_RunCallback();
}

Notes

  • onFinished The callback does not reflect the actual server transmission results. The callback is triggered with a "SUCCESS" result as soon as the log is saved to the local database; the actual HTTP transmission is then handled subsequently via a separate internal retransmission path. Since failures in this path are not reported to the user callback, you should not misinterpret the success of this callback as meaning that "the log has arrived at the server."
  • If you do not know the value of a specific log entry, you do not need to fill in that field. Numeric fields will retain a default value of 0, and string fields will remain empty or set to nullptr.
  • Only the Stove_SendLog() logging feature is provided via the public API; the SDK handles initialization and termination.
  • The reserved argument of a callback is always a reserved parameter, nullptr. We recommend handling it defensively in the form of if (reserved) in anticipation of when the value will be populated.
  • Except for local DB storage failures (such as k_EStoveCommonResultCode_LocalDbWriteFailed in the table above), this callback virtually always returns a success. We recommend that you do not design your game logic to branch based on the result of this callback.

See Also


Stove_SetGameProfile

Kind Function · Module Base · Version 3.5.0

Description

This is a synchronous function that sets game profile information.

Declaration

c
IStoveResult* Stove_SetGameProfile(const IStoveSetGameProfileParam* gameProfileParams);

Parameters

NameTypeRequiredDescription
gameProfileParamsconst IStoveSetGameProfileParam*YThis is the game profile information. It is generated as Stove_CreateParam(k_EStoveBaseTypeKind_SetGameProfileParam).

Returns

TypeDescription
IStoveResult*Here are the results of the call. A value of Stove_IStoveResult_IsSuccessful(result) indicates success.

The method code for this function is k_EStoveBaseMethodCode_SetGameProfile.

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
5k_EStoveCommonResultCode_InvalidParamgameProfileParams is nullptrx
16k_EStoveCommonResultCode_BaseNotInitializedThe SDK did not initializex
253k_EStoveCommonResultCode_UnmanagedExceptionAn unknown exception occurred during execution.OA temporary issue has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionAn internal exception occurred during executionOA temporary issue has occurred. Please try again. [OK]

Complete list: EStoveCommonResultCode, EStoveResultCode

Memory Management

ObjectOwnerRelease
gameProfileParamsCallerStove_IStoveTypeBase_Destroy((IStoveTypeBase*)gameProfileParams) Required
Returned IStoveResult*CallerStove_IStoveTypeBase_Destroy((IStoveTypeBase*)result) Required

Example

c
IStoveSetGameProfileParam* gameProfileParams = (IStoveSetGameProfileParam*)Stove_CreateParam(k_EStoveBaseTypeKind_SetGameProfileParam);
Stove_IStoveSetGameProfileParam_SetWorldId(gameProfileParams, L"world_01");
Stove_IStoveSetGameProfileParam_SetCharacterNo(gameProfileParams, 12345);

IStoveResult* result = Stove_SetGameProfile(gameProfileParams);
if (Stove_IStoveResult_IsSuccessful(result))
{
    // Please implement the logic for a successful outcome.
}
else
{
    // Please implement the logic for when an error occurs.
}

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result);
Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)gameProfileParams);

Notes

  • IStoveSetGameProfileParam::GetCharacterNo() is the character ID within the world. The previous reference to this field as "worldId Length" in StoveGameProfileParams was a typographical error in the documentation.

See Also


Stove_SetLanguage

Kind Function · Module Base · Version 3.5.0

Description

This is a synchronous function that sets the language to be used by the PCSDK.

Declaration

c
IStoveResult* Stove_SetLanguage(const wchar_t* language);

Parameters

NameTypeRequiredDescription
languageconst wchar_t*YThis is a language information string.

Returns

TypeDescription
IStoveResult*Here are the results of the call. A value of Stove_IStoveResult_IsSuccessful(result) indicates success.

The method code for this function is k_EStoveBaseMethodCode_SetLanguage.

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
5k_EStoveCommonResultCode_InvalidParamlanguage is nullptr or an unsupported language codex
16k_EStoveCommonResultCode_BaseNotInitializedThe SDK did not initializex
253k_EStoveCommonResultCode_UnmanagedExceptionAn unknown exception occurred during execution.OA temporary issue has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionAn internal exception occurred during executionOA temporary issue has occurred. Please try again. [OK]

If the language code is unsupported, InvalidParam(5) is set at the lower level (LanguageActor).

Complete list: EStoveCommonResultCode, EStoveResultCode

Memory Management

ObjectOwnerRelease
languageCallerThis is a string argument. It is not a target for Destroy.
Returned IStoveResult*CallerStove_IStoveTypeBase_Destroy((IStoveTypeBase*)result) Required

Example

c
IStoveResult* result = Stove_SetLanguage(L"ko");
if (Stove_IStoveResult_IsSuccessful(result))
{
    // Please implement the logic for a successful outcome.
}
else
{
    // Please implement the logic for when an error occurs.
}

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result);

Notes

  • This function is synchronous and does not accept callbacks.

Stove_SetStat

Kind Function · Module GameSupport · Version 3.5.0

Description

Stove_SetStat() is a function that updates the value of the specified statistic (Stat) to a new value. The result of the update is passed to the onFinished callback.

The statistics and achievements features do not have a separate initialization procedure; their lifecycle is tied to the SDK initialization. Call them after Stove_Initialize() has succeeded.

Declaration

c
void Stove_SetStat(const IStoveSetStatParam* param, OnSetStatCallback onFinished, void* userData);

Parameters

NameTypeRequiredDescription
paramconst IStoveSetStatParam*YA parameter containing the ID of the statistic to be modified and the new value. It is created as Stove_CreateParam(k_EStoveGameSupportTypeKind_SetStatParam).
onFinishedOnSetStatCallbackYCallback to receive the update results
userDatavoid*NUser data passed directly to the callback

Returns

None (void)

The method code for this function is k_EStoveGameSupportMethodCode_SetStat.

Callback

c
typedef void(__cdecl* OnSetStatCallback)(const IStoveCallbackResult* callbackResult, const IStoveSetStatOutcome* statOutcome);
NameTypeDescription
callbackResultconst IStoveCallbackResult*Call Results
statOutcomeconst IStoveSetStatOutcome*Information on Revision Results

This callback runs in the thread that called Stove_RunCallback(). It is passed only once per call to Stove_SetStat().

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
5k_EStoveCommonResultCode_InvalidParamThe statistics ID (StatsId) for param is an empty stringx
253k_EStoveCommonResultCode_UnmanagedExceptionAn unknown exception occurred during processingOA temporary issue has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionAn internal exception occurred during processing (e.g., failure to retrieve an entity)OA temporary issue has occurred. Please try again. [OK]

Errors corresponding to HTTP communication failures (HttpError=22, ResponseError=23, ResponseInvalidCode=24, ResponseValueIsNull=25, ResponseInvalidValueFormat=26, NetworkTransportError=249) are not set directly by this function but are passed from the lower communication layer.

The old interface (GameSupport_ModifyStat) has a separate gate that returns NotInitialized (17) when the module is not initialized, but the new flat C surface, Stove_SetStat(), does not have this gate. In other words, this function does not return 17.

Complete list: EStoveCommonResultCode

Memory Management

ObjectOwnerRelease
paramCallerStove_IStoveTypeBase_Destroy((IStoveTypeBase*)param) Required (Can be released immediately after the Stove_SetStat() call returns)
Callback callbackResultSDKDo not unlock. This will be invalidated once the callback is complete.
Callback statOutcomeSDKDo not unlock. This will be invalidated once the callback is complete.

Example

c
void OnSetStatFinished(const IStoveCallbackResult* callbackResult, const IStoveSetStatOutcome* statOutcome)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);

    if (Stove_IStoveResult_IsSuccessful(result) && statOutcome != NULL && Stove_IStoveSetStatOutcome_IsUpdated(statOutcome))
    {
        int32_t currentValue = Stove_IStoveSetStatOutcome_GetCurrentValue(statOutcome);

        // Please implement the logic for a successful outcome.
    }
    else
    {
        // Please implement the logic for when the operation fails.
    }
}

IStoveSetStatParam* param =
    (IStoveSetStatParam*)Stove_CreateParam(k_EStoveGameSupportTypeKind_SetStatParam);
Stove_IStoveSetStatParam_SetStatsId(param, L"KILL_COUNT");
Stove_IStoveSetStatParam_SetStatValue(param, 10);

Stove_SetStat(param, OnSetStatFinished, NULL);

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param);

Notes

  • This function executes the underlying logic immediately without checking whether it has been initialized. If called before initialization, it may result in ManagedException(254).
  • StatValue does not represent an increment or decrement added to or subtracted from the existing value; rather, it replaces (sets) the statistical value with this value exactly as is. For example, if the current value is 10 and you enter 5 in StatValue, the result will be 5, not 15. To accumulate the value, you must first retrieve the current value using Stove_FetchStat before the call, add the new value to it, and then pass the result.
  • To look up statistical values, use Stove_FetchStat.
  • To verify whether the value has actually been updated, you should check IStoveSetStatOutcome::IsUpdated() rather than the callback result code.
  • If you set the same value again, the call succeeds, but the result IsUpdated() is returned as false. This is not an error.
  • The format of the statistics ID for param is [A-Z0-9\-_]*$ (uppercase letters, numbers, underscores, and hyphens).
  • The statistics and achievements features are available exclusively in the Store.
  • If the value you are trying to set exceeds the int32 range, it will be truncated to 2147483647. The call will still succeed, and IStoveSetStatOutcome::IsUpdated() will be true.
  • You can check whether the value has been truncated by seeing if integer overflow is stored in IStoveSetStatOutcome::GetErrorMessage().

See Also


Stove_ShutdownNotification

Kind Function · Module Base · Version 3.5.0

Description

A shutdown notification is sent via callback to users subject to the shutdown.

This API is not limited to South Korea. It works for users outside of South Korea as well, provided their accounts are subject to the shutdown policy.

Declaration

c
void Stove_ShutdownNotification(const IStoveTypeBase* param, OnShutdownNotificationCallback onFinished, void* userData);

Parameters

NameTypeRequiredDescription
paramconst IStoveTypeBase*NAs a reserved argument, a dedicated TypeKind has not been defined.
onFinishedOnShutdownNotificationCallbackYThis is the callback that will receive the results.
userDatavoid*NThis is the user data that is passed directly to the callback.

Returns

None

The method code for this function is k_EStoveBaseMethodCode_ShutdownNotification.

Callback

c
typedef void(__cdecl* OnShutdownNotificationCallback)(const IStoveCallbackResult* callbackResult, const IStoveShutdownInfo* shutdown);
NameTypeDescription
callbackResultconst IStoveCallbackResult*Here are the results of the call.
shutdownconst IStoveShutdownInfo*This is shutdown notification information. It provides the notification message (GetMsg()), the message display duration (GetExposureTime(), in seconds), and the time remaining until shutdown (GetInadvanceMinutes(), in minutes).

The callback runs in the thread that called Stove_RunCallback() (or Stove_RunCallbackWithTimeout()).

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
5k_EStoveCommonResultCode_InvalidParamonFinished is nullptrx
16k_EStoveCommonResultCode_BaseNotInitializedThe SDK did not initializex
253k_EStoveCommonResultCode_UnmanagedExceptionAn unknown exception occurred during execution.OA temporary issue has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionAn internal exception occurred during executionOA temporary issue has occurred. Please try again. [OK]

This API has no country restrictions (NotSupportedCountry). If your account is subject to a shutdown, it will function the same way even when accessed from overseas.

Complete list: EStoveCommonResultCode, EStoveResultCode

Memory Management

ObjectOwnerRelease
paramCallerIf delivered, Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param) Required
Callback callbackResult, shutdownSDKDo not unlock. This will be invalidated once the callback is complete.

Example

c
void OnShutdownNotification(const IStoveCallbackResult* callbackResult, const IStoveShutdownInfo* shutdown)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);
    if (Stove_IStoveResult_IsSuccessful(result))
    {
        // Please implement the logic for a successful outcome.
        const wchar_t* msg = Stove_IStoveShutdownInfo_GetMsg(shutdown);
        int32_t inadvanceMinutes = Stove_IStoveShutdownInfo_GetInadvanceMinutes(shutdown);
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

Stove_ShutdownNotification(nullptr, OnShutdownNotification, nullptr);

// The callback will be passed only if it is called periodically within the game loop.
Stove_RunCallback();

Notes

  • This API is not exclusive to South Korea. If your account is subject to the shutdown policy, it will work even from overseas.
  • This callback is not a one-time event. Once registered, it will be called repeatedly, once at each of the advance notification times specified by the server (e.g., 30 minutes before shutdown, 10 minutes before shutdown, etc.), and once at the actual shutdown time, up to the number of times specified by the server.

See Also


Stove_StartPurchase

Kind Function · Module IAP · Version 3.5.0

Description

We will begin the purchase process for the list of items in the order sent via params. The procedure will vary depending on the value of Operation (EStovePurchaseOperation) in IStovePurchaseParam, which is contained in params.

  • Default: Stove Webview is not used. The caller must retrieve the one-time payment URL from the results returned by onFinished and open the payment page directly; after payment, the caller must call Stove_ConfirmPurchase to confirm the purchase.
  • WithWebView: Opens the Stove payment page within the Stove Webview. In this case as well, once the payment is complete, the caller must call Stove_ConfirmPurchase to confirm the purchase.
  • WithWebViewAndConfirmResult: The Stove payment page opens within the Stove Webview, and upon successful payment, the SDK automatically calls Stove_ConfirmPurchase and returns the confirmed purchase result to onFinished. In this case, the caller does not need to call Stove_ConfirmPurchase separately.

For all failures (such as failure to initialize, parameter validation failure, exceptions, etc.) in which the WebView is not created at all and the call terminates, onDestroy is called once along with PopupNotCreated (33). For more details, refer to the "Error Codes and Callbacks" section.

Declaration

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

Parameters

NameTypeRequiredDescription
paramsconst IStoveStartPurchaseParam*YThis is a list of ordered items and purchase action parameters.
onFinishedOnStartPurchaseCallbackYThis is the callback that will receive the purchase results.
onDestroyOnIAPPopupDestroyCallbackNThis is a callback that is called when all pop-ups created by the SDK have been closed.
userData1void*NThis is user data that is passed directly to onFinished.
userData2void*NThis is user data that is passed directly to onDestroy.

Returns

None

The method code for this function is k_EStoveIAPMethodCode_StartPurchase.

Callback

c
typedef void(__cdecl* OnStartPurchaseCallback)(const IStoveCallbackResult* callbackResult, const IStoveStartPurchaseOutcome* outcome);

typedef void(__cdecl* OnIAPPopupDestroyCallback)(const IStoveCallbackResult* callbackResult, const IStoveTypeBase* reserved);
NameTypeDescription
callbackResultconst IStoveCallbackResult*Here are the results of the call.
outcomeconst IStoveStartPurchaseOutcome*Here are the purchase results (IStovePurchaseResult in the old interface has been renamed to this). Which fields are populated depends on the value of Operation (see Overview).
reservedconst IStoveTypeBase*This is a reserved parameter. It is currently always nullptr.

Both callbacks run on the thread that called Stove_RunCallback().

  • onFinished is passed only once per call.
  • onDestroy is passed once after all pop-ups created by this call have been closed. Even if no pop-ups are created and the call terminates, it is called once with the result code PopupNotCreated (33).

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
17k_EStoveCommonResultCode_NotInitializedThe payment feature is not initialized.x
60k_EStoveCommonResultCode_ViewUiNotInitializedOperation is not Default, so the payment web view needs to be opened, but the web view/pop-up UI subsystem has not been initialized.x
65k_EStoveCommonResultCode_WebviewCloseAllFailBefore opening the new payment webview, the system failed to close all previously open IAP webviews.x
62k_EStoveCommonResultCode_WebviewCreateFailThe attempt to create the payment web view failed.x
63k_EStoveCommonResultCode_WebviewLoadUrlFailThe payment page URL could not be loaded in the payment webview.x
34k_EStoveCommonResultCode_WebviewClosedBeforeCompleteWithWebViewAndConfirmResult The WebView closed before a payment completion notification was received from the payment flow (e.g., user cancellation).OThe purchase was not completed successfully. Please try again. [OK]
66k_EStoveCommonResultCode_WebviewCloseFailAn internal closure process failed while the WebView was closing normally. This error is logged as onDestroy, not onFinished.x
80k_EStoveCommonResultCode_ParameterLengthExceededServiceTxnNo exceeds 50 characters, or ExtraData exceeds 500 characters.OThe payment information is invalid, so we cannot process the payment. Please try again. [OK]
81k_EStoveCommonResultCode_InvalidJsonStringExtraData is not empty, but it is not in JSON format.OThe payment information is invalid, so we cannot process the payment. Please try again. [OK]
503k_EStoveResultCode_InvalidOrderProductInformationThere are items in your order with a quantity of 0 or less, or with a selling price (SalePrice) that is negative.OThe payment information is invalid, so we cannot process the payment. Please try again. [OK]
252k_EStoveCommonResultCode_NotImplementedThe value of Operation for IStovePurchaseParam is not one of the known values (Default/WithWebView/WithWebViewAndConfirmResult).x
253k_EStoveCommonResultCode_UnmanagedExceptionAn unhandled exception occurred during execution.OA temporary issue has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionA managed exception occurred during execution (including missing internal entities such as login tokens).OA temporary issue has occurred. Please try again. [OK]
33k_EStoveCommonResultCode_PopupNotCreatedThe call ended without a popup being created. It is passed only to onDestroy.x

Network/server response errors are passed down through the lower HTTP layers.

In the case of Operation == WithWebViewAndConfirmResult, the SDK automatically calls Stove_ConfirmPurchase after a successful payment. If the confirmation fails at this point, the result code may be passed directly to onFinished in this function. Please also refer to the error codes in the Stove_ConfirmPurchase documentation.

Complete list: EStoveCommonResultCode, EStoveResultCode

Memory Management

ObjectOwnerRelease
paramsCallerStove_IStoveTypeBase_Destroy((IStoveTypeBase*)params) Required. Release it after the call returns.
Each IStoveOrderProductParam contained in paramsCallerThe caller retains ownership and must Destroy() after the call returns.
params contains IStovePurchaseParamCallerThe caller retains ownership and must Destroy() after the call returns.
Callback callbackResultSDKDo not unlock. This will be invalidated once the callback is complete.
Callback outcomeSDKDo not unwrap. This will be invalidated once the callback completes, so you must copy any necessary values within the callback.

Example

c
void __cdecl OnStartPurchaseFinished(const IStoveCallbackResult* callbackResult, const IStoveStartPurchaseOutcome* outcome)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);
    if (Stove_IStoveResult_IsSuccessful(result))
    {
        // Please implement the logic for a successful outcome.
        // If Operation == Default, open the payment page using TempPaymentUrl, and
        // After completing the payment, you must call Stove_ConfirmPurchase() to finalize the purchase.
        int64_t txnMasterNo = Stove_IStoveStartPurchaseOutcome_GetTxnMasterNo(outcome);
        const wchar_t* tempPaymentUrl = Stove_IStoveStartPurchaseOutcome_GetTempPaymentUrl(outcome);
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

void __cdecl OnStartPurchasePopupDestroyed(const IStoveCallbackResult* callbackResult, const IStoveTypeBase* reserved)
{
    // Please implement logic that closes all pop-ups opened during the purchase process.
    // Even if a popup was not created (PopupNotCreated, 33), this event is passed to this callback, and it is safe to ignore it.
}

// Call
IStoveOrderProductParam* orderProduct = (IStoveOrderProductParam*)Stove_CreateParam(k_EStoveIAPTypeKind_OrderProductParam);
Stove_IStoveOrderProductParam_SetProductId(orderProduct, productId);
Stove_IStoveOrderProductParam_SetSalePrice(orderProduct, salePrice);
Stove_IStoveOrderProductParam_SetQuantity(orderProduct, 1);

IStovePurchaseParam* purchaseParam = (IStovePurchaseParam*)Stove_CreateParam(k_EStoveIAPTypeKind_PurchaseParam);
Stove_IStovePurchaseParam_SetOperation(purchaseParam, k_EStovePurchaseOperation_Default);

IStoveOrderProductParam* orderProducts[] = { orderProduct };
IStoveStartPurchaseParam* params = (IStoveStartPurchaseParam*)Stove_CreateParam(k_EStoveIAPTypeKind_StartPurchaseParam);
Stove_IStoveStartPurchaseParam_SetProducts(params, orderProducts, 1);
Stove_IStoveStartPurchaseParam_SetPurchaseParam(params, purchaseParam);

Stove_StartPurchase(params, OnStartPurchaseFinished, OnStartPurchasePopupDestroyed, nullptr, nullptr);

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)params);
Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)purchaseParam);
Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)orderProduct);

Notes

  • This function is asynchronous, and the result is returned only via the onFinished callback.
  • Purchases starting with Operation, Default, or WithWebView must be finalized by calling Stove_ConfirmPurchase. The SDK automatically handles the finalization of WithWebViewAndConfirmResult.
  • You can use the PurchaseProgress (EStovePurchaseProgress) value of outcome to determine whether to open the payment window directly.
  • In the old interface, when creating a params·product·option object, the value names did not include underscores (k_EStoveIAPTypeKindStartPurchaseParam), and the result type name was IStovePurchaseResult. These have now been changed to k_EStoveIAPTypeKind_StartPurchaseParam and IStoveStartPurchaseOutcome, respectively.
  • There is no parameter or option that distinguishes the Steam launcher flow from the STOVE launcher flow. There is also no developer-side setting that decides whether a Steam-based launch shows the payment window (a STOVE launcher feature) or the Steam overlay; if a Steam user ID (SteamUserId) was passed when the External Platform Integration Module was initialized, the SDK automatically uses the Steam payment flow (Steam overlay). See the Steam Payment section of the Payment guide for details.

See Also


Stove_Uninitialize

Kind Function · Module Base · Version 3.5.0

Description

We are deprecating (removing) the SDK. This function is paired with Stove_Initialize().

Function names use lowercase i, not uppercase I. This notation differs from Base_UnInitialize (uppercase I) in the old interface.

Starting with 3.5.3, the SDK sends any unreported game playtime to the server immediately when it shuts down. This function may therefore wait up to 3 seconds for the server response.

Declaration

c
IStoveResult* Stove_Uninitialize();

Parameters

None

Returns

TypeDescription
IStoveResult*Here are the results of the call. If Stove_IStoveResult_GetResultCode() equals 0, the call was successful.

The method code for this function is k_EStoveBaseMethodCode_BaseUninitialize.

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
16k_EStoveCommonResultCode_BaseNotInitializedIt was called before it had been initialized.x
253k_EStoveCommonResultCode_UnmanagedExceptionAn unknown exception occurred during execution.OThere was a temporary issue. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionAn exception occurred during execution.OA temporary problem has occurred. Please try again. [OK]

Complete List: EStoveCommonResultCode

Memory Management

ObjectOwnerRelease
Returned IStoveResult*CallerStove_IStoveTypeBase_Destroy() Required

Example

c
IStoveResult* result = Stove_Uninitialize();
if (Stove_IStoveResult_IsSuccessful(result))
{
    // Please implement the logic for a successful outcome.
}
else
{
    // Please implement the logic for when an error occurs.
}

Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result);

Notes

  • This is the termination function that pairs with Stove_Initialize().
  • This function is also used to clean up the state where only some modules were initialized due to a failure and to retry Stove_Initialize().
  • Even if BASE_NOT_INITIALIZED is returned, the internal cleanup routine continues (it simply logs the error and proceeds with the termination process).

See Also


Stove_VietnamAgeRatingNotification

Kind Function · Module Base · Version 3.5.0

Description

This API returns information on age ratings in Vietnam via a callback. It is an API specifically for Vietnam.

This is not a one-time callback. Call the function once and the notification is delivered every time the overlay needs to be shown or hidden. Call it after your game can render.

Declaration

c
void Stove_VietnamAgeRatingNotification(const IStoveTypeBase* param, OnVietnamAgeRatingNotificationCallback onFinished, void* userData);

Parameters

NameTypeRequiredDescription
paramconst IStoveTypeBase*NAs a reserved argument, a dedicated TypeKind has not been defined.
onFinishedOnVietnamAgeRatingNotificationCallbackYThis is the callback that will receive the results.
userDatavoid*NThis is user data that is passed directly to the callback.

Returns

None

The method code for this function is k_EStoveBaseMethodCode_VietnamAgeRatingNotification.

Callback

c
typedef void(__cdecl* OnVietnamAgeRatingNotificationCallback)(const IStoveCallbackResult* callbackResult, const IStoveVietnamAgeRatingInfo* ageRatingInfo);
NameTypeDescription
callbackResultconst IStoveCallbackResult*Here are the results of the call.
ageRatingInfoconst IStoveVietnamAgeRatingInfo*This is information about the age rating overlay. Overlay display status (GetOverlayMode()), overlay color type (GetOverlayType(), 0=Black·1=White), overlay size (GetOverlayScale(), 0.0–1.0), overlay opacity (GetOverlayOpacity(), 0.0–1.0), game rating (GetAgeRating(), 0=All Ages·12=Ages 12·16=Ages 16·18=Ages 18), notification message (GetMsg()), display position X·Y (GetDisplayPositionX()/GetDisplayPositionY(), 0.0 to 1.0 relative to the top-left corner of the screen), and a language code for font selection (GetLanguage()).

The callback runs in the thread that called Stove_RunCallback() (or Stove_RunCallbackWithTimeout()). It is a one-time callback and must be called after the point at which rendering is possible.

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
5k_EStoveCommonResultCode_InvalidParamonFinished is nullptrx
16k_EStoveCommonResultCode_BaseNotInitializedThe SDK did not initializex
31k_EStoveCommonResultCode_NotSupportedCountryThe GDS country code for the login account is not Vietnam (vn)x
253k_EStoveCommonResultCode_UnmanagedExceptionAn unknown exception occurred during execution.OA temporary issue has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionAn internal exception occurred during executionOA temporary issue has occurred. Please try again. [OK]

Complete list: EStoveCommonResultCode, EStoveResultCode

Memory Management

ObjectOwnerRelease
paramCallerIf delivered, Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param) Required
Callback callbackResult, ageRatingInfoSDKDo not unlock. This will be invalidated once the callback completes.

Example

c
void OnVietnamAgeRatingNotification(const IStoveCallbackResult* callbackResult, const IStoveVietnamAgeRatingInfo* ageRatingInfo)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);
    if (Stove_IStoveResult_IsSuccessful(result))
    {
        // Please implement the logic for a successful outcome.
        int32_t overlayMode = Stove_IStoveVietnamAgeRatingInfo_GetOverlayMode(ageRatingInfo);
        const wchar_t* msg = Stove_IStoveVietnamAgeRatingInfo_GetMsg(ageRatingInfo);
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

// Call this once after the point at which rendering is possible.
Stove_VietnamAgeRatingNotification(nullptr, OnVietnamAgeRatingNotification, nullptr);

// The callback will be passed only if it is called periodically within the game loop.
Stove_RunCallback();

Notes

  • This is an API specifically for Vietnam.
  • This is a one-time callback and must be called after rendering is complete.

See Also


Stove_VietnamOverimmersionNotification

Kind Function · Module Base · Version 3.5.0

Description

Information on preventing excessive gaming in Vietnam is provided via callback. This is an API specifically for Vietnam.

This is not a one-time callback. Call the function once and the notification is delivered repeatedly at the interval the server defines, including once right after the game starts (0 minutes elapsed). Call it after your game can render, so that the first notice is not missed.

Declaration

c
void Stove_VietnamOverimmersionNotification(const IStoveTypeBase* param, OnVietnamOverimmersionNotificationCallback onFinished, void* userData);

Parameters

NameTypeRequiredDescription
paramconst IStoveTypeBase*NAs a reserved argument, a dedicated TypeKind has not been defined.
onFinishedOnVietnamOverimmersionNotificationCallbackYThis is the callback that will receive the results.
userDatavoid*NThis is the user data that is passed directly to the callback.

Returns

None

The method code for this function is k_EStoveBaseMethodCode_VietnamOverimmersionNotification.

Callback

c
typedef void(__cdecl* OnVietnamOverimmersionNotificationCallback)(const IStoveCallbackResult* callbackResult, const IStoveVietnamOverimmersionInfo* overimmersionInfo);
NameTypeDescription
callbackResultconst IStoveCallbackResult*Here are the results of the call.
overimmersionInfoconst IStoveVietnamOverimmersionInfo*This is information about the anti-excessive-use overlay. Overlay display status (GetOverlayMode()), overlay color types (GetOverlayType(), 0=Black·1=White), overlay size (GetOverlayScale(), 0.0–1.0), overlay opacity (GetOverlayOpacity(), 0.0–1.0), game rating (GetAgeRating(), 0=All Ages·12=Ages 12·16=Ages 16·18=Ages 18), warning message (GetMsg()), formatting tags (<b>, <color=#RRGGBBAA>, etc.) formatted message (GetStyledMsg()), cumulative playtime (GetElapsedMinutes(), in minutes), message display duration (GetExposureTime(), in seconds), expansion animation duration (GetExpandAnimationTime(), in seconds), display position X and Y (GetDisplayPositionX()/GetDisplayPositionY(), 0.0 to 1.0 relative to the top-left corner of the screen), and language codes for font selection (GetLanguage()).

The callback runs in the thread that called Stove_RunCallback() (or Stove_RunCallbackWithTimeout()). It is a one-time callback and must be called after the point at which rendering is possible.

Error Codes

CodeNameDescriptionShow to UserIn-Game Message
0k_EStoveCommonResultCode_SuccessSuccessx
5k_EStoveCommonResultCode_InvalidParamonFinished is nullptrx
16k_EStoveCommonResultCode_BaseNotInitializedThe SDK did not initializex
31k_EStoveCommonResultCode_NotSupportedCountryThe GDS country code for the login account is not Vietnam (vn)x
253k_EStoveCommonResultCode_UnmanagedExceptionAn unknown exception occurred during execution.OA temporary problem has occurred. Please try again. [OK]
254k_EStoveCommonResultCode_ManagedExceptionAn internal exception occurred during executionOA temporary issue has occurred. Please try again. [OK]

Complete list: EStoveCommonResultCode, EStoveResultCode

Memory Management

ObjectOwnerRelease
paramCallerIf delivered, Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param) Required
Callbacks callbackResult and overimmersionInfoSDKDo not unlock. This will be invalidated once the callback is complete.

Example

c
void OnVietnamOverimmersionNotification(const IStoveCallbackResult* callbackResult, const IStoveVietnamOverimmersionInfo* overimmersionInfo)
{
    IStoveResult* result = Stove_IStoveCallbackResult_GetResult(callbackResult);
    if (Stove_IStoveResult_IsSuccessful(result))
    {
        // Please implement the logic for the success case.
        const wchar_t* styledMsg = Stove_IStoveVietnamOverimmersionInfo_GetStyledMsg(overimmersionInfo);
        int32_t elapsedMinutes = Stove_IStoveVietnamOverimmersionInfo_GetElapsedMinutes(overimmersionInfo);
    }
    else
    {
        // Please implement the logic for when an error occurs.
    }
}

// Call this once after the point in time when rendering is possible.
Stove_VietnamOverimmersionNotification(nullptr, OnVietnamOverimmersionNotification, nullptr);

// The callback will be delivered only if it is called periodically within the game loop.
Stove_RunCallback();

Notes

  • This is an API specifically for Vietnam.
  • This is a one-time callback and must be called after rendering is complete.

See Also