- 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
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.
| File | Role |
|---|---|
<module>_api.h | Declaring SDK Custom Functions (such as Stove_Initialize) |
<module>_types.h | C++ environment: IStove* interface definition (pure virtual function). C environment: opaque typedef struct |
<module>_misc.h | Enumeration Definitions (EStove<Module>TypeKind, EStove<Module>MethodCode, EStove<Module>ResultCode) |
<module>_flat_api.h | C-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 usingstove_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.
| Target | Notation |
|---|---|
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 |
| Callback | Callback 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 inself->Method(). - C flat function: This is an entry point exposed from
*_api.h/*_flat_api.htoextern "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.htoextern "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.
| Tab | Uses | Accessing Interface Members | Object Release |
|---|---|---|---|
C | C projects, or environments where vtable calls cannot be used | Stove_IStoveResult_IsSuccessful(result) | Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result) |
C++ | A C++ project that uses the interface of *_types.h as-is | result->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
| Category | Pattern | Example |
|---|---|---|
| SDK Functions | Stove_<Method> (Free function without a module token) | Stove_Initialize, Stove_StartPurchase, Stove_FetchProducts |
| Parameter Object Composite Factory | Stove_CreateParam(int kind) | Stove_CreateParam(k_EStoveBaseTypeKind_InitializeParam) |
| Interface Accessors | Stove_<Interface>_<Method> | Stove_IStoveUser_GetNickName(user) |
| Callback Type | On<Action>Callback | OnRestartAppIfNecessaryCallback |
| Enumeration values | k_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.
cif (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
Destroybased on the return value ofShouldDestroy()will prevent both memory leaks and double release. The table below summarizes the return values ofShouldDestroyfor 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>)areShouldDestroy == true, and you must free them by callingStove_IStoveTypeBase_Destroy(obj)(orobj->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 Path | ShouldDestroy | Release |
|---|---|---|
Parameter object created using Factory(Stove_CreateParam) | true | The caller must free the memory, After the API call is complete, Stove_IStoveTypeBase_Destroy(self) (in C++, self->Destroy()) |
Synchronous API return value IStoveResult* | true | The caller must release it, Stove_IStoveTypeBase_Destroy(result) |
Objects received as out parameters (IStoveUser**, IStoveGds**, IStoveSignin**) | true | The caller must release it, Stove_IStoveTypeBase_Destroy(*outXxx) |
IStoveCallbackResult* and its associated objects (IStoveAccessToken*, IStoveStat*, IStoveAchievement*, ...) passed via an asynchronous callback | false | SDK 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()) | false | Owned 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. CallStove_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:
// 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:
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.
- Created IStoveRestartAppIfNecessaryParam as
Stove_CreateParam(k_EStoveBaseTypeKind_RestartAppIfNecessaryParam) - Configure settings such as environment variables, game IDs, and app keys using
Stove_IStoveRestartAppIfNecessaryParam_Set*()(orrestartParam->SetXxx()in C++) - 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.
- In the game's main loop, we start calling Stove_RunCallback() every frame. Since the callback for
Stove_RestartAppIfNecessary()is dispatched whenStove_RunCallback()is called, theStove_RunCallback()loop must start running immediately after the call in order to receive the callback. - In the callback, if
IsRestartRequired() == false, call Stove_Initialize() in the order shown below, (ifIsRestartRequired() == true, the SDK will relaunch the app via the launcher, so terminate the current process)- Created as
Stove_CreateParam(k_EStoveBaseTypeKind_InitializeParam)from IStoveInitializeParam - To use IAP together, set
SetMainWndHandle()to be the parent window of the payment webview along withSetShopKey(). Stove_Initialize(initParam)call, Synchronous,IStoveResult*returns immediately. The IAP module is also initialized based on the specified value.
- Created as
- If the returned
IStoveResult*result code is 0 (success), it can be used. Destroy after use. - Keep the
Stove_RunCallback()loop running while the game is running (main thread) - Call Stove_Uninitialize() upon termination (must return
IStoveResult*Destroy) restartParamandinitParamare each released viaStove_IStoveTypeBase_Destroy()after they have finished executing (after the callback completes / afterStove_Initialize()is returned).
Stove_RestartAppIfNecessary()is an asynchronous function. The callback is dispatched on the thread that calledStove_RunCallback(), not on an internal SDK thread. Therefore, if you do not runStove_RunCallback()in the game loop after callingStove_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 returnsIStoveResult*. Be sure to call it within theIsRestartRequired() == falsebranch of theStove_RestartAppIfNecessary()callback. After checking the result code, the caller should release it usingStove_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
__cdeclcalling 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
VietnamAgeRatingandVietnamOverimmersion) must be called after the point at which rendering is possible. - The
onFinishedcallback in the asynchronous API is a required parameter. If you do not specify it, ak_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_AccessTokenRenewedandStove_OverImmersionNotification),userDatamust remain active until the SDK is terminated or unregistered.- Be careful not to let
userDatapoint 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
onFinishedandonDestroy) operate independently ofuserData1anduserData2. 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, passNULL.
Example C: The game dynamically allocates and passes a context structure, which is then freed after use in the callback:
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
ctxis deallocated before theOnPurchaseFinishedcallback is called, a crash will occur due to a dangling pointer. Be sure to maintain the lifetime ofctxuntil 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.
| Type | Document |
|---|---|
IStoveTypeBase | IStoveTypeBase |
IStoveResult | IStoveResult |
IStoveCallbackResult | IStoveCallbackResult |
Notes
Stove_RestartAppIfNecessary()must be called beforeStove_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 ofStove_RestartAppIfNecessary()(theIsRestartRequired() == falsebranch).- Since
userDatais avoid*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
| Document | Content |
|---|---|
| Stove_CreateParam | Parameter Object Composite Factory |
| IStoveRestartAppIfNecessaryOutcome | Stove_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
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
| Code | Name | Description |
|---|---|---|
| -1 | k_EStoveBaseMethodCode_Invalid | Not used |
| 1 | k_EStoveBaseMethodCode_BaseInitialize | Stove_Initialize |
| 2 | k_EStoveBaseMethodCode_BaseUninitialize | Stove_Uninitialize |
| 5 | k_EStoveBaseMethodCode_BaseGetVersion | Stove_GetVersion |
| , | 6 ~ 63 | Not in use (reserved section) |
Public APIs
| Code | Name | Description |
|---|---|---|
| 64 | k_EStoveBaseMethodCode_GetAccessToken | Stove_GetAccessToken |
| 65 | k_EStoveBaseMethodCode_AccessTokenRenewed | Stove_AccessTokenRenewed |
| 66 | k_EStoveBaseMethodCode_GetUser | Stove_GetUser |
| 67 | k_EStoveBaseMethodCode_SetLanguage | Stove_SetLanguage |
| 68 | k_EStoveBaseMethodCode_OverImmersionNotification | Stove_OverImmersionNotification |
| 69 | k_EStoveBaseMethodCode_ShutdownNotification | Stove_ShutdownNotification |
| , | 70, 71 | Not in use (reserved numbers that have been retired for internal use only) |
| 72 | k_EStoveBaseMethodCode_SetGameProfile | Stove_SetGameProfile |
| 73 | k_EStoveBaseMethodCode_GetGds | Stove_GetGds |
| 74 | k_EStoveBaseMethodCode_GetSignin | Stove_GetSignin |
| 75 | k_EStoveBaseMethodCode_RestartAppIfNecessary | Stove_RestartAppIfNecessary |
| 76 | k_EStoveBaseMethodCode_RestartAppIfNecessaryAsync | Asynchronous processing path for Stove_RestartAppIfNecessary |
| 77 | k_EStoveBaseMethodCode_OpenExternalUrl | Stove_OpenExternalUrl |
| 78 | k_EStoveBaseMethodCode_GetCloudSavingPath | Stove_GetCloudSavingPath, Exclusive to StoreIndi |
| 79 | k_EStoveBaseMethodCode_VietnamAgeRatingNotification | Stove_VietnamAgeRatingNotification |
| 80 | k_EStoveBaseMethodCode_VietnamOverimmersionNotification | Stove_VietnamOverimmersionNotification |
| 81 | k_EStoveBaseMethodCode_CloseAllPopups | Stove_CloseAllPopups(Single binary integration, Closes both the IAP and View pop-ups) |
| , | 82 ~ 95 | Not in use (reserved section) |
Private getters (private getters exposed to other SDK modules, not exposed to the game)
| Code | Name | Description |
|---|---|---|
| 115 | k_EStoveBaseMethodCode_GetEnvPrivate | Private getter, For use by other SDK modules only; not exposed to the game |
| 116 | k_EStoveBaseMethodCode_GetGameIdPrivate | Private getter, For use by other SDK modules only; not exposed to the game |
| 117 | k_EStoveBaseMethodCode_GetMemberNoPrivate | Private getter, Reserved for other SDK modules; not exposed to the game |
| 118 | k_EStoveBaseMethodCode_GetPublicIp | Private getter, For use by other SDK modules only; not exposed to the game |
| 119 | k_EStoveBaseMethodCode_GetTranslateLanguage | Private getter, For use by other SDK modules only; not exposed to the game |
Other
| Code | Name | Description |
|---|---|---|
| , | 120 ~ 0x7ffffffe | Not in use (reserved section) |
| 0x7fffffff | k_EStoveBaseMethodCode_Max | Not 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
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 containInternal. - 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 ink_EStoveBaseMethodCode_Invalid.
Changelog
| Version | Change |
|---|---|
| 3.5.0 | First 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
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)
| Code | Name | Description |
|---|---|---|
| -1 | k_EStoveBaseTypeKind_Invalid | Not used |
| 0 | k_EStoveBaseTypeKind_Base | IStoveTypeBase |
| 1 | k_EStoveBaseTypeKind_StoveResult | IStoveResult |
| 2 | k_EStoveBaseTypeKind_StoveCallbackResult | IStoveCallbackResult |
| 3 | k_EStoveBaseTypeKind_StoveUser | IStoveUser |
| 4 | k_EStoveBaseTypeKind_StoveAccessToken | IStoveAccessToken |
| 5 | k_EStoveBaseTypeKind_StoveGds | IStoveGds |
| 6 | k_EStoveBaseTypeKind_StoveSignin | IStoveSignin |
| 7 | k_EStoveBaseTypeKind_StoveOverImmersionInfo | IStoveOverImmersionInfo |
| 8 | k_EStoveBaseTypeKind_StoveVietnamAgeRatingInfo | IStoveVietnamAgeRatingInfo |
| 9 | k_EStoveBaseTypeKind_StoveVietnamOverimmersionInfo | IStoveVietnamOverimmersionInfo |
| 10 | k_EStoveBaseTypeKind_StoveShutdownInfo | IStoveShutdownInfo |
| 11 | k_EStoveBaseTypeKind_StoveRestartAppIfNecessaryOutcome | IStoveRestartAppIfNecessaryOutcome |
| , | 12 ~ 499 | Not used (reserved range between the result/data type and the parameter type range) |
Parameter types (created by the caller using Stove_CreateParam())
| Code | Name | Description |
|---|---|---|
| 500 | k_EStoveBaseTypeKind_RestartAppIfNecessaryParam | IStoveRestartAppIfNecessaryParam |
| 501 | k_EStoveBaseTypeKind_InitializeParam | IStoveInitializeParam |
| 502 | k_EStoveBaseTypeKind_SetGameProfileParam | IStoveSetGameProfileParam |
| , | 503 ~ 0x7ffffffe | Not in use (reserved section) |
| 0x7fffffff | k_EStoveBaseTypeKind_Max | Not used |
Example
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 ink_EStoveBaseTypeKind_Invalid. - In the old interface,
IStoveInitializeParamwas 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
| Version | Change |
|---|---|
| 3.5.0 | First 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
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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 1 | k_EStoveCommonResultCode_Fail | General Failure | x |
Configuration/Parameter Validation Failed
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 2 | k_EStoveCommonResultCode_InvalidConfig | The setting is invalid. | x | |
| 3 | k_EStoveCommonResultCode_InvalidLogLevel | The log level value is invalid. | x | |
| 4 | k_EStoveCommonResultCode_InvalidLogPath | The log path is invalid. | x | |
| 5 | k_EStoveCommonResultCode_InvalidParam | The parameter is invalid. | x | |
| , | 6 ~ 15 | Not in use (reserved section) | , | , |
Initialization State Error
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 16 | k_EStoveCommonResultCode_BaseNotInitialized | The SDK has not been initialized. | x | |
| 17 | k_EStoveCommonResultCode_NotInitialized | This module has not been initialized. | x | |
| 18 | k_EStoveCommonResultCode_AlreadyInitialized | It is already initialized. | x |
Token/Entity Error
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 19 | k_EStoveCommonResultCode_InvalidAccessToken | The AccessToken is invalid. | O | Your login session has expired. Please close the game and restart it. [OK] |
| 20 | k_EStoveCommonResultCode_NullTokenEntity | The token entity is null. | x | |
| 21 | k_EStoveCommonResultCode_NullEntity | The entity is null. | x |
If you receive the code below, you must exit the game. The game cannot proceed normally.
19k_EStoveCommonResultCode_InvalidAccessToken, Your login session has expired and needs to be refreshed
HTTP/Response Errors
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 22 | k_EStoveCommonResultCode_HttpError | An HTTP error has occurred | O | The network connection is unstable. Please check your network status and try again. [OK] |
| 23 | k_EStoveCommonResultCode_ResponseError | This is a server response error. | O | The network connection is unstable. Please check your network status and try again. [OK] |
| 24 | k_EStoveCommonResultCode_ResponseInvalidCode | The server response code is invalid. | O | The network connection is unstable. Please check your network status and try again. [OK] |
| 25 | k_EStoveCommonResultCode_ResponseValueIsNull | The server response value is null. | O | The network connection is unstable. Please check your network status and try again. [OK] |
| 26 | k_EStoveCommonResultCode_ResponseInvalidValueFormat | The format of the server response is invalid. | O | The network connection is unstable. Please check your network status and try again. [OK] |
Other Conditions
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| , | 27, 28 | Not in use (discontinued number) | , | , |
| 29 | k_EStoveCommonResultCode_AsyncOperationInProgress | An asynchronous task is already in progress. | x | |
| 30 | k_EStoveCommonResultCode_BaseUninitialized | The SDK has already been unlocked (Stove_Uninitialize). | x | |
| 31 | k_EStoveCommonResultCode_NotSupportedCountry | This country/region is not supported. | x | |
| 33 | k_EStoveCommonResultCode_PopupNotCreated | The 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 | |
| 34 | k_EStoveCommonResultCode_WebviewClosedBeforeComplete | The WebView closed before the task was completed. | O | The purchase was not completed successfully. Please try again. [OK] |
Local DB Failure (Common to All Modules)
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 40 | k_EStoveCommonResultCode_LocalDbCreateWorkingDirectoryFailed | Failed to create the local DB working directory | x | |
| 41 | k_EStoveCommonResultCode_LocalDbConnectFailed | Failed to connect to the local database | x | |
| 42 | k_EStoveCommonResultCode_LocalDbCreateTableFailed | Failed to create a local database table | x | |
| 43 | k_EStoveCommonResultCode_LocalDbDisconnectFailed | Failed to disconnect from the local database | x | |
| 44 | k_EStoveCommonResultCode_LocalDbWriteFailed | Failed to write to the local database | x | |
| , | 45 ~ 59 | Not in use (reserved for future Local DB/payload/storage code) | , | , |
WebView/Popup UI Failure (Shared Module)
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 60 | k_EStoveCommonResultCode_ViewUiNotInitialized | The Popup/WebView UI subsystem has not been initialized. | x | |
| 61 | k_EStoveCommonResultCode_ViewUiUninitFailed | Failed to close the Popup/WebView UI subsystem | x | |
| 62 | k_EStoveCommonResultCode_WebviewCreateFail | Failed to create a WebView | x | |
| 63 | k_EStoveCommonResultCode_WebviewLoadUrlFail | Failed to load the URL in the WebView | x | |
| 64 | k_EStoveCommonResultCode_WebviewCreateCookieFail | Failed to set WebView cookies | O | The page cannot be loaded. Please try again. [OK] |
| 65 | k_EStoveCommonResultCode_WebviewCloseAllFail | Failed to close all web views/pop-ups | x | |
| 66 | k_EStoveCommonResultCode_WebviewCloseFail | Failed to close the WebView/popup | x | |
| 67 | k_EStoveCommonResultCode_NoPopupData | There is no pop-up data to display. | O | There is no pop-up configuration information, so there is no window to display. [OK] |
| 68 | k_EStoveCommonResultCode_CloseAllPopupsFailed | One or more pop-ups could not be closed during call Stove_CloseAllPopups (IAP+View integrated call) | x | |
| , | 69 ~ 79 | Not in use (reserved for future WebView/pop-up UI code) | , | , |
Parameter/Payload Validation (Common to All Modules)
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 80 | k_EStoveCommonResultCode_ParameterLengthExceeded | The request parameters exceeded the maximum length. | O | The payment information is invalid, so we cannot process the payment. Please try again. [OK] |
| 81 | k_EStoveCommonResultCode_InvalidJsonString | The JSON string format is invalid. | O | The payment information is invalid, so we cannot process the payment. Please try again. [OK] |
| 82 | k_EStoveCommonResultCode_PayloadSizeExceeded | The payload exceeds the maximum allowed size. | x | |
| , | 83 ~ 248 | Not in use (reserved section) | , | , |
Network Transmission Failure
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 249 | k_EStoveCommonResultCode_NetworkTransportError | This is a network transmission error. The HTTP backend's native error code IStoveCallbackResult::GetExternalError() is returned (e.g., WinHTTP 12002/12007/12029). | x | |
| , | 250 | Not in use (reserved section) | , | , |
System/Runtime Failure
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 251 | k_EStoveCommonResultCode_PcsdkDllNotFound | The PCSDK DLL cannot be found | x | |
| 252 | k_EStoveCommonResultCode_NotImplemented | This feature has not been implemented. | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unmanaged exception has occurred. | O | A temporary issue has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | A managed exception has occurred. | O | A temporary issue has occurred. Please try again. [OK] |
| 255 | k_EStoveCommonResultCode_UnknownError | An unknown error has occurred. | x | |
| , | 256 ~ 0x7ffffffe | Not in use (reserved section) | , | , |
| 0x7fffffff | k_EStoveCommonResultCode_Max | Not used | , | , |
Example
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
EStoveBaseResultCodeandEStoveIAPResultCodefrom 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 ink_EStoveCommonResultCode_Success.
Changelog
| Version | Change |
|---|---|
| 3.5.0 | Initial 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
typedef enum EStoveDiscountType
{
k_EStoveDiscountType_None = 0,
k_EStoveDiscountType_FixedRate = 1,
k_EStoveDiscountType_FlatRate = 2,
k_EStoveDiscountType_Max = 0x7fffffff
} EStoveDiscountType;
Enum Values
| Code | Name | Description |
|---|---|---|
| 0 | k_EStoveDiscountType_None | No discount |
| 1 | k_EStoveDiscountType_FixedRate | Percentage discount (e.g., 10% off), DiscountTypeValue is a percentage value. |
| 2 | k_EStoveDiscountType_FlatRate | Fixed-amount discount (e.g., $2 off), DiscountTypeValue is the discount amount in the product's currency. |
| 0x7fffffff | k_EStoveDiscountType_Max | Not used |
Example
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
- The unit of IStoveProduct::DiscountTypeValue depends on this value.
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
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
| Code | Name | Description |
|---|---|---|
| -1 | k_EStoveGameSupportMethodCode_Invalid | Not used |
| 5000 | k_EStoveGameSupportMethodCode_FetchStat | Stove_FetchStat |
| 5001 | k_EStoveGameSupportMethodCode_SetStat | Stove_SetStat |
| 5002 | k_EStoveGameSupportMethodCode_FetchAchievement | Stove_FetchAchievement |
| 5003 | k_EStoveGameSupportMethodCode_FetchAchievements | Stove_FetchAchievements |
| 5004 | k_EStoveGameSupportMethodCode_FetchRanking | Stove_FetchRanking |
| 0x7fffffff | k_EStoveGameSupportMethodCode_Max | Not used |
Example
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
| Version | Change |
|---|---|
| 3.5.0 | First 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
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)
| Code | Name | Description |
|---|---|---|
| -1 | k_EStoveGameSupportTypeKind_Invalid | Not used |
| 5000 | k_EStoveGameSupportTypeKind_StatFullId | IStoveStatFullId |
| 5001 | k_EStoveGameSupportTypeKind_Stat | IStoveStat |
| 5002 | k_EStoveGameSupportTypeKind_SetStatOutcome | IStoveSetStatOutcome |
| 5003 | k_EStoveGameSupportTypeKind_AchievementCondition | IStoveAchievementCondition |
| 5004 | k_EStoveGameSupportTypeKind_Achievement | IStoveAchievement |
| 5005 | k_EStoveGameSupportTypeKind_Rank | IStoveRank |
| 5006 | k_EStoveGameSupportTypeKind_AchievementList | IStoveAchievementList |
| 5007 | k_EStoveGameSupportTypeKind_Ranking | IStoveRanking |
| , | 5008 ~ 5499 | Not used (reserved range between the result/data type and the parameter type range) |
Parameter types (created by the caller using Stove_CreateParam())
| Code | Name | Description |
|---|---|---|
| 5500 | k_EStoveGameSupportTypeKind_FetchStatParam | IStoveFetchStatParam |
| 5501 | k_EStoveGameSupportTypeKind_SetStatParam | IStoveSetStatParam |
| 5502 | k_EStoveGameSupportTypeKind_FetchAchievementParam | IStoveFetchAchievementParam |
| 5503 | k_EStoveGameSupportTypeKind_FetchAchievementsParam | IStoveFetchAchievementsParam |
| 5504 | k_EStoveGameSupportTypeKind_FetchRankingParam | IStoveFetchRankingParam |
| , | 5505 ~ 0x7ffffffe | Not in use (reserved section) |
| 0x7fffffff | k_EStoveGameSupportTypeKind_Max | Not used |
Example
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 toStove_CreateParam(). - The parameter type (
5500) is the type that the caller must create usingStove_CreateParam().
Changelog
| Version | Change |
|---|---|
| 3.5.0 | First 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
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
| Code | Name | Description |
|---|---|---|
| -1 | k_EStoveIAPMethodCode_Invalid | Not used |
| 2000 | k_EStoveIAPMethodCode_FetchShopCategories | Stove_FetchShopCategories |
| 2001 | k_EStoveIAPMethodCode_FetchProducts | Stove_FetchProducts |
| 2002 | k_EStoveIAPMethodCode_StartPurchase | Stove_StartPurchase |
| 2003 | k_EStoveIAPMethodCode_ConfirmPurchase | Stove_ConfirmPurchase |
| 2004 | k_EStoveIAPMethodCode_FetchInventory | Stove_FetchInventory |
| 2005 | k_EStoveIAPMethodCode_FetchTermsAgreement | Stove_FetchTermsAgreement |
| 2006 | k_EStoveIAPMethodCode_WithdrawGame | Stove_WithdrawGame, For Lost Ark Mobile only |
| 0x7fffffff | k_EStoveIAPMethodCode_Max | Not used |
Example
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
EStoveIAPResultCodefrom the previous interface has been removed. To determine the cause of the failure, check the value ofGetResultCode()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
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
| Code | Name | Description |
|---|---|---|
| -1 | k_EStoveIAPTypeKind_Invalid | Not used |
| 2000 | k_EStoveIAPTypeKind_ShopCategory | IStoveShopCategory, Store Category Entry |
| 2001 | k_EStoveIAPTypeKind_Product | IStoveProduct, Product Item |
| 2002 | k_EStoveIAPTypeKind_StartPurchaseOutcome | IStoveStartPurchaseOutcome, Purchase Start Result (Formerly: PurchaseResult) |
| 2003 | k_EStoveIAPTypeKind_PurchasedProduct | IStovePurchasedProduct, Items with confirmed purchases |
| 2004 | k_EStoveIAPTypeKind_ChargeInfo | IStoveChargeInfo, Payment Currency (Charge) Information |
| 2005 | k_EStoveIAPTypeKind_InventoryItem | IStoveInventoryItem, Inventory (Purchase History) Item |
| , | 2006 | Not in use (reservation number) |
| , | 2007 | Not in use (reserved number) |
| 2008 | k_EStoveIAPTypeKind_ConfirmPurchaseOutcome | IStoveConfirmPurchaseOutcome, Purchase Confirmation Results |
| 2009 | k_EStoveIAPTypeKind_WithdrawGameOutcome | IStoveWithdrawGameOutcome, Game Withdrawal Results (Lost Ark Mobile Only) |
| 2010 | k_EStoveIAPTypeKind_TermsAgreementOutcome | IStoveTermsAgreementOutcome, Results of Terms and Conditions Agreement Check |
| 2011 | k_EStoveIAPTypeKind_ShopCategoryList | IStoveShopCategoryList, Container for the list of store categories |
| 2012 | k_EStoveIAPTypeKind_ProductList | IStoveProductList, Product List Container |
| 2013 | k_EStoveIAPTypeKind_InventoryList | IStoveInventoryList, Inventory (Purchase History) List Container |
| 2500 | k_EStoveIAPTypeKind_FetchProductsParam | IStoveFetchProductsParam, Product search parameters |
| 2501 | k_EStoveIAPTypeKind_OrderProductParam | IStoveOrderProductParam, Order Item Parameters |
| 2502 | k_EStoveIAPTypeKind_PurchaseParam | IStovePurchaseParam, Purchase Action Parameters |
| 2503 | k_EStoveIAPTypeKind_StartPurchaseParam | IStoveStartPurchaseParam, Start Purchase Parameter |
| 2504 | k_EStoveIAPTypeKind_FetchTermsAgreementParam | IStoveFetchTermsAgreementParam, Terms of Service Agreement Lookup Parameter |
| , | 2505 | Not in use (reservation number) |
| 2506 | k_EStoveIAPTypeKind_WithdrawGameParam | IStoveWithdrawGameParam, Game Exit Parameter (Lost Ark Mobile Only) |
| 2507 | k_EStoveIAPTypeKind_ConfirmPurchaseParam | IStoveConfirmPurchaseParam, Purchase Confirmation Parameter |
| , | 2508 | Not in use (reserved number) |
| 0x7fffffff | k_EStoveIAPTypeKind_Max | Not 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
IStoveFetchProductsParam* param = (IStoveFetchProductsParam*)Stove_CreateParam(k_EStoveIAPTypeKind_FetchProductsParam);
Notes
- Since the
TypeKindenumerations for each module, such asBaseandIAP, use non-overlapping integer ranges, you can generate parameters for all modules using just a singleStove_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_StartPurchaseOutcomewas 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
typedef enum EStoveLogMethodCode
{
k_EStoveLogMethodCode_Invalid = -1,
k_EStoveLogMethodCode_SendLog = 6000,
k_EStoveLogMethodCode_Max = 0x7fffffff
} EStoveLogMethodCode;
Enum Values
| Code | Name | Description |
|---|---|---|
| -1 | k_EStoveLogMethodCode_Invalid | Not used |
| 6000 | k_EStoveLogMethodCode_SendLog | This is the result created by Stove_SendLog. |
| 0x7fffffff | k_EStoveLogMethodCode_Max | Not used |
Example
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. EStoveLogResultCodehas 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
typedef enum EStoveLogTypeKind
{
k_EStoveLogTypeKind_Invalid = -1,
k_EStoveLogTypeKind_SendLogParam = 6500,
k_EStoveLogTypeKind_Max = 0x7fffffff
} EStoveLogTypeKind;
Enum Values
| Code | Name | Description |
|---|---|---|
| -1 | k_EStoveLogTypeKind_Invalid | Not used |
| 6500 | k_EStoveLogTypeKind_SendLogParam | This is the parameter type created by the caller as Stove_CreateParam(). It corresponds to IStoveSendLogParam. |
| 0x7fffffff | k_EStoveLogTypeKind_Max | Not used |
Example
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
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
| Code | Name | Description |
|---|---|---|
| -1 | k_EStoveOverlayMode_Invalid | Not used |
| 0 | k_EStoveOverlayMode_Show | Displays the overlay |
| 1 | k_EStoveOverlayMode_Hide | Hide the overlay |
| 2 | k_EStoveOverlayMode_Expanded | Displays the overlay in its expanded form |
| 0x7fffffff | k_EStoveOverlayMode_Max | Not used |
Example
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_Expandedis 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 ink_EStoveOverlayMode_Invalid.
Changelog
| Version | Change |
|---|---|
| 3.5.0 | First 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
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
| Code | Name | Description |
|---|---|---|
| -1 | k_EStoveOwnershipCode_Invalid | Not used |
| 0 | k_EStoveOwnershipCode_None | There is no recorded ownership status. |
| 1 | k_EStoveOwnershipCode_Acquire | The user currently owns this item. |
| 2 | k_EStoveOwnershipCode_Lose | The user has lost ownership (e.g., due to a refund). |
| 0x7fffffff | k_EStoveOwnershipCode_Max | Not used |
Example
if (Stove_IStoveOwnership_GetOwnershipCode(ownership) == k_EStoveOwnershipCode_Acquire)
{
// Please implement the logic for the items you own.
}
Notes
- This is the value of the
OwnershipCodefield in IStoveOwnership.
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
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
| Code | Name | Description |
|---|---|---|
| -1 | k_EStoveOwnershipGameCode_Invalid | Not used |
| 0 | k_EStoveOwnershipGameCode_None | Not a product item / Unclassified |
| , | 1, 2 | Not in use (discontinued number) |
| 3 | k_EStoveOwnershipGameCode_Basic | Base Game |
| 4 | k_EStoveOwnershipGameCode_Demo | Demo Build |
| 5 | k_EStoveOwnershipGameCode_Dlc | Downloadable Content (DLC) associated with the base game |
| 0x7fffffff | k_EStoveOwnershipGameCode_Max | Not used |
Example
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
GameCodefield 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
typedef enum EStoveOwnershipMethodCode
{
k_EStoveOwnershipMethodCode_Invalid = -1,
k_EStoveOwnershipMethodCode_FetchOwnerships = 4000,
k_EStoveOwnershipMethodCode_Max = 0x7fffffff
} EStoveOwnershipMethodCode;
Enum Values
| Code | Name | Description |
|---|---|---|
| -1 | k_EStoveOwnershipMethodCode_Invalid | Not used |
| 4000 | k_EStoveOwnershipMethodCode_FetchOwnerships | This is the result created by Stove_FetchOwnerships. |
| 0x7fffffff | k_EStoveOwnershipMethodCode_Max | Not used |
Example
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
typedef enum EStoveOwnershipTypeKind
{
k_EStoveOwnershipTypeKind_Invalid = -1,
k_EStoveOwnershipTypeKind_StoveOwnership = 4000,
k_EStoveOwnershipTypeKind_OwnershipList = 4001,
k_EStoveOwnershipTypeKind_Max = 0x7fffffff
} EStoveOwnershipTypeKind;
Enum Values
| Code | Name | Description |
|---|---|---|
| -1 | k_EStoveOwnershipTypeKind_Invalid | Not used |
| 4000 | k_EStoveOwnershipTypeKind_StoveOwnership | This is the type value for IStoveOwnership. |
| 4001 | k_EStoveOwnershipTypeKind_OwnershipList | This is the type value for IStoveOwnershipList. |
| 0x7fffffff | k_EStoveOwnershipTypeKind_Max | Not used |
Example
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
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
| Code | Name | Description |
|---|---|---|
| 0 | k_EStoveProductTypeCode_None | Uncategorized |
| 1 | k_EStoveProductTypeCode_IndiePackageGameItem | Reserved (not currently used) |
| 2 | k_EStoveProductTypeCode_InGameItem | In-game items |
| 3 | k_EStoveProductTypeCode_PackageItem | Reserved (not currently used) |
| 0x7fffffff | k_EStoveProductTypeCode_Max | Not used |
Example
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
0and2are currently in use.1and3are 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
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
| Code | Name | Description |
|---|---|---|
| 0 | k_EStovePurchaseLimitTypeCode_None | No defined restriction policy |
| 1 | k_EStovePurchaseLimitTypeCode_Unlimited | Unlimited purchases available |
| 2 | k_EStovePurchaseLimitTypeCode_Member | Account (Member) Level Limits |
| 3 | k_EStovePurchaseLimitTypeCode_Character | Character Limit |
| 0x7fffffff | k_EStovePurchaseLimitTypeCode_Max | Not used |
Example
int32_t limitType = Stove_IStoveProduct_GetPurchaseLimitTypeCode(product);
int32_t limitCount = Stove_IStoveProduct_GetPurchaseLimitCount(product);
Notes
- This value is used when interpreting IStoveProduct::PurchaseLimitCount.
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
typedef enum EStovePurchaseOperation
{
k_EStovePurchaseOperation_Default = 0,
k_EStovePurchaseOperation_WithWebView = 1,
k_EStovePurchaseOperation_WithWebViewAndConfirmResult = 2,
k_EStovePurchaseOperation_Max = 0x7fffffff
} EStovePurchaseOperation;
Enum Values
| Code | Name | Description |
|---|---|---|
| 0 | k_EStovePurchaseOperation_Default | Do 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. |
| 1 | k_EStovePurchaseOperation_WithWebView | Opens 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. |
| 2 | k_EStovePurchaseOperation_WithWebViewAndConfirmResult | Open 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. |
| 0x7fffffff | k_EStovePurchaseOperation_Max | Not used |
Example
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 theWebView*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
typedef enum EStovePurchaseProgress
{
k_EStovePurchaseProgress_None = 0,
k_EStovePurchaseProgress_NeedPaymentWindow = 1,
k_EStovePurchaseProgress_NotNeedPaymentWindow = 2,
k_EStovePurchaseProgress_Max = 0x7fffffff
} EStovePurchaseProgress;
Enum Values
| Code | Name | Description |
|---|---|---|
| 0 | k_EStovePurchaseProgress_None | No progress |
| 1 | k_EStovePurchaseProgress_NeedPaymentWindow | The caller must manually open the payment window using the one-time payment URL provided in the response. |
| 2 | k_EStovePurchaseProgress_NotNeedPaymentWindow | You 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. |
| 0x7fffffff | k_EStovePurchaseProgress_Max | Not used |
Example
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
- When
NeedPaymentWindow, use IStoveStartPurchaseOutcome::TempPaymentUrl to open the payment window, and after making the payment, you must confirm the purchase using Stove_ConfirmPurchase.
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–) andEStoveCommonResultCode(0–299).
Declaration
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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 300 | k_EStoveResultCode_LanguageNotSet | No display language has been set (Set the language to Stove_SetLanguage and try again) | x | |
| 301 | k_EStoveResultCode_EmptyTranslatedString | The translated string is empty. | x | |
| 302 | k_EStoveResultCode_NotFoundRequiredInformation | The required information was not found. | x | |
| 303 | k_EStoveResultCode_InvalidGdsInfo | The GDS (Country/Regulatory) information is invalid. | x | |
| 304 | k_EStoveResultCode_NeedStoveLauncher | The Stove launcher is required but is not running. | O | The 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] |
| 305 | k_EStoveResultCode_LauncherFailedCreateRequired | Failed to create the required launcher resources | x | |
| 306 | k_EStoveResultCode_RenewTokenMaxRetryCountExceeded | The token renewal has exceeded the maximum number of retry attempts. | O | The network connection is unstable. Please check your network status and try again. [OK] |
| 307 | k_EStoveResultCode_IpcConnectFailed | Failed to establish an IPC connection with the launcher | O | The 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] |
| 308 | k_EStoveResultCode_IpcAesKeyNotReceived | The AES key was not received over IPC. | O | The 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] |
| 309 | k_EStoveResultCode_IpcTimeout | The IPC communication with the launcher timed out. | O | The 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.
304k_EStoveResultCode_NeedStoveLauncher, This is not running via the Stove PC client, so it needs to be restarted.307k_EStoveResultCode_IpcConnectFailed, Failed to connect to the launcher; please try again.308k_EStoveResultCode_IpcAesKeyNotReceived, Failed to establish communication with the launcher; a retry is required309k_EStoveResultCode_IpcTimeout, Communication with the launcher timed out; a retry is required
4xx, (Reserved, Unused)
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| , | 400 ~ 499 | The webview/popup UI code has been moved to EStoveCommonResultCode lines 60–68. | , | , |
5xx, IAP Purchase / Payload
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| , | 501, 502 | EStoveCommonResultCode Moved to 80 and 81 | , | , |
| 503 | k_EStoveResultCode_InvalidOrderProductInformation | The order/product information is invalid. | O | The payment information is invalid, so we cannot process the payment. Please try again. [OK] |
| 0x7fffffff | k_EStoveResultCode_Max | Not used | , | , |
Example
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
| Version | Change |
|---|---|
| 3.5.0 | First 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
typedef enum EStoveTermsOperation
{
k_EStoveTermsOperation_Default = 0,
k_EStoveTermsOperation_WithWebView = 1,
k_EStoveTermsOperation_Max = 0x7fffffff
} EStoveTermsOperation;
Enum Values
| Code | Name | Description |
|---|---|---|
| 0 | k_EStoveTermsOperation_Default | The Stove WebView is not used. The caller opens the Terms and Conditions page directly using the one-time URL received as a result. |
| 1 | k_EStoveTermsOperation_WithWebView | Opens the Terms of Service agreement page within the Stove web view. |
| 0x7fffffff | k_EStoveTermsOperation_Max | Not used |
Example
IStoveFetchTermsAgreementParam* param = (IStoveFetchTermsAgreementParam*)Stove_CreateParam(k_EStoveIAPTypeKind_FetchTermsAgreementParam);
Stove_IStoveFetchTermsAgreementParam_SetOperation(param, k_EStoveTermsOperation_WithWebView);
Notes
- When using
WithWebView, you must also fill in theWebView*fields (WebView position and size) that IStoveFetchTermsAgreementParam inherits. - If a user has already agreed to the latest terms of service, regardless of this value,
IsAgreedin IStoveTermsAgreementOutcome will be returned astrue, andUrlwill 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
typedef enum EStoveWebViewMode
{
k_EStoveWebViewMode_Invalid = -1,
k_EStoveWebViewMode_External = 0,
k_EStoveWebViewMode_Internal = 1,
k_EStoveWebViewMode_Max = 0x7fffffff
} EStoveWebViewMode;
Enum Values
| Code | Name | Description |
|---|---|---|
| -1 | k_EStoveWebViewMode_Invalid | Not used |
| 0 | k_EStoveWebViewMode_External | Opens in the system's default browser |
| 1 | k_EStoveWebViewMode_Internal | Opens in the SDK's built-in web view |
| 0x7fffffff | k_EStoveWebViewMode_Max | Not used |
Example
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_Internalis 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 ink_EStoveWebViewMode_Invalid.
Changelog
| Version | Change |
|---|---|
| 3.5.0 | First 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
typedef struct IStoveAccessToken IStoveAccessToken;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
AccessToken | const wchar_t* | Read | Stove_IStoveAccessToken_GetAccessToken() | This is the Stove AccessToken value. |
ExpireIn | int32_t | Read | Stove_IStoveAccessToken_GetExpireIn() | This is the remaining validity period (in seconds) of the Stove AccessToken. |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | SDK |
| Responsibility for Termination | SDK, Passed only as a callback argument and invalidated once the callback completes. The caller does not call Destroy(). |
Example
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
typedef struct IStoveAchievement IStoveAchievement;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
Condition | const IStoveAchievementCondition* | Read | Stove_IStoveAchievement_GetCondition() | These are the requirements for completing the achievement. |
Value | int32_t | Read | Stove_IStoveAchievement_GetValue() | This is the current progress toward the achievement. |
AchievementId | const wchar_t* | Read | Stove_IStoveAchievement_GetAchievementId() | This is the achievement ID. |
Name | const wchar_t* | Read | Stove_IStoveAchievement_GetName() | This is the localized name of the achievement. |
Description | const wchar_t* | Read | Stove_IStoveAchievement_GetDescription() | This is a localized description of the achievement. |
DefaultImage | const wchar_t* | Read | Stove_IStoveAchievement_GetDefaultImage() | This is the URL for the "Goal Not Met" status image. |
AchievedImage | const wchar_t* | Read | Stove_IStoveAchievement_GetAchievedImage() | This is the URL for the achievement status image. |
Status | const wchar_t* | Read | Stove_IStoveAchievement_GetStatus() | This shows the current status of the achievement. Example: "ONGOING" (In Progress), "ACHIEVED" (Completed) |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | SDK |
| Responsibility for Dismantling | SDK (Do not disable. It will be invalidated once the callback (Stove_FetchAchievement / Stove_FetchAchievements) is complete.) |
Example
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
Conditionis also invalidated once the callback associated with this object completes. - The
ValueOperation/Typevalues forStatusandConditionare 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
typedef struct IStoveAchievementCondition IStoveAchievementCondition;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
ValueOperation | const wchar_t* | Read | Stove_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) |
Type | const wchar_t* | Read | Stove_IStoveAchievementCondition_GetType() | This is how target values and user-entered values are compared. Example: "GTE" (or higher), "LTE" (or lower) |
GoalValue | int32_t | Read | Stove_IStoveAchievementCondition_GetGoalValue() | This is the target value for the achievement. |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | SDK |
| Responsibility for Dismantling | SDK (Do not release. If the IStoveAchievement callback parameter containing this object is invalidated, it will be invalidated as well) |
Example
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
ValueOperationandTypeare 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
typedef struct IStoveAchievementList IStoveAchievementList;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
Count | uint32_t | Read | Stove_IStoveAchievementList_GetCount() | This is the number of achievements included in this response. |
| , | const IStoveAchievement* | Read | Stove_IStoveAchievementList_GetAt(index) | Retrieves achievement entries starting from index 0. If the index is index >= Count, it returns NULL. |
TotalCount | uint32_t | Read | Stove_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
| Item | Value |
|---|---|
| Creating Entity | SDK |
| Responsibility for Dismantling | SDK (Do not deactivate. It will be invalidated once the Stove_FetchAchievements callback completes) |
Example
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 fromGetResult(), will be invalidated.Destroy()will not be called.
Declaration
typedef struct IStoveCallbackResult IStoveCallbackResult;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
Result | IStoveResult* | Read | Stove_IStoveCallbackResult_GetResult() | This is an internal result object. It is valid only during the callback call. |
ErrorMessage | const wchar_t* | Read | Stove_IStoveCallbackResult_GetErrorMessage() | This is a detailed message explaining why the error occurred. |
ExternalError | int32_t | Read | Stove_IStoveCallbackResult_GetExternalError() | This is an external error value (HTTP error code or API response code). |
UserData | void* | Read | Stove_IStoveCallbackResult_GetUserData() | This is the userData pointer passed by the caller when making an asynchronous API call. |
Memory Management
| Item | Value |
|---|---|
| Creator | SDK |
| Responsibility for Dismantling | SDK, Passed only as a callback argument and invalidated once the callback completes. The caller does not call Destroy(). |
Example
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()(orStove_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
typedef struct IStoveChargeInfo IStoveChargeInfo;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
ChargeDeductVal | double | Read | Stove_IStoveChargeInfo_GetChargeDeductVal() | The amount actually deducted at the time of payment (based on the payment unit) |
ChargeDisplayDeductVal | double | Read | Stove_IStoveChargeInfo_GetChargeDisplayDeductVal() | Cash equivalent value of the deduction amount |
ChargeType | int32_t | Read | Stove_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. |
ChargeTypeName | const wchar_t* | Read | Stove_IStoveChargeInfo_GetChargeTypeName() | Localized payment method names |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | SDK |
| Responsibility for Dismantling | SDK (Do not unlock, becomes invalid once the callback is complete) |
Example
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
- It is passed from both
ChargeInfoAt()of IStoveStartPurchaseOutcome andChargeInfoAt()of IStoveConfirmPurchaseOutcome. - If multiple payment methods are used in a single purchase, the items are organized into an array, with one entry for each payment method.
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 callDestroy(); instead, copy any values you need to retain within the callback.
Declaration
typedef struct IStoveConfirmPurchaseOutcome IStoveConfirmPurchaseOutcome;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
IsConfirmed | bool | Read | Stove_IStoveConfirmPurchaseOutcome_IsConfirmed() | Whether the purchase was successfully completed |
PurchasedProductCount | uint32_t | Read | Stove_IStoveConfirmPurchaseOutcome_GetPurchasedProductCount() | Number of items with confirmed purchases |
PurchasedProductAt(index) | const IStovePurchasedProduct* | Read | Stove_IStoveConfirmPurchaseOutcome_GetPurchasedProductAt() | The purchased item at position index (starting from 0). If the position is index >= PurchasedProductCount, it returns nullptr. |
ChargeInfoCount | uint32_t | Read | Stove_IStoveConfirmPurchaseOutcome_GetChargeInfoCount() | Number of "charge-info" entries |
ChargeInfoAt(index) | const IStoveChargeInfo* | Read | Stove_IStoveConfirmPurchaseOutcome_GetChargeInfoAt() | The "charge-info" entry at position index (starting from 0). If it is index >= ChargeInfoCount, it returns nullptr. |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | SDK |
| Responsibility for Dismantling | SDK (Do Not Unlock, Invalid once the callback completes) |
Example
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
IsConfirmedisfalse, 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
typedef struct IStoveConfirmPurchaseParam IStoveConfirmPurchaseParam;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Required | Accessor | Description |
|---|---|---|---|---|---|
TxnMasterNo | int64_t | Reading and Writing | Yes | Stove_IStoveConfirmPurchaseParam_GetTxnMasterNo() / Stove_IStoveConfirmPurchaseParam_SetTxnMasterNo() | Transaction master number received from IStoveStartPurchaseOutcome |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | Caller (Stove_CreateParam(k_EStoveIAPTypeKind_ConfirmPurchaseParam)) |
| Responsibility for Dismantling | Caller (Destroy() required) |
Example
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 theTxnMasterNovalue from IStoveStartPurchaseOutcome, which is the result of Stove_StartPurchase, as is. - Purchases that begin with
Operation == Defaultmust 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
typedef struct IStoveFetchAchievementParam IStoveFetchAchievementParam;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Required | Access | Accessor | Description |
|---|---|---|---|---|---|
AchievementId | const wchar_t* | Yes | Reading and Writing | Stove_IStoveFetchAchievementParam_GetAchievementId() / SetAchievementId() | This is the achievement ID to look up. |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | Caller (Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchAchievementParam)) |
| Responsibility for Dismantling | Caller (Destroy() required) |
Example
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
- This query retrieves only one achievement. To retrieve multiple achievements at once, use IStoveFetchAchievementsParam and Stove_FetchAchievements.
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
AchievementIdandPageSize, 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
typedef struct IStoveFetchAchievementsParam IStoveFetchAchievementsParam;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Required | Access | Accessor | Description |
|---|---|---|---|---|---|
AchievementId | const wchar_t* | No | Reading and Writing | Stove_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. |
PageSize | uint32_t | No | Reading and Writing | Stove_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
| Item | Value |
|---|---|
| Creating Entity | Caller (Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchAchievementsParam)) |
| Responsibility for Dismantling | Caller (Destroy() required) |
Example
// 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
typedef struct IStoveFetchProductsParam IStoveFetchProductsParam;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Required | Accessor | Description |
|---|---|---|---|---|---|
CategoryId | const wchar_t* | Reading and Writing | No | Stove_IStoveFetchProductsParam_GetCategoryId() / Stove_IStoveFetchProductsParam_SetCategoryId() | Category ID filter. Leave this blank to view products from all categories. |
PageIndex | uint32_t | Reading and Writing | Yes | Stove_IStoveFetchProductsParam_GetPageIndex() / Stove_IStoveFetchProductsParam_SetPageIndex() | Page number (starting from 1). This matches the value page_no sent to the server. |
PageSize | uint32_t | Reading and Writing | Yes | Stove_IStoveFetchProductsParam_GetPageSize() / Stove_IStoveFetchProductsParam_SetPageSize() | Number of products per page |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | Caller (Stove_CreateParam(k_EStoveIAPTypeKind_FetchProductsParam)) |
| Responsibility for Dismantling | Caller (Destroy() required) |
Example
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
CategoryIdblank, products from all categories will be displayed. To view products from a specific category, please specify the value ofCategoryIdin 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
typedef struct IStoveFetchRankingParam IStoveFetchRankingParam;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Required | Access | Accessor | Description |
|---|---|---|---|---|---|
LeaderboardId | const wchar_t* | Yes | Reading and Writing | Stove_IStoveFetchRankingParam_GetLeaderboardId() / SetLeaderboardId() | This is a leaderboard identifier generated by the studio. |
PageIndex | uint32_t | Yes | Reading and Writing | Stove_IStoveFetchRankingParam_GetPageIndex() / SetPageIndex() | This is the page number to view (1 <= pageIndex). |
PageSize | uint32_t | Yes | Reading and Writing | Stove_IStoveFetchRankingParam_GetPageSize() / SetPageSize() | The number of rankings to display per page (1 <= pageSize <= 50). |
IncludeMyRank | bool | Yes | Reading and Writing | Stove_IStoveFetchRankingParam_GetIncludeMyRank() / SetIncludeMyRank() | This determines whether the search results should include the logged-in user's own ranking. |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | Caller (Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchRankingParam)) |
| Responsibility for Dismantling | Caller (Destroy() required) |
Example
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
- The query results are passed as the IStoveRanking callback argument, and each ranking entry is IStoveRank.
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
typedef struct IStoveFetchStatParam IStoveFetchStatParam;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Required | Access | Accessor | Description |
|---|---|---|---|---|---|
StatsId | const wchar_t* | Yes | Reading and Writing | Stove_IStoveFetchStatParam_GetStatsId() / SetStatsId() | This is the ID of the statistic to retrieve. Format: [A-Z0-9\-_]*$ (uppercase letters, numbers, underscores, hyphens) |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | Caller (Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchStatParam)) |
| Responsibility for Revocation | Caller (Destroy() required) |
Example
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
typedef struct IStoveFetchTermsAgreementParam IStoveFetchTermsAgreementParam;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Required | Accessor | Description |
|---|---|---|---|---|---|
Operation | EStoveTermsOperation | Reading and Writing | Yes | Stove_IStoveFetchTermsAgreementParam_GetOperation() / Stove_IStoveFetchTermsAgreementParam_SetOperation() | Mode Selector |
WebViewMode | EStoveWebViewMode | Reading and Writing | No | Stove_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. |
WebViewPosX | int32_t | Reading and Writing | No | Stove_IStoveFetchTermsAgreementParam_GetWebViewPosX() / Stove_IStoveFetchTermsAgreementParam_SetWebViewPosX() | WebView x-coordinate (pixels). Applies only when Operation != Default. IStoveWebViewLayoutParam is an inherited member. |
WebViewPosY | int32_t | Reading and Writing | No | Stove_IStoveFetchTermsAgreementParam_GetWebViewPosY() / Stove_IStoveFetchTermsAgreementParam_SetWebViewPosY() | WebView y-coordinate (pixels). Applies only when Operation != Default is true. IStoveWebViewLayoutParam is an inherited member. |
WebViewWidth | int32_t | Reading and Writing | No | Stove_IStoveFetchTermsAgreementParam_GetWebViewWidth() / Stove_IStoveFetchTermsAgreementParam_SetWebViewWidth() | WebView width (pixels). Applies only when Operation != Default is true. It is an inherited member of IStoveWebViewLayoutParam. |
WebViewHeight | int32_t | Reading and Writing | No | Stove_IStoveFetchTermsAgreementParam_GetWebViewHeight() / Stove_IStoveFetchTermsAgreementParam_SetWebViewHeight() | WebView height (pixels). Applies only when Operation != Default. This is an inherited member of IStoveWebViewLayoutParam. |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | Caller (Stove_CreateParam(k_EStoveIAPTypeKind_FetchTermsAgreementParam)) |
| Responsibility for Dismantling | Caller (Destroy() required) |
Example
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
OperationIf this isDefault, theWebView*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
typedef struct IStoveGds IStoveGds;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
IsDefault | bool | Read | Stove_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. |
Nation | const wchar_t* | Read | Stove_IStoveGds_GetNation() | This is the country code (ISO 3166-1 ALPHA-2) determined based on the logged-in user's IP address. |
Regulation | const wchar_t* | Read | Stove_IStoveGds_GetRegulation() | This is the name of the regulation that applies based on the country code (e.g., GDPR). |
Timezone | const wchar_t* | Read | Stove_IStoveGds_GetTimezone() | This is the logged-in user's time zone (IANA Time Zone Database ID, e.g., L"Asia/Seoul"). |
UtcOffset | int32_t | Read | Stove_IStoveGds_GetUtcOffset() | This is the UTC offset (in minutes) for the user's time zone. |
Lang | const wchar_t* | Read | Stove_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
| Item | Value |
|---|---|
| Creator | SDK (passed as an out parameter to Stove_GetGds()) |
| Responsibility for Dismantling | Caller (Destroy() required) |
Example
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.
MainWndHandleis a valid value only after the game's main window has actually been created.
Declaration
typedef struct IStoveInitializeParam IStoveInitializeParam;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
ShopKey | const wchar_t* | Reading and Writing | Stove_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. |
MainWndHandle | const void* | Reading and Writing | Stove_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
| Item | Value |
|---|---|
| Creating Entity | Caller (Stove_CreateParam(k_EStoveBaseTypeKind_InitializeParam)) |
| Responsibility for Dismantling | Caller (Destroy() required), Release this after the API call is complete. |
Example
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 callingStove_Initialize(). ShopKeyandMainWndHandleare 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 callStove_Uninitialize()and then callStove_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
typedef struct IStoveInventoryItem IStoveInventoryItem;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
TxnMasterNo | int64_t | Read | Stove_IStoveInventoryItem_GetTxnMasterNo() | Transaction Master Number |
TxnDetailNo | int64_t | Read | Stove_IStoveInventoryItem_GetTxnDetailNo() | Transaction Detail Number (TID by Product) |
ProductId | int64_t | Read | Stove_IStoveInventoryItem_GetProductId() | Platform-Specific Product Identifier |
InserviceItemId | const wchar_t* | Read | Stove_IStoveInventoryItem_GetInserviceItemId() | In-game item identifiers mapped to this product |
ProductName | const wchar_t* | Read | Stove_IStoveInventoryItem_GetProductName() | Localized Product Names |
Quantity | int32_t | Read | Stove_IStoveInventoryItem_GetQuantity() | Quantity Purchased |
ThumbnailUrl | const wchar_t* | Read | Stove_IStoveInventoryItem_GetThumbnailUrl() | Product Main Thumbnail Image URL |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | SDK |
| Responsibility for Revocation | SDK (Do Not Unlock, Invalid Once Callback Completes) |
Example
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 callDestroy(); instead, copy any values that need to be preserved within the callback.
Declaration
typedef struct IStoveInventoryList IStoveInventoryList;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
Count | uint32_t | Read | Stove_IStoveInventoryList_GetCount() | Number of purchase history entries included in the results |
At(index) | const IStoveInventoryItem* | Read | Stove_IStoveInventoryList_GetAt() | The purchase history entry at position index (starting from 0). If the value is index >= Count, it returns nullptr. |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | SDK |
| Responsibility for Termination | SDK (Do Not Unlock, Invalid Once Callback Completes) |
Example
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
typedef struct IStoveOrderProductParam IStoveOrderProductParam;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Required | Accessor | Description |
|---|---|---|---|---|---|
ProductId | int64_t | Reading and Writing | Yes | Stove_IStoveOrderProductParam_GetProductId() / Stove_IStoveOrderProductParam_SetProductId() | Platform-specific product identifier. Must match ProductId for IStoveProduct. |
SalePrice | double | Reading and Writing | Yes | Stove_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. |
Quantity | int32_t | Reading and Writing | Yes | Stove_IStoveOrderProductParam_GetQuantity() / Stove_IStoveOrderProductParam_SetQuantity() | Quantity to Purchase |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | Caller (Stove_CreateParam(k_EStoveIAPTypeKind_OrderProductParam)) |
| Responsibility for Dismantling | Caller (Destroy() required) |
Example
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 type | Value to take | Note |
|---|---|---|
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 chose | IStoveProduct::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.
// 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 theIStoveOrderProductParamobject and must callDestroy()directly after the purchase call is complete.- For
SalePrice, please use the sameSalePricevalue as IStoveProduct. If the values differ, the server may treat this as a price discrepancy. Quantityis the purchase quantity the user chose. Do not copyQuantityof 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
typedef struct IStoveOverImmersionInfo IStoveOverImmersionInfo;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
Msg | const wchar_t* | Read | Stove_IStoveOverImmersionInfo_GetMsg() | This is a warning about excessive engagement. |
ElapsedHours | int32_t | Read | Stove_IStoveOverImmersionInfo_GetElapsedHours() | This is the cumulative time spent playing the game (in hours). |
ExposureTime | int32_t | Read | Stove_IStoveOverImmersionInfo_GetExposureTime() | This is the message display time (in seconds). |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | SDK |
| Responsibility for Dismantling | SDK, Passed only as a callback argument and invalidated once the callback completes. The caller does not call Destroy(). |
Example
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.
ElapsedHoursrepresents hours. Be careful not to confuse it withElapsedMinutes, 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
typedef struct IStoveOwnership IStoveOwnership;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
GameId | const wchar_t* | Read | Stove_IStoveOwnership_GetGameId() | This is the STOVE game ID associated with this ownership entry. |
GameCode | int32_t | Read | Stove_IStoveOwnership_GetGameCode() | This is the product category for this item. EStoveOwnershipGameCode (Basic / Demo / DLC, etc.) |
OwnershipCode | int32_t | Read | Stove_IStoveOwnership_GetOwnershipCode() | Ownership status of the item. EStoveOwnershipCode (Acquire / Lose / None) |
PurchaseDate | uint64_t | Read | Stove_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
| Item | Value |
|---|---|
| Creating Entity | SDK |
| Responsibility for Dismantling | SDK (Do Not Unlock), This will be invalidated once the OnOwnershipListCallback callback completes. |
Example
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.
PurchaseDateis provided as a Unix epoch in UTC milliseconds, and sincepurchaseDatein 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 byGetAt()will all be invalidated once the callback ends. Any values needed outside the callback must be copied beforehand within the callback.
Declaration
typedef struct IStoveOwnershipList IStoveOwnershipList;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
Count | uint32_t | Read | Stove_IStoveOwnershipList_GetCount() | The total number of ownership entries in the list. |
At[index] | const IStoveOwnership* | Read | Stove_IStoveOwnershipList_GetAt(index) | Returns the indexth ownership entry. If index is out of range, returns nullptr. |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | SDK |
| Responsibility for Dismantling | SDK (Do Not Unlock), Once the OnOwnershipListCallback callback completes, the list and each item returned by GetAt() will be invalidated. |
Example
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()andGetAt().
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
typedef struct IStoveProduct IStoveProduct;
// To access members, use the access functions listed in the member table below.
Members
Basic Information
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
ProductId | int64_t | Read | Stove_IStoveProduct_GetProductId() | Platform-Specific Product Identifier |
InserviceItemId | const wchar_t* | Read | Stove_IStoveProduct_GetInserviceItemId() | In-game item identifiers mapped to this product |
ProductName | const wchar_t* | Read | Stove_IStoveProduct_GetProductName() | Localized Product Names |
ProductDescription | const wchar_t* | Read | Stove_IStoveProduct_GetProductDescription() | Localized Product Descriptions |
Quantity | int32_t | Read | Stove_IStoveProduct_GetQuantity() | Number of items awarded per purchase of this product |
ProductTypeCode | EStoveProductTypeCode | Read | Stove_IStoveProduct_GetProductTypeCode() | Product Category Code |
CategoryId | const wchar_t* | Read | Stove_IStoveProduct_GetCategoryId() | The store category identifier for this product |
CategoryName | const wchar_t* | Read | Stove_IStoveProduct_GetCategoryName() | The localized name of the store category to which this product belongs |
ThumbnailUrl | const wchar_t* | Read | Stove_IStoveProduct_GetThumbnailUrl() | Product Main Thumbnail Image URL |
Price
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
CurrencyCode | const wchar_t* | Read | Stove_IStoveProduct_GetCurrencyCode() | ISO 4217 currency codes (e.g., L"USD", L"KRW") |
Price | double | Read | Stove_IStoveProduct_GetPrice() | List price used for payment processing |
DisplayPrice | double | Read | Stove_IStoveProduct_GetDisplayPrice() | List price displayed on screen (may differ from Price due to rounding, etc.) |
StrDisplayPrice | const wchar_t* | Read | Stove_IStoveProduct_GetStrDisplayPrice() | Display price string with currency format applied |
SalePrice | double | Read | Stove_IStoveProduct_GetSalePrice() | Selling price used for payment processing (same as Price unless a discount is applied) |
DisplaySalePrice | double | Read | Stove_IStoveProduct_GetDisplaySalePrice() | Selling price displayed on the screen |
StrDisplaySalePrice | const wchar_t* | Read | Stove_IStoveProduct_GetStrDisplaySalePrice() | Display price string with currency format applied |
Discount
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
IsDiscounted | bool | Read | Stove_IStoveProduct_IsDiscounted() | Whether there is a current discount |
DiscountType | EStoveDiscountType | Read | Stove_IStoveProduct_GetDiscountType() | Discount Calculation Method |
DiscountTypeValue | int32_t | Read | Stove_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. |
DiscountStartDate | int64_t | Read | Stove_IStoveProduct_GetDiscountStartDate() | Discount Start Time (UTC epoch milliseconds) |
DiscountEndDate | int64_t | Read | Stove_IStoveProduct_GetDiscountEndDate() | Discount End Time (UTC epoch milliseconds) |
Purchase Quantity and History
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
TotalQuantity | int32_t | Read | Stove_IStoveProduct_GetTotalQuantity() | Total quantity of this product purchased across all categories |
MemberQuantity | int32_t | Read | Stove_IStoveProduct_GetMemberQuantity() | Quantity purchased under the login account (member) |
GuidQuantity | int32_t | Read | Stove_IStoveProduct_GetGuidQuantity() | Quantity purchased within the current character GUID range |
HasPurchased | bool | Read | Stove_IStoveProduct_HasPurchased() | Whether the user has ever purchased this product |
IsWithdrawable | bool | Read | Stove_IStoveProduct_IsWithdrawable() | Whether the product is subject to the subscription cancellation (consumer protection refund) policy |
Purchase Limits and Sales Periods
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
PurchaseLimitTypeCode | EStovePurchaseLimitTypeCode | Read | Stove_IStoveProduct_GetPurchaseLimitTypeCode() | Purchase Restriction Policy |
PurchaseLimitCount | int32_t | Read | Stove_IStoveProduct_GetPurchaseLimitCount() | Purchase Limit Under Current Policy |
SaleLimitCount | int32_t | Read | Stove_IStoveProduct_GetSaleLimitCount() | Total sales quantity limit for the product (0 means unlimited) |
SalesStartDate | int64_t | Read | Stove_IStoveProduct_GetSalesStartDate() | Start time of the sales period (UTC epoch milliseconds) |
SalesEndDate | int64_t | Read | Stove_IStoveProduct_GetSalesEndDate() | End Time of the Sales Period (UTC epoch milliseconds) |
PurchaseAvailabilityCode | int16_t | Read | Stove_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
| Item | Value |
|---|---|
| Creating Entity | SDK |
| Responsibility for Dismantling | SDK (Do Not Release, Invalid Once Callback Completes) |
Example
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/SalePricefor payment processing (server verification), andDisplayPrice/DisplaySalePrice/StrDisplayPrice/StrDisplaySalePricefor 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
SalePricevalue for this product as-is toSalePricein IStoveOrderProductParam. DiscountStartDate/DiscountEndDate/SalesStartDate/SalesEndDateare all integers representing UTC epoch milliseconds (milliseconds since January 1, 1970, UTC). They are not in theYYYYMMDDHHMMSSformat.- For how to move the values into the purchase parameter, see Mapping from IStoveProduct in IStoveOrderProductParam.
Quantityis 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 callDestroy(); instead, copy any values you need to preserve within the callback.
Declaration
typedef struct IStoveProductList IStoveProductList;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
Count | uint32_t | Read | Stove_IStoveProductList_GetCount() | Number of items in the results |
At(index) | const IStoveProduct* | Read | Stove_IStoveProductList_GetAt() | The item at position index (starting from 0). If it is index >= Count, it returns nullptr. |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | SDK |
| Responsibility for Dismantling | SDK (Do not unlock, becomes invalid once the callback is complete) |
Example
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
typedef struct IStovePurchasedProduct IStovePurchasedProduct;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
TxnDetailNo | int64_t | Read | Stove_IStovePurchasedProduct_GetTxnDetailNo() | Transaction Detail Number (TID for each product within the master transaction) |
ProductId | int64_t | Read | Stove_IStovePurchasedProduct_GetProductId() | Platform-Specific Product Identifier |
CategoryId | const wchar_t* | Read | Stove_IStovePurchasedProduct_GetCategoryId() | The store category identifier for this product |
TotalQuantity | int32_t | Read | Stove_IStovePurchasedProduct_GetTotalQuantity() | Total purchase quantity for this item |
MemberQuantity | int32_t | Read | Stove_IStovePurchasedProduct_GetMemberQuantity() | Quantity purchased within the member (account) scope |
GuidQuantity | int32_t | Read | Stove_IStovePurchasedProduct_GetGuidQuantity() | Quantity purchased within the current character GUID range |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | SDK |
| Responsibility for Dismantling | SDK (Do not unwrap, becomes invalid once the callback completes) |
Example
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
- It is passed from both
PurchasedProductAt()of IStoveStartPurchaseOutcome andPurchasedProductAt()of IStoveConfirmPurchaseOutcome. - When distributing in-game items, duplicate distributions must be prevented based on
TxnDetailNo.
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
typedef struct IStovePurchaseParam IStovePurchaseParam;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Required | Accessor | Description |
|---|---|---|---|---|---|
Operation | EStovePurchaseOperation | Reading and Writing | Yes | Stove_IStovePurchaseParam_GetOperation() / Stove_IStovePurchaseParam_SetOperation() | Mode Selector |
WebViewMode | EStoveWebViewMode | Reading and Writing | No | Stove_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. |
WebViewPosX | int32_t | Reading and Writing | No | Stove_IStovePurchaseParam_GetWebViewPosX() / Stove_IStovePurchaseParam_SetWebViewPosX() | WebView x-coordinate (pixels). Applies only when Operation != Default. This is an inherited member of IStoveWebViewLayoutParam. |
WebViewPosY | int32_t | Reading and Writing | No | Stove_IStovePurchaseParam_GetWebViewPosY() / Stove_IStovePurchaseParam_SetWebViewPosY() | WebView y-coordinate (pixels). Applies only when Operation != Default. This is an inherited member of IStoveWebViewLayoutParam. |
WebViewWidth | int32_t | Reading and Writing | No | Stove_IStovePurchaseParam_GetWebViewWidth() / Stove_IStovePurchaseParam_SetWebViewWidth() | WebView width (pixels). Applies only when Operation != Default is true. It is an inherited member of IStoveWebViewLayoutParam. |
WebViewHeight | int32_t | Reading and Writing | No | Stove_IStovePurchaseParam_GetWebViewHeight() / Stove_IStovePurchaseParam_SetWebViewHeight() | WebView height (pixels). Applies only when Operation != Default. This is an inherited member of IStoveWebViewLayoutParam. |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | Caller (Stove_CreateParam(k_EStoveIAPTypeKind_PurchaseParam)) |
| Responsibility for Dismantling | Caller (Destroy() required) |
Example
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 callDestroy()directly after the purchase call is complete.OperationIf this isDefault, theWebView*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
typedef struct IStoveRank IStoveRank;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
Nickname | const wchar_t* | Read | Stove_IStoveRank_GetNickname() | This is the user's nickname. |
ProfileImage | const wchar_t* | Read | Stove_IStoveRank_GetProfileImage() | This is the URL for the user's profile picture. |
Score | int32_t | Read | Stove_IStoveRank_GetScore() | Here are the leaderboard scores. |
Rank | uint32_t | Read | Stove_IStoveRank_GetRank() | This is the user's current ranking. |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | SDK |
| Responsibility for Dismantling | SDK (Do not unwrap. If the IStoveRanking callback parameter containing this object is invalidated, it will be invalidated as well) |
Example
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
typedef struct IStoveRanking IStoveRanking;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
Count | uint32_t | Read | Stove_IStoveRanking_GetCount() | This is the number of ranking items included on this page. |
| , | const IStoveRank* | Read | Stove_IStoveRanking_GetAt(index) | Retrieves the ranking entry starting from index 0. If the index is index >= Count, it returns NULL. |
TotalCount | uint32_t | Read | Stove_IStoveRanking_GetTotalCount() | This is the total number of ranking items across the entire page. |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | SDK |
| Responsibility for Dismantling | SDK (Do not disable. It will be invalidated once the Stove_FetchRanking callback completes) |
Example
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
typedef struct IStoveRestartAppIfNecessaryOutcome IStoveRestartAppIfNecessaryOutcome;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
IsRestartRequired | bool | Read | Stove_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
| Item | Value |
|---|---|
| Creating Entity | SDK |
| Responsibility for Dismantling | SDK, Passed only as a callback argument and is invalidated once the callback completes. The caller does not call Destroy(). |
Example
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 beforeStove_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
typedef struct IStoveRestartAppIfNecessaryParam IStoveRestartAppIfNecessaryParam;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
Environment | const wchar_t* | Reading and Writing | Stove_IStoveRestartAppIfNecessaryParam_GetEnvironment() / SetEnvironment() | These are the Stove environment values. |
GameId | const wchar_t* | Reading and Writing | Stove_IStoveRestartAppIfNecessaryParam_GetGameId() / SetGameId() | This is the Stove game ID. |
AppKey | const wchar_t* | Reading and Writing | Stove_IStoveRestartAppIfNecessaryParam_GetAppKey() / SetAppKey() | This is the Stove application key value. |
WaitTimeMilliSec | uint32_t | Reading and Writing | Stove_IStoveRestartAppIfNecessaryParam_GetWaitTimeMilliSec() / SetWaitTimeMilliSec() | This is the wait time (in milliseconds) used to determine whether the app was launched via the launcher. |
LaunchStoveLauncher | bool | Reading and Writing | Stove_IStoveRestartAppIfNecessaryParam_GetLaunchStoveLauncher() / SetLaunchStoveLauncher() | This determines whether to launch the Stove launcher when it is not currently running. |
PlatformName | const wchar_t* | Reading and Writing | Stove_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
| Item | Value |
|---|---|
| Creating Entity | Caller (Stove_CreateParam(k_EStoveBaseTypeKind_RestartAppIfNecessaryParam)) |
| Responsibility for Dismantling | Caller (Destroy() required), Release this after the API call is complete. |
Example
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 beforeStove_Initialize(). The SDK reuses the cached Environment/GameId/AppKey from this call in the subsequentStove_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 inIStoveInitializeParam. PlatformNameis used to specify the IPC path for communicating with the launcher. If the value is left blank orL"Stove"is specified, the existing path is used. If you enter an arbitrary value not supported by the launcher, the path will change, causingk_EStoveResultCode_IpcConnectFailed(307) ork_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
typedef struct IStoveResult IStoveResult;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
MethodCode | uint32_t | Read | Stove_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). |
ResultCode | uint32_t | Read | Stove_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–). |
IsSuccessful | bool | Read | Stove_IStoveResult_IsSuccessful() | Whether it succeeds (the same check as whether ResultCode is 0). |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | SDK (Return Value of a Synchronous API Call) |
| Responsibility for Dismantling | Caller (Destroy() required) |
Example
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_InitializeandStove_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
EStoveBaseResultCodehas been discontinued and consolidated intoEStoveResultCode. - The flat C access function includes
Stove_IStoveResult_IsSuccessful(), which allows you to immediately obtain the same result asGetResultCode() == 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
typedef struct IStoveSendLogParam IStoveSendLogParam;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
Auid | int64_t | Reading and Writing | Stove_IStoveSendLogParam_GetAuid() / SetAuid() | This is the account UID (STOVE account identifier). |
Cuid | int64_t | Reading and Writing | Stove_IStoveSendLogParam_GetCuid() / SetCuid() | This is the character UID (in-game character identifier). |
MktType1 | const wchar_t* | Reading and Writing | Stove_IStoveSendLogParam_GetMktType1() / SetMktType1() | This is the name of the integrated third-party marketing service (Slot 1). |
MktId1 | const wchar_t* | Reading and Writing | Stove_IStoveSendLogParam_GetMktId1() / SetMktId1() | This is an identifier (campaign/referrer ID) issued by Slot 1 Marketing Services. |
MktType2 | const wchar_t* | Reading and Writing | Stove_IStoveSendLogParam_GetMktType2() / SetMktType2() | This is the name of the integrated third-party marketing service (Slot 2). |
MktId2 | const wchar_t* | Reading and Writing | Stove_IStoveSendLogParam_GetMktId2() / SetMktId2() | This is an identifier issued by Slot 2 Marketing Services. |
GameVersion | const wchar_t* | Reading and Writing | Stove_IStoveSendLogParam_GetGameVersion() / SetGameVersion() | This is the game client version string (e.g., L"1.2.3"). |
LogGroupId | const wchar_t* | Reading and Writing | Stove_IStoveSendLogParam_GetLogGroupId() / SetLogGroupId() | A correlation ID that groups multiple related log entries into a single set. |
ServerCode | const wchar_t* | Reading and Writing | Stove_IStoveSendLogParam_GetServerCode() / SetServerCode() | This is the server code for the world/region the user is connected to. |
ServerCodeDetail | const wchar_t* | Reading and Writing | Stove_IStoveSendLogParam_GetServerCodeDetail() / SetServerCodeDetail() | ServerCode These are the detailed codes for sub-servers, channels, shards, and other elements under this level. |
LevelCode | const wchar_t* | Reading and Writing | Stove_IStoveSendLogParam_GetLevelCode() / SetLevelCode() | This is the account level at the time the log was recorded. |
LevelCodeDetail | const wchar_t* | Reading and Writing | Stove_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. |
ExternalId | const wchar_t* | Reading and Writing | Stove_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). |
Contents | const wchar_t* | Reading and Writing | Stove_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
| Item | Value |
|---|---|
| Creator | Caller (Stove_CreateParam(k_EStoveLogTypeKind_SendLogParam)) |
| Responsibility for Dismantling | Caller (Stove_IStoveTypeBase_Destroy() required), Stove_SendLog() can be released immediately after the call returns. |
Example
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/MktId1andMktType2/MktId2are two independent slots. Since they do not have a primary/fallback relationship, fill in only the corresponding slot.- Contrary to its name,
LevelCodeDetailis not a subvalue ofLevelCodebut a separate value within the character range. Contentscorresponds to theaction_paramfield 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
typedef struct IStoveSetGameProfileParam IStoveSetGameProfileParam;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
WorldId | const wchar_t* | Reading and Writing | Stove_IStoveSetGameProfileParam_GetWorldId() / SetWorldId() | This is the game's world identifier. |
CharacterNo | int64_t | Reading and Writing | Stove_IStoveSetGameProfileParam_GetCharacterNo() / SetCharacterNo() | This is the character number on the server. |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | Caller (Stove_CreateParam(k_EStoveBaseTypeKind_SetGameProfileParam)) |
| Responsibility for Dismantling | Caller (Destroy() required), Release this after the API call is complete. |
Example
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, theCharacterNofield was incorrectly labeled as "worldId Length", it is actually a character number, and theCharacterNolabel 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
typedef struct IStoveSetStatOutcome IStoveSetStatOutcome;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
ErrorMessage | const wchar_t* | Read | Stove_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. |
CurrentValue | int32_t | Read | Stove_IStoveSetStatOutcome_GetCurrentValue() | This is the current (updated) value of the statistics reflecting the changes. |
IsUpdated | bool | Read | Stove_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
| Item | Value |
|---|---|
| Creator | SDK |
| Responsibility for Dismantling | SDK (Do not disable. It will be invalidated once the Stove_SetStat callback completes) |
Example
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,
IsUpdatedis passed asfalse. This does not indicate a failure; it simply means the value has not changed, so it should not be treated as an error. ErrorMessagemay be populated even when the call is successful.- If the value you are trying to set exceeds the
int32range, it will be truncated to2147483647. Even in this case, the call will succeed, andIsUpdatedwill be passed astrue. - You can check whether the value has been truncated by seeing if
integer overflowis stored inErrorMessage.
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
typedef struct IStoveSetStatParam IStoveSetStatParam;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Required | Access | Accessor | Description |
|---|---|---|---|---|---|
StatsId | const wchar_t* | Yes | Reading and Writing | Stove_IStoveSetStatParam_GetStatsId() / SetStatsId() | This is the ID of the statistic to be edited. Format: [A-Z0-9\-_]*$ (uppercase letters, numbers, underscores, hyphens) |
StatValue | int32_t | Yes | Reading and Writing | Stove_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
| Item | Value |
|---|---|
| Creating Entity | Caller (Stove_CreateParam(k_EStoveGameSupportTypeKind_SetStatParam)) |
| Responsibility for Dismantling | Caller (Destroy() required) |
Example
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
StatsIdandStatValueto be able to submit edit requests properly. StatValueis 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
typedef struct IStoveShopCategory IStoveShopCategory;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
CategoryId | const wchar_t* | Read | Stove_IStoveShopCategory_GetCategoryId() | Category Identifier |
CategoryParentId | const wchar_t* | Read | Stove_IStoveShopCategory_GetCategoryParentId() | Parent category identifier. The top-level category is empty. |
CategoryDisplayNo | int32_t | Read | Stove_IStoveShopCategory_GetCategoryDisplayNo() | Display Order Within the Same Tier |
CategoryName | const wchar_t* | Read | Stove_IStoveShopCategory_GetCategoryName() | Localized category names |
CategoryDepth | int32_t | Read | Stove_IStoveShopCategory_GetCategoryDepth() | Depth in the category tree (0 = top level) |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | SDK |
| Responsibility for Dismantling | SDK (Do Not Unlock, Invalid Once Callback Completes) |
Example
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
CategoryParentIdis empty, this is the top-level category. - IStoveProduct's
CategoryIdandCategoryNamecorrespond 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 callDestroy(); instead, copy any values you need to preserve within the callback.
Declaration
typedef struct IStoveShopCategoryList IStoveShopCategoryList;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
Count | uint32_t | Read | Stove_IStoveShopCategoryList_GetCount() | Number of store categories included in the results |
At(index) | const IStoveShopCategory* | Read | Stove_IStoveShopCategoryList_GetAt() | The store category at position index (starting from 0). If the value is index >= Count, it returns nullptr. |
Memory Management
| Item | Value |
|---|---|
| Creator | SDK |
| Responsibility for Dismantling | SDK (Do Not Unlock, Invalid Once Callback Completes) |
Example
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
typedef struct IStoveShutdownInfo IStoveShutdownInfo;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
Msg | const wchar_t* | Read | Stove_IStoveShutdownInfo_GetMsg() | This is a shutdown notification message. |
ExposureTime | int32_t | Read | Stove_IStoveShutdownInfo_GetExposureTime() | This is the shutdown message display time (in seconds). |
InadvanceMinutes | int32_t | Read | Stove_IStoveShutdownInfo_GetInadvanceMinutes() | This is the time remaining (in minutes) until the user's session is shut down. |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | SDK |
| Responsibility for Dismantling | SDK, Passed only as a callback argument and invalidated once the callback completes. The caller does not call Destroy(). |
Example
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
ShutdownNotificationis 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
typedef struct IStoveSignin IStoveSignin;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
IsPersonVerified | bool | Read | Stove_IStoveSignin_IsPersonVerified() | This indicates whether the user has completed identity verification. |
IsEmailVerified | bool | Read | Stove_IStoveSignin_IsEmailVerified() | This indicates whether the user has completed email verification. |
RegisteredCountryCode | const wchar_t* | Read | Stove_IStoveSignin_GetRegisteredCountryCode() | This is the country code for the Stove platform (ISO 3166-1 ALPHA-2). |
ProviderCode | const wchar_t* | Read | Stove_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. |
AccountType | int32_t | Read | Stove_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
| Item | Value |
|---|---|
| Creating Entity | SDK (passed as an out parameter to Stove_GetSignin()) |
| Responsibility for Dismantling | Caller (Destroy() required) |
Example
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. AccountTypeis a numeric code, andProviderCodeis a string code; they represent the same authentication method using different notations. UseProviderCodewhen 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.
OperationIf this isDefault,TempPaymentUrlwill be filled in for manual payment processing.OperationIf this isWithWebViewAndConfirmResult, thenIsPurchased,PurchasedProduct*, andChargeInfo*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
TxnDetailNosand the items obtained viaPurchasedProductAt()/ChargeInfoAt()are all owned by the SDK and are no longer valid once the callback completes. Do not callDestroy(); instead, copy any values you need to preserve within the callback.
Declaration
typedef struct IStoveStartPurchaseOutcome IStoveStartPurchaseOutcome;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
TxnMasterNo | int64_t | Read | Stove_IStoveStartPurchaseOutcome_GetTxnMasterNo() | Transaction Master Number (TID per purchase) |
TxnDetailNos | const int64_t* | Read | Stove_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. |
TxnDetailNosCount | uint32_t | Read | Stove_IStoveStartPurchaseOutcome_GetTxnDetailNosCount() | The number of elements in the array pointed to by TxnDetailNos |
TempPaymentUrl | const wchar_t* | Read | Stove_IStoveStartPurchaseOutcome_GetTempPaymentUrl() | A one-time payment URL. Provided when Operation == Default. |
PurchaseProgress | EStovePurchaseProgress | Read | Stove_IStoveStartPurchaseOutcome_GetPurchaseProgress() | Purchase Status |
IsPurchased | bool | Read | Stove_IStoveStartPurchaseOutcome_IsPurchased() | Operation == WithWebViewAndConfirmResult, and if the payment was successfully completed, true. Otherwise, false. |
ExtraData | const wchar_t* | Read | Stove_IStoveStartPurchaseOutcome_GetExtraData() | Echo of the ExtraData string passed when calling Stove_StartPurchase |
PurchasedProductCount | uint32_t | Read | Stove_IStoveStartPurchaseOutcome_GetPurchasedProductCount() | Number of items purchased. Operation == WithWebViewAndConfirmResult; this field is populated when the payment is successful. |
PurchasedProductAt(index) | const IStovePurchasedProduct* | Read | Stove_IStoveStartPurchaseOutcome_GetPurchasedProductAt() | The purchased item at position index (starting from 0). If it is index >= PurchasedProductCount, it returns nullptr. |
ChargeInfoCount | uint32_t | Read | Stove_IStoveStartPurchaseOutcome_GetChargeInfoCount() | The number of "charge-info" entries describing the currency used for the payment |
ChargeInfoAt(index) | const IStoveChargeInfo* | Read | Stove_IStoveStartPurchaseOutcome_GetChargeInfoAt() | The "charge-info" entry at position index (starting from 0). If the value is index >= ChargeInfoCount, it returns nullptr. |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | SDK |
| Responsibility for Dismantling | SDK (Do Not Unlock, Invalid once the callback is complete) |
Example
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
PurchaseProgressisNeedPaymentWindow, open the payment window atTempPaymentUrl, and after completing payment, confirm the purchase at Stove_ConfirmPurchase. ExtraDatareturns theExtraDataof 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
- Stove_StartPurchase
- Stove_ConfirmPurchase
- IStoveStartPurchaseParam
- IStovePurchasedProduct
- IStoveChargeInfo
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
typedef struct IStoveStartPurchaseParam IStoveStartPurchaseParam;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Required | Accessor | Description |
|---|---|---|---|---|---|
Products | const IStoveOrderProductParam* const* / IStoveOrderProductParam** | Reading and Writing | Yes | Stove_IStoveStartPurchaseParam_GetProducts() / Stove_IStoveStartPurchaseParam_SetProducts() | Arrangement of Order Items by Product to Be Purchased |
ProductsCount | uint32_t | Read | , | Stove_IStoveStartPurchaseParam_GetProductsCount() | Products The number of elements in the array. It is specified when SetProducts() is called. |
PurchaseParam | const IStovePurchaseParam* / IStovePurchaseParam* | Reading and Writing | Yes | Stove_IStoveStartPurchaseParam_GetPurchaseParam() / Stove_IStoveStartPurchaseParam_SetPurchaseParam() | Purchase Behavior Options (Including Web View Placement) |
ServiceTxnNo | const wchar_t* | Reading and Writing | No | Stove_IStoveStartPurchaseParam_GetServiceTxnNo() / Stove_IStoveStartPurchaseParam_SetServiceTxnNo() | Service-side transaction number issued by the game (optional) |
ExtraData | const wchar_t* | Reading and Writing | No | Stove_IStoveStartPurchaseParam_GetExtraData() / Stove_IStoveStartPurchaseParam_SetExtraData() | Additional request data (typically a JSON string; optional). It is returned as-is from IStoveStartPurchaseOutcome to ExtraData. |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | Caller (Stove_CreateParam(k_EStoveIAPTypeKind_StartPurchaseParam)) |
| Responsibility for Dismantling | Caller (Destroy() required) |
Example
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()andSetPurchaseParam()do not acquire ownership. The caller retains ownership of the passed IStoveOrderProductParam and IStovePurchaseParam objects and can callDestroy()directly on each of them at any time afterStove_StartPurchase()is returned. SinceStove_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
- Stove_StartPurchase
- IStoveOrderProductParam
- IStovePurchaseParam
- IStoveStartPurchaseOutcome
- Stove_ConfirmPurchase
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
typedef struct IStoveStat IStoveStat;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
StatsFullId | const IStoveStatFullId* | Read | Stove_IStoveStat_GetStatsFullId() | This is the complete set of identifying information for the statistics. |
UpdatedAt | uint64_t | Read | Stove_IStoveStat_GetUpdatedAt() | This is the last update time (epoch time, in milliseconds). |
CurrentValue | int32_t | Read | Stove_IStoveStat_GetCurrentValue() | This is the current value of the statistic. |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | SDK |
| Responsibility for Dismantling | SDK (Do not disable. It will be invalidated once the Stove_FetchStat callback completes) |
Example
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
StatsFullIdis 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
typedef struct IStoveStatFullId IStoveStatFullId;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
GameId | const wchar_t* | Read | Stove_IStoveStatFullId_GetGameId() | This is the game ID associated with these statistics. |
StatsId | const wchar_t* | Read | Stove_IStoveStatFullId_GetStatsId() | This is a statistics ID. Format: [A-Z0-9\-_]*$ (uppercase letters, numbers, underscores, hyphens) |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | SDK (passed as part of the IStoveStat callback argument) |
| Responsibility for Dismantling | SDK (Do not release. If the IStoveStat callback parameter containing this object is invalidated, this object will also be invalidated.) |
Example
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
StatsIdformat follows the same rules as theStatsIdin 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
typedef struct IStoveTermsAgreementOutcome IStoveTermsAgreementOutcome;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
IsAgreed | bool | Read | Stove_IStoveTermsAgreementOutcome_IsAgreed() | Whether the user has already agreed to the latest Terms of Service. If true is true, Url is an empty string. |
Url | const wchar_t* | Read | Stove_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
| Item | Value |
|---|---|
| Creating Entity | SDK |
| Responsibility for Dismantling | SDK (Do Not Unlock, Invalid Once Callback Completes) |
Example
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
- It is passed only as the output of Stove_FetchTermsAgreement.
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 callDestroy().
Declaration
typedef struct IStoveTypeBase IStoveTypeBase;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
TypeKind | int32_t | Read | Stove_IStoveTypeBase_GetTypeKind() | Returns the concrete type type (one of the EStoveBaseTypeKind values). |
ShouldDestroy | bool | Read | Stove_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. |
| , | void | Dongjak | Stove_IStoveTypeBase_Destroy() (Non-const) | Releases the object. This method must be called exactly once for each instance it owns. |
QueryExt | void* | Read | Stove_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
| Item | Value |
|---|---|
| Creating Entity | It 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 Dismantling | Instances for which ShouldDestroy() returns true call Destroy(). Instances passed as callback arguments are those for which ShouldDestroy() returns false and are not released. |
Example
IStoveResult* result = Stove_Uninitialize();
if (Stove_IStoveTypeBase_ShouldDestroy((IStoveTypeBase*)result))
{
Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result);
}
Notes
- Not only
IStoveResult,IStoveUser, andIStoveGds, 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 returnsnullptr, regardless of theextIdpassed to it, since no extensions have actually been registered for it yet.- Since the instances passed as callback arguments (such as
IStoveCallbackResultandIStoveAccessToken) 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
typedef struct IStoveUser IStoveUser;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
NickName | const wchar_t* | Read | Stove_IStoveUser_GetNickName() | This is the Stove nickname of the user logged in to the launcher. |
UserId | uint64_t | Read | Stove_IStoveUser_GetUserId() | This is the GameUserId of the user logged in to the launcher. |
Memory Management
| Item | Value |
|---|---|
| Creating Entity | SDK (passed as an out parameter to Stove_GetUser()) |
| Responsibility for Dismantling | Caller (Destroy() required) |
Example
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
typedef struct IStoveVietnamAgeRatingInfo IStoveVietnamAgeRatingInfo;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
OverlayMode | int32_t | Read | Stove_IStoveVietnamAgeRatingInfo_GetOverlayMode() | The overlay is currently displayed (SHOW: Show overlay, HIDE: Hide overlay). The value is EStoveOverlayMode. |
OverlayType | int32_t | Read | Stove_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). |
OverlayScale | float | Read | Stove_IStoveVietnamAgeRatingInfo_GetOverlayScale() | This is the overlay scale (0.0 to 1.0). |
OverlayOpacity | float | Read | Stove_IStoveVietnamAgeRatingInfo_GetOverlayOpacity() | This is the overlay opacity (0.0 to 1.0). |
AgeRating | int32_t | Read | Stove_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). |
Msg | const wchar_t* | Read | Stove_IStoveVietnamAgeRatingInfo_GetMsg() | This is an age rating notification message. |
DisplayPositionX | float | Read | Stove_IStoveVietnamAgeRatingInfo_GetDisplayPositionX() | The x-coordinate of the message display location. Measured from the left edge of the screen (0.0 to 1.0). |
DisplayPositionY | float | Read | Stove_IStoveVietnamAgeRatingInfo_GetDisplayPositionY() | The y-coordinate of the message's display position. Relative to the top of the screen (0.0 to 1.0). |
Language | const wchar_t* | Read | Stove_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
| Item | Value |
|---|---|
| Creating Entity | SDK |
| Responsibility for Dismantling | SDK, Passed only as a callback argument and invalidated once the callback completes. The caller does not call Destroy(). |
Example
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.
OverlayModeuses 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
typedef struct IStoveVietnamOverimmersionInfo IStoveVietnamOverimmersionInfo;
// To access members, use the access functions listed in the member table below.
Members
| Name | Type | Access | Accessor | Description |
|---|---|---|---|---|
OverlayMode | int32_t | Read | Stove_IStoveVietnamOverimmersionInfo_GetOverlayMode() | The overlay is currently displayed (SHOW: Show overlay, HIDE: Hide overlay). The value is EStoveOverlayMode. |
OverlayType | int32_t | Read | Stove_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). |
OverlayScale | float | Read | Stove_IStoveVietnamOverimmersionInfo_GetOverlayScale() | This is the overlay scale (0.0–1.0). |
OverlayOpacity | float | Read | Stove_IStoveVietnamOverimmersionInfo_GetOverlayOpacity() | This is the overlay opacity (0.0 to 1.0). |
AgeRating | int32_t | Read | Stove_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). |
Msg | const wchar_t* | Read | Stove_IStoveVietnamOverimmersionInfo_GetMsg() | This is a warning about excessive engagement. |
StyledMsg | const wchar_t* | Read | Stove_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. |
ElapsedMinutes | int32_t | Read | Stove_IStoveVietnamOverimmersionInfo_GetElapsedMinutes() | This is the cumulative game play time (in minutes). |
ExposureTime | int32_t | Read | Stove_IStoveVietnamOverimmersionInfo_GetExposureTime() | This is the message display time (in seconds). |
ExpandAnimationTime | float | Read | Stove_IStoveVietnamOverimmersionInfo_GetExpandAnimationTime() | This is the duration (in seconds) of the animation in which the overlay expands when switching between "Show" and "Expand." |
DisplayPositionX | float | Read | Stove_IStoveVietnamOverimmersionInfo_GetDisplayPositionX() | The x-coordinate of the message's display position. Measured from the left edge of the screen (0.0 to 1.0). |
DisplayPositionY | float | Read | Stove_IStoveVietnamOverimmersionInfo_GetDisplayPositionY() | The y-coordinate of the message's display position. Relative to the top of the screen (0.0 to 1.0). |
Language | const wchar_t* | Read | Stove_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
| Item | Value |
|---|---|
| Creating Entity | SDK |
| Responsibility for Dismantling | SDK, Passed only as a callback argument and invalidated once the callback completes. The caller does not call Destroy(). |
Example
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.
OverlayModeuses the value EStoveOverlayMode and also supportsk_EStoveOverlayMode_Expanded(expanded display).ElapsedMinutesis the unit "minute." Be careful not to confuse it withElapsedHours, 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
// 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
| Name | Type | Description |
|---|---|---|
WebViewMode | EStoveWebViewMode | WebView Display Mode (External Browser / SDK-Embedded WebView) |
WebViewPosX | int32_t | WebView x-coordinate (pixels) |
WebViewPosY | int32_t | WebView y-coordinate (pixels) |
WebViewWidth | int32_t | Web View Width (pixels) |
WebViewHeight | int32_t | WebView 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
// 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
IStovePurchaseParamandIStoveFetchTermsAgreementParam, these fields apply only when theOperationvalue for each type is notDefault. - Since
IStoveWithdrawGameParamdoes not containOperation, these fields always apply.
See Also
- IStovePurchaseParam
- IStoveFetchTermsAgreementParam
- IStoveWithdrawGameParam
- EStoveWebViewMode
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
void Stove_AccessTokenRenewed(const IStoveTypeBase* param, OnAccessTokenRenewedCallback onFinished, void* userData);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
param | const IStoveTypeBase* | N | The reserved argument ...Param TypeKind is not defined. |
onFinished | OnAccessTokenRenewedCallback | Y | This is the callback that will receive the results. |
userData | void* | N | This is the user data that is passed directly to the callback. |
Returns
None
The method code for this function is
k_EStoveBaseMethodCode_AccessTokenRenewed.
Callback
typedef void(__cdecl* OnAccessTokenRenewedCallback)(const IStoveCallbackResult* callbackResult, const IStoveAccessToken* token);
| Name | Type | Description |
|---|---|---|
callbackResult | const IStoveCallbackResult* | Here are the results of the call. |
token | const 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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 5 | k_EStoveCommonResultCode_InvalidParam | onFinished is nullptr. | x | |
| 16 | k_EStoveCommonResultCode_BaseNotInitialized | It was called before being initialized. | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unknown exception occurred during execution. | O | A temporary issue has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | An exception occurred during execution. | O | A 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
| Object | Owner | Release |
|---|---|---|
param | Caller | If delivered, Stove_IStoveTypeBase_Destroy() Required |
Callback callbackResult, token | SDK | Do not unlock. This will be invalidated once the callback is complete. |
Example
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()andStove_View_CloseAllPopups()functions that were previously used for each module. Now, a single call closes all SDK pop-ups at once.
Declaration
IStoveResult* Stove_CloseAllPopups();
Parameters
None
Returns
| Type | Description |
|---|---|
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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success (IAP · Close View Popup, All Successful) | x | |
| 68 | k_EStoveCommonResultCode_CloseAllPopupsFailed | Failed 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 | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unknown exception occurred during execution. | O | A temporary issue has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | An internal exception occurred during execution | O | A 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
| Object | Owner | Release |
|---|---|---|
Returned IStoveResult* | Caller | Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result) Required |
Example
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
void Stove_ConfirmPurchase(const IStoveConfirmPurchaseParam* param, OnConfirmPurchaseCallback onFinished, void* userData);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
param | const IStoveConfirmPurchaseParam* | Y | This is the master number (TxnMasterNo) parameter for the transaction to be finalized. |
onFinished | OnConfirmPurchaseCallback | Y | This is the callback that will receive the final results. |
userData | void* | N | This is the user data that is passed directly to the callback. |
Returns
None
The method code for this function is
k_EStoveIAPMethodCode_ConfirmPurchase.
Callback
typedef void(__cdecl* OnConfirmPurchaseCallback)(const IStoveCallbackResult* callbackResult, const IStoveConfirmPurchaseOutcome* outcome);
| Name | Type | Description |
|---|---|---|
callbackResult | const IStoveCallbackResult* | Here are the results of the call. |
outcome | const 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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 17 | k_EStoveCommonResultCode_NotInitialized | The payment feature is not initialized. | x | |
| 21 | k_EStoveCommonResultCode_NullEntity | Language information is not available (check whether Stove_SetLanguage was called). | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unhandled exception occurred during execution. | O | A temporary issue has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | A managed exception occurred during execution (including missing internal entities such as login tokens). | O | A 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
| Object | Owner | Release |
|---|---|---|
param | Caller | Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param) Required. Release after the call returns. |
Callback callbackResult | SDK | Do not unlock. This will be invalidated once the callback is complete. |
The outcome in the callback (and each IStovePurchasedProduct and IStoveChargeInfo within it) | SDK | Do not unwrap. This will be invalidated once the callback completes, so you must copy any necessary values within the callback. |
Example
// 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
onFinishedcallback. - If
Operationof Stove_StartPurchase isWithWebViewAndConfirmResult, the SDK automatically calls this function, so there is no need to call it separately. - Whether
callbackResultis successful andoutcome'sIsConfirmed()are two separate matters. Even if the call itself is successful, ifIsConfirmed()isfalse, the purchase has not been finalized. - In the Steam launcher flow,
IsConfirmed()is always delivered asfalseregardless of the server response. In that flow, treat a successful call (IsSuccessfultrue) as the purchase being confirmed, and don't referencePurchasedProductsorChargeInfos, 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, andchargeInfos. 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
IStoveTypeBase* Stove_CreateParam(int kind);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
kind | int | Y | This 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
| Type | Description |
|---|---|
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
| Object | Owner | Release |
|---|---|---|
Returned IStoveTypeBase* | Caller | Stove_IStoveTypeBase_Destroy() Required |
Example
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
void Stove_FetchAchievement(const IStoveFetchAchievementParam* param, OnGetAchievementCallback onFinished, void* userData);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
param | const IStoveFetchAchievementParam* | Y | A parameter containing the ID of the achievement to look up. Create it as Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchAchievementParam). |
onFinished | OnGetAchievementCallback | Y | Callback to receive query results |
userData | void* | N | User data passed directly to the callback |
Returns
None (void)
The method code for this function is
k_EStoveGameSupportMethodCode_FetchAchievement.
Callback
typedef void(__cdecl* OnGetAchievementCallback)(const IStoveCallbackResult* callbackResult, const IStoveAchievement* achievement);
| Name | Type | Description |
|---|---|---|
callbackResult | const IStoveCallbackResult* | Call Results |
achievement | const 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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 5 | k_EStoveCommonResultCode_InvalidParam | The achievement ID (AchievementId) for param is an empty string | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unknown exception occurred during processing | O | A temporary issue has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | An internal exception occurred during processing (e.g., failure to retrieve an entity) | O | A 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 returnsNotInitialized(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
| Object | Owner | Release |
|---|---|---|
param | Caller | Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param) Required (Can be released immediately after the Stove_FetchAchievement() call returns) |
Callback callbackResult | SDK | Do not unlock. This will be invalidated once the callback is complete. |
Callback achievement | SDK | Do not unlock. This will be invalidated once the callback is complete. |
Example
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
AchievementIdandPageSize, 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
void Stove_FetchAchievements(const IStoveFetchAchievementsParam* param, OnGetAchievementsCallback onFinished, void* userData);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
param | const IStoveFetchAchievementsParam* | Y | Query parameter. Create it as Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchAchievementsParam). In v3.5.0, pass it as is without filling in a value. |
onFinished | OnGetAchievementsCallback | Y | Callback to receive query results |
userData | void* | N | User data passed directly to the callback |
Returns
None (void)
The method code for this function is
k_EStoveGameSupportMethodCode_FetchAchievements.
Callback
typedef void(__cdecl* OnGetAchievementsCallback)(const IStoveCallbackResult* callbackResult, const IStoveAchievementList* list);
| Name | Type | Description |
|---|---|---|
callbackResult | const IStoveCallbackResult* | Call Results |
list | const 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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unknown exception occurred during processing | O | A temporary problem has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | An internal exception occurred during processing (e.g., failure to retrieve an entity) | O | A 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 returnsNotInitialized(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
| Object | Owner | Release |
|---|---|---|
param | Caller | Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param) Required (Can be released immediately after the Stove_FetchAchievements() call returns) |
Callback callbackResult | SDK | Do Not Unlock. This will be invalidated once the callback is complete. |
The list in Callback (and each achievement item within it) | SDK | Do Not Unlock. This will be invalidated once the callback is complete. |
Example
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
AchievementIdorPageSize. 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
void Stove_FetchInventory(const IStoveTypeBase* param, OnFetchInventoryCallback onFinished, void* userData);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
param | const IStoveTypeBase* | N | This is a reserved parameter. Since it is not currently used, always pass nullptr. |
onFinished | OnFetchInventoryCallback | Y | This is the callback that receives the list of inventory items. |
userData | void* | N | This is the user data that is passed directly to the callback. |
Returns
None
The method code for this function is
k_EStoveIAPMethodCode_FetchInventory.
Callback
typedef void(__cdecl* OnFetchInventoryCallback)(const IStoveCallbackResult* callbackResult, const IStoveInventoryList* list);
| Name | Type | Description |
|---|---|---|
callbackResult | const IStoveCallbackResult* | Here are the results of the call. |
list | const 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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 17 | k_EStoveCommonResultCode_NotInitialized | The payment feature is not initialized. | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unhandled exception occurred during execution. | O | A temporary issue has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | A managed exception occurred during execution (including missing internal entities such as the login token). | O | A 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
| Object | Owner | Release |
|---|---|---|
param | Caller | Since this is a reservation parameter that is no longer in use, there is nothing to deactivate. |
Callback callbackResult | SDK | Do not unlock. This will be invalidated once the callback is complete. |
The list in the callback (and each IStoveInventoryItem within it) | SDK | Do not unwrap. This will be invalidated once the callback completes, so you must copy any necessary values within the callback. |
Example
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
onFinishedcallback. - Since
paramis a reserved parameter that is no longer in use, always passnullptr.
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
void Stove_FetchOwnerships(const IStoveTypeBase* param, OnOwnershipListCallback onFinished, void* userData);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
param | const IStoveTypeBase* | N | This is a reserved parameter. Since this call has no dedicated parameter type, pass nullptr. |
onFinished | OnOwnershipListCallback | Y | This is the callback that will receive the query results. |
userData | void* | N | This is the user data that is passed directly to the callback. |
Returns
None
The method code for this function is
k_EStoveOwnershipMethodCode_FetchOwnerships.
Callback
typedef void(__cdecl* OnOwnershipListCallback)(const IStoveCallbackResult* callbackResult, const IStoveOwnershipList* ownerships);
| Name | Type | Description |
|---|---|---|
callbackResult | const IStoveCallbackResult* | Here are the results of the query. |
ownerships | const 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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 5 | k_EStoveCommonResultCode_InvalidParam | onFinished is nullptr. | x | |
| 17 | k_EStoveCommonResultCode_NotInitialized | The SDK has not been initialized (internal check within the operation) | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unknown exception has occurred. | O | A temporary issue has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | A handled exception has occurred | O | A 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
| Object | Owner | Release |
|---|---|---|
param | Caller | Since this is a reservation parameter that is currently not in use, pass nullptr; there is no need to disable it separately. |
Callback callbackResult | SDK | Do not unlock. This will be invalidated once the callback is complete. |
Each item returned by the callbacks ownerships and GetAt() | SDK | Do not unwrap. All values will be discarded once the callback ends. Copy any values you need to preserve within the callback. |
Example
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
paramis a reserved slot that is currently unused, you can passnullptrinstead. ownershipsis not an out-parameter in the form of an array plus a count, but rather an SDK-specific list wrapper type that includesGetCount()/GetAt().
See Also
- IStoveOwnership
- IStoveOwnershipList
- EStoveOwnershipCode
- EStoveOwnershipGameCode
- EStoveOwnershipMethodCode
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
void Stove_FetchProducts(const IStoveFetchProductsParam* params, OnFetchProductsCallback onFinished, void* userData);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
params | const IStoveFetchProductsParam* | Y | These are category filter and page condition parameters. |
onFinished | OnFetchProductsCallback | Y | This is the callback that will receive the product list. |
userData | void* | N | This is the user data that is passed directly to the callback. |
Returns
None
The method code for this function is
k_EStoveIAPMethodCode_FetchProducts.
Callback
typedef void(__cdecl* OnFetchProductsCallback)(const IStoveCallbackResult* callbackResult, const IStoveProductList* list);
| Name | Type | Description |
|---|---|---|
callbackResult | const IStoveCallbackResult* | Here are the results of the call. |
list | const 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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 17 | k_EStoveCommonResultCode_NotInitialized | The payment feature is not initialized. | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unhandled exception occurred during execution. | O | A temporary issue has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | A managed exception occurred during execution (including missing internal entities such as the login token). | O | A 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
| Object | Owner | Release |
|---|---|---|
params | Caller | Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)params) Required. Release after the call returns. |
Callback callbackResult | SDK | Do not unlock. This will be invalidated once the callback is complete. |
The list of the callback (and each IStoveProduct within it) | SDK | Do not unwrap. This will be invalidated once the callback ends, so you must copy any necessary values within the callback. |
Example
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
Exvariant in the old interface). - This function is asynchronous, and the result is returned only via the
onFinishedcallback. paramsis generated fromStove_CreateParam(k_EStoveIAPTypeKind_FetchProductsParam).- The
ProductIdvalue 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
void Stove_FetchRanking(const IStoveFetchRankingParam* rankParams, OnGetRankingCallback onFinished, void* userData);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
rankParams | const IStoveFetchRankingParam* | Y | A parameter containing the leaderboard ID to retrieve and the pagination conditions. It is generated as Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchRankingParam). |
onFinished | OnGetRankingCallback | Y | Callback to receive query results |
userData | void* | N | User data passed directly to the callback |
Returns
None (void)
The method code for this function is
k_EStoveGameSupportMethodCode_FetchRanking.
Callback
typedef void(__cdecl* OnGetRankingCallback)(const IStoveCallbackResult* callbackResult, const IStoveRanking* ranking);
| Name | Type | Description |
|---|---|---|
callbackResult | const IStoveCallbackResult* | Call Results |
ranking | const 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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 5 | k_EStoveCommonResultCode_InvalidParam | The leaderboard ID (LeaderboardId) for rankParams is an empty string | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unknown exception occurred during processing | O | A temporary issue has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | An internal exception occurred during processing (e.g., failed to retrieve an entity) | O | A 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 returnsNotInitialized(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
| Object | Owner | Release |
|---|---|---|
rankParams | Caller | Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)rankParams) Required (Can be released immediately after the Stove_FetchRanking() call returns) |
Callback callbackResult | SDK | Do not unlock. This will be invalidated once the callback is complete. |
The ranking of the callback (and each ranking item within it) | SDK | Do not unlock. This will be invalidated once the callback is complete. |
Example
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). PageIndexstarts at 1.PageSizemust be set to a value between 1 and 50, inclusive.- If you set
IncludeMyRanktotrue, 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
void Stove_FetchShopCategories(const IStoveTypeBase* param, OnFetchShopCategoriesCallback onFinished, void* userData);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
param | const IStoveTypeBase* | N | This is a reserved parameter. Since it is not currently in use, always pass nullptr. |
onFinished | OnFetchShopCategoriesCallback | Y | This is the callback that will receive the category list. |
userData | void* | N | This is the user data that is passed directly to the callback. |
Returns
None
The method code for this function is
k_EStoveIAPMethodCode_FetchShopCategories.
Callback
typedef void(__cdecl* OnFetchShopCategoriesCallback)(const IStoveCallbackResult* callbackResult, const IStoveShopCategoryList* list);
| Name | Type | Description |
|---|---|---|
callbackResult | const IStoveCallbackResult* | Here are the results of the call. |
list | const 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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 17 | k_EStoveCommonResultCode_NotInitialized | The payment feature is not initialized. | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unhandled exception occurred during execution. | O | There was a temporary issue. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | A managed exception occurred during execution (including missing internal entities such as login tokens). | O | A 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
| Object | Owner | Release |
|---|---|---|
param | Caller | Since this is a reservation parameter that is no longer in use, there is nothing to deactivate. |
Callback callbackResult | SDK | Do Not Unlock. This will be invalidated once the callback is complete. |
The list in the callback (and each IStoveShopCategory within it) | SDK | Do not unwrap. The callback will be invalidated once it completes, so you must copy any necessary values within the callback. |
Example
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
onFinishedcallback. - Since
paramis a reserved parameter that is no longer in use, always passnullptr. - The
CategoryIdfor 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
void Stove_FetchStat(const IStoveFetchStatParam* param, OnGetStatCallback onFinished, void* userData);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
param | const IStoveFetchStatParam* | Y | A parameter containing the ID of the statistic to retrieve. It is generated as Stove_CreateParam(k_EStoveGameSupportTypeKind_FetchStatParam). |
onFinished | OnGetStatCallback | Y | Callback to receive query results |
userData | void* | N | User data passed directly to the callback |
Returns
None (void)
The method code for this function is
k_EStoveGameSupportMethodCode_FetchStat.
Callback
typedef void(__cdecl* OnGetStatCallback)(const IStoveCallbackResult* callbackResult, const IStoveStat* stat);
| Name | Type | Description |
|---|---|---|
callbackResult | const IStoveCallbackResult* | Call Results |
stat | const 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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 5 | k_EStoveCommonResultCode_InvalidParam | The statistics ID (StatsId) for param is an empty string | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unknown exception occurred during processing | O | A temporary issue has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | An internal exception occurred during processing (e.g., failure to retrieve an entity) | O | A 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 returnsNotInitialized(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
| Object | Owner | Release |
|---|---|---|
param | Caller | Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param) Required (Can be released immediately after Stove_FetchStat() returns) |
Callback callbackResult | SDK | Do not unlock. This will be invalidated once the callback is complete. |
Callback stat | SDK | Do not unlock. It will be invalidated once the callback is complete. |
Example
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
paramis[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 usingUrl, which is passed toonFinished.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,
onDestroyis called once along withPopupNotCreated(33). For more details, see the "Error Codes and Callbacks" section.
Declaration
void Stove_FetchTermsAgreement(const IStoveFetchTermsAgreementParam* param,
OnFetchTermsAgreementCallback onFinished, OnIAPPopupDestroyCallback onDestroy,
void* userData1, void* userData2);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
param | const IStoveFetchTermsAgreementParam* | Y | These are the parameters for the Terms and Conditions lookup operation and WebView layout. |
onFinished | OnFetchTermsAgreementCallback | Y | This is a callback to receive the consent status and the URL for the terms and conditions. |
onDestroy | OnIAPPopupDestroyCallback | N | This is a callback that is called when all pop-ups created by the SDK have been closed. |
userData1 | void* | N | This is user data that is passed directly to onFinished. |
userData2 | void* | N | This is user data that is passed directly to onDestroy. |
Returns
None
The method code for this function is
k_EStoveIAPMethodCode_FetchTermsAgreement.
Callback
typedef void(__cdecl* OnFetchTermsAgreementCallback)(const IStoveCallbackResult* callbackResult, const IStoveTermsAgreementOutcome* outcome);
typedef void(__cdecl* OnIAPPopupDestroyCallback)(const IStoveCallbackResult* callbackResult, const IStoveTypeBase* reserved);
| Name | Type | Description |
|---|---|---|
callbackResult | const IStoveCallbackResult* | Here are the results of the call. |
outcome | const 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(). |
reserved | const IStoveTypeBase* | This is a reserved parameter. It is currently always nullptr. |
Both callbacks run on the thread that called Stove_RunCallback().
onFinishedis passed only once per call.onDestroyis returned once after all pop-ups created by this call have been closed (ifOperation == WithWebView). Even if no pop-ups are created and the call terminates, it is called once with the result codePopupNotCreated(33).
Error Codes
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success (including cases where consent has already been given) | x | |
| 17 | k_EStoveCommonResultCode_NotInitialized | The payment feature is not initialized. | x | |
| 60 | k_EStoveCommonResultCode_ViewUiNotInitialized | Since 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 | |
| 65 | k_EStoveCommonResultCode_WebviewCloseAllFail | Before opening the Terms and Conditions web view, the system failed to close all previously open IAP web views. | x | |
| 62 | k_EStoveCommonResultCode_WebviewCreateFail | The attempt to create the Terms and Conditions web view failed. | x | |
| 64 | k_EStoveCommonResultCode_WebviewCreateCookieFail | Failed to set the language (locale) cookie. | O | You 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] |
| 63 | k_EStoveCommonResultCode_WebviewLoadUrlFail | Failed to load the Terms and Conditions page URL in the Terms and Conditions web view. | x | |
| 66 | k_EStoveCommonResultCode_WebviewCloseFail | An internal closure operation failed during the normal closing process of the WebView. This error is logged as onDestroy, not onFinished. | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unhandled exception occurred during execution. | O | A temporary issue has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | A managed exception occurred during execution (including missing internal entities such as login tokens). | O | A temporary issue has occurred. Please try again. [OK] |
| 33 | k_EStoveCommonResultCode_PopupNotCreated | The 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
| Object | Owner | Release |
|---|---|---|
param | Caller | Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param) Required. Release after the call returns. |
Callback callbackResult | SDK | Do not unlock. This will be invalidated once the callback is complete. |
Callback outcome | SDK | Do not unwrap. This will be invalidated once the callback ends, so you must copy any necessary values (e.g., Url) within the callback. |
Example
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
onFinishedcallback. - Using
Operation == WithWebVieweliminates 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 whenOperation != Defaultis 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
IStoveResult* Stove_GetAccessToken(wchar_t* outAccessToken, uint32_t length);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
outAccessToken | wchar_t* | Y | This is the buffer that will receive the AccessToken string. |
length | uint32_t | Y | outAccessToken is the length of the buffer. |
Returns
| Type | Description |
|---|---|
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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 5 | k_EStoveCommonResultCode_InvalidParam | outAccessToken is nullptr, length is 0, or the buffer is too small, so the value was truncated. | x | |
| 16 | k_EStoveCommonResultCode_BaseNotInitialized | It was called before being initialized. | x | |
| 19 | k_EStoveCommonResultCode_InvalidAccessToken | The AccessToken is invalid. | O | Your login session has expired. Please close the game and restart it. [OK] |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unknown exception occurred during execution. | O | A temporary issue has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | An exception occurred during execution. | O | A temporary issue has occurred. Please try again. [OK] |
If you receive the code below, you must exit the game. The game cannot proceed normally.
19k_EStoveCommonResultCode_InvalidAccessToken, Your login session has expired and needs to be refreshed
Complete list: EStoveCommonResultCode
Memory Management
| Object | Owner | Release |
|---|---|---|
outAccessToken | Caller | This is a buffer allocated by the caller. It is not a target for destruction. |
Returned IStoveResult* | Caller | Stove_IStoveTypeBase_Destroy() Required |
Example
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
IStoveResult* Stove_GetCloudSavingPath(wchar_t* outPath, uint32_t length);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
outPath | wchar_t* | Y | This is a buffer to receive the cloud storage path string. It is preallocated by the caller. |
length | uint32_t | Y | outPath is the length (in characters) of the buffer. |
Returns
| Type | Description |
|---|---|
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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 5 | k_EStoveCommonResultCode_InvalidParam | outPath is nullptr, length is 0, or the path string is truncated (STRUNCATE) because the buffer is too small. | x | |
| 16 | k_EStoveCommonResultCode_BaseNotInitialized | The SDK did not initialize | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unknown exception occurred during execution. | O | A temporary issue has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | An internal exception occurred during execution | O | A temporary issue has occurred. Please try again. [OK] |
Complete list: EStoveCommonResultCode, EStoveResultCode
Memory Management
| Object | Owner | Release |
|---|---|---|
outPath | Caller | This is a buffer allocated by the caller. It is not a Destroy target. |
Returned IStoveResult* | Caller | Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result) Required |
Example
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.
outPathIf the buffer is smaller than the resulting string, the string is truncated andInvalidParam(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
IStoveResult* Stove_GetGds(IStoveGds** outGds);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
outGds | IStoveGds** | Y | This is the variable that will receive the GDS information pointer. After use, you must call Destroy(). |
Returns
| Type | Description |
|---|---|
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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 5 | k_EStoveCommonResultCode_InvalidParam | outGds is nullptr. | x | |
| 16 | k_EStoveCommonResultCode_BaseNotInitialized | It was called before being initialized. | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unknown exception occurred during execution. | O | A temporary issue has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | An exception occurred during execution. | O | There was a temporary issue. Please try again. [OK] |
Complete list: EStoveCommonResultCode
Memory Management
| Object | Owner | Release |
|---|---|---|
*outGds | The SDK is created, and ownership is transferred to the caller | Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)gds) Required |
Returned IStoveResult* | Caller | Stove_IStoveTypeBase_Destroy() Required |
Example
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()returnstrue.
See Also
Stove_GetSignin
Kind Function · Module Base · Version 3.5.0
Description
Retrieves the sign-in information for the logged-in user.
Declaration
IStoveResult* Stove_GetSignin(IStoveSignin** outSignin);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
outSignin | IStoveSignin** | Y | This is the variable that will receive the registration information pointer. After use, you must call Destroy(). |
Returns
| Type | Description |
|---|---|
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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 5 | k_EStoveCommonResultCode_InvalidParam | outSignin is nullptr. | x | |
| 16 | k_EStoveCommonResultCode_BaseNotInitialized | It was called before it was initialized. | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unknown exception occurred during execution. | O | A temporary issue has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | An exception occurred during execution. | O | There was a temporary issue. Please try again. [OK] |
Complete list: EStoveCommonResultCode
Memory Management
| Object | Owner | Release |
|---|---|---|
*outSignin | The SDK is created, and ownership is transferred to the caller | Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)signin) Required |
Returned IStoveResult* | Caller | Stove_IStoveTypeBase_Destroy() Required |
Example
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, useStove_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
IStoveResult* Stove_GetUser(IStoveUser** outUser);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
outUser | IStoveUser** | Y | This is the variable that will receive the user information pointer. After use, you must call Destroy(). |
Returns
| Type | Description |
|---|---|
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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 5 | k_EStoveCommonResultCode_InvalidParam | outUser is nullptr. | x | |
| 16 | k_EStoveCommonResultCode_BaseNotInitialized | It was called before being initialized. | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unknown exception occurred during execution. | O | A temporary issue has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | An exception occurred during execution. | O | There was a temporary issue. Please try again. [OK] |
Complete List: EStoveCommonResultCode
Memory Management
| Object | Owner | Release |
|---|---|---|
*outUser | The SDK is created, and ownership is transferred to the caller | Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)user) Required |
Returned IStoveResult* | Caller | Stove_IStoveTypeBase_Destroy() Required |
Example
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
IStoveResult* Stove_GetVersion(wchar_t* outVersion, uint32_t length);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
outVersion | wchar_t* | Y | This is the buffer that will receive the version string. It is preallocated by the caller. |
length | uint32_t | Y | outVersion is the length (in characters) of the buffer. |
Returns
| Type | Description |
|---|---|
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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 5 | k_EStoveCommonResultCode_InvalidParam | outVersion is nullptr, length is 0, or the buffer is too small, causing the version string to be truncated (STRUNCATE) | x | |
| 251 | k_EStoveCommonResultCode_PcsdkDllNotFound | The DLL path was not found in the executable file path | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unknown exception occurred during execution. | O | A temporary problem has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | An internal exception occurred during execution | O | A temporary issue has occurred. Please try again. [OK] |
Complete list: EStoveCommonResultCode, EStoveResultCode
Memory Management
| Object | Owner | Release |
|---|---|---|
outVersion | Caller | This buffer was allocated by the caller. It is not a target for destruction. |
Returned IStoveResult* | Caller | Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result) Required |
Example
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 retryStove_Initialize()from a clean state. If you call it again withoutUninitialize,ALREADY_INITIALIZEDwill be returned, and the initialization of the module that failed will not be retried.
Declaration
IStoveResult* Stove_Initialize(const IStoveInitializeParam* initParam);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
initParam | IStoveInitializeParam* | N | This is initialization information. If you pass nullptr, only the SDK will be initialized. |
Returns
| Type | Description |
|---|---|
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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 5 | k_EStoveCommonResultCode_InvalidParam | At least one of the following is empty: environment, game ID, or app key (check the value passed when calling Stove_RestartAppIfNecessary()). | x | |
| 18 | k_EStoveCommonResultCode_AlreadyInitialized | It is already initialized. | x | |
| 304 | k_EStoveResultCode_NeedStoveLauncher | You must first call Stove_RestartAppIfNecessary() to complete the launcher connection. | O | The 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] |
| 251 | k_EStoveCommonResultCode_PcsdkDllNotFound | The result of the failed internal version lookup (GetVersion) was returned as-is. | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unknown exception occurred during execution. | O | A temporary problem has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | An exception occurred during execution (including lower-level errors such as failure to parse required information). | O | There was a temporary issue. Please try again. [OK] |
If you receive the code below, you must exit the game. The game cannot proceed normally.
304k_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
| Object | Owner | Release |
|---|---|---|
initParam | Caller | If delivered, Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)initParam) Required |
Returned IStoveResult* | Caller | Stove_IStoveTypeBase_Destroy() Required |
Example
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
void Stove_OpenExternalUrl(const wchar_t* url, OnOpenExternalUrlCallback onFinished, void* userData);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
url | const wchar_t* | Y | This is the URL you want to open. |
onFinished | OnOpenExternalUrlCallback | Y | This is the callback that will receive the results. |
userData | void* | N | This is the user data that is passed directly to the callback. |
Returns
None
The method code for this function is
k_EStoveBaseMethodCode_OpenExternalUrl.
Callback
typedef void(__cdecl* OnOpenExternalUrlCallback)(const IStoveCallbackResult* callbackResult, const IStoveTypeBase* reserved);
| Name | Type | Description |
|---|---|---|
callbackResult | const IStoveCallbackResult* | Here are the results of the call. |
reserved | const 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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success (URL opened successfully in the browser) | x | |
| 5 | k_EStoveCommonResultCode_InvalidParam | onFinished is nullptr | x | |
| 16 | k_EStoveCommonResultCode_BaseNotInitialized | The SDK did not initialize | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | The browser failed to launch, or an unknown exception occurred while it was running. | O | A temporary issue has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | An internal exception occurred during execution | O | A 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
| Object | Owner | Release |
|---|---|---|
url | Caller | This is a string argument. It is not a target for destruction. |
Callback callbackResult, reserved | SDK | Do not unlock. This will be invalidated once the callback is complete. |
Example
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
reservedargument of the callback is currently always nullptr. You can checkif (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
void Stove_OverImmersionNotification(const IStoveTypeBase* param, OnOverImmersionNotificationCallback onFinished, void* userData);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
param | const IStoveTypeBase* | N | As a reserved argument, a dedicated TypeKind has not been defined. |
onFinished | OnOverImmersionNotificationCallback | Y | This is the callback that will receive the results. |
userData | void* | N | This is the user data that is passed directly to the callback. |
Returns
None
The method code for this function is
k_EStoveBaseMethodCode_OverImmersionNotification.
Callback
typedef void(__cdecl* OnOverImmersionNotificationCallback)(const IStoveCallbackResult* callbackResult, const IStoveOverImmersionInfo* overImmersion);
| Name | Type | Description |
|---|---|---|
callbackResult | const IStoveCallbackResult* | Here are the results of the call. |
overImmersion | const 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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 5 | k_EStoveCommonResultCode_InvalidParam | onFinished is nullptr | x | |
| 16 | k_EStoveCommonResultCode_BaseNotInitialized | The SDK did not initialize | x | |
| 31 | k_EStoveCommonResultCode_NotSupportedCountry | The GDS country code for the login account is not South Korea (kr) | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unknown exception occurred during execution. | O | There was a temporary issue. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | An internal exception occurred during execution | O | A temporary issue has occurred. Please try again. [OK] |
Complete list: EStoveCommonResultCode, EStoveResultCode
Memory Management
| Object | Owner | Release |
|---|---|---|
param | Caller | If delivered, Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param) Required |
Callback callbackResult, overImmersion | SDK | Do not unlock. This will be invalidated once the callback is complete. |
Example
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
void Stove_RestartAppIfNecessary(const IStoveRestartAppIfNecessaryParam* initParam, OnRestartAppIfNecessaryCallback onFinished, void* userData);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
initParam | IStoveRestartAppIfNecessaryParam* | Y | This information, such as Environment, Game ID, and App Key, is required to verify the launcher. |
onFinished | OnRestartAppIfNecessaryCallback | Y | This is the callback that will receive the results. |
userData | void* | N | This is the user data that is passed directly to the callback. |
Returns
None
The method code for this function is
k_EStoveBaseMethodCode_RestartAppIfNecessaryAsync.
Callback
typedef void(__cdecl* OnRestartAppIfNecessaryCallback)(const IStoveCallbackResult* callbackResult, const IStoveRestartAppIfNecessaryOutcome* outcome);
| Name | Type | Description |
|---|---|---|
callbackResult | const IStoveCallbackResult* | Here are the results of the call. |
outcome | const 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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success (IPC status reaches "Normal," or the previous call is confirmed to have already completed) | x | |
| 29 | k_EStoveCommonResultCode_AsyncOperationInProgress | The previous asynchronous restart request is still being processed. | x | |
| 30 | k_EStoveCommonResultCode_BaseUninitialized | The IPC state changed to an uninitialized state while waiting. | x | |
| 307 | k_EStoveResultCode_IpcConnectFailed | The IPC connection to the launcher failed. | O | The 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] |
| 308 | k_EStoveResultCode_IpcAesKeyNotReceived | The AES key was not received from the launcher. | O | The 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] |
| 309 | k_EStoveResultCode_IpcTimeout | The timeout (waitTimeMillisec) has been exceeded. | O | The 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] |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unknown exception occurred during execution. | O | A temporary problem has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | An exception occurred during execution. | O | A temporary issue has occurred. Please try again. [OK] |
If you receive the code below, you must exit the game. The game cannot proceed normally.
307k_EStoveResultCode_IpcConnectFailed, Connection to the launcher failed; please try again.308k_EStoveResultCode_IpcAesKeyNotReceived, Failed to establish communication with the launcher; a retry is required309k_EStoveResultCode_IpcTimeout, Communication with the launcher timed out; a retry is required
Complete list: EStoveCommonResultCode, EStoveResultCode
Memory Management
| Object | Owner | Release |
|---|---|---|
initParam | Caller | Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)initParam) Required |
Callback callbackResult, outcome | SDK | Do not unlock. This will be invalidated once the callback is complete. |
Example
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
void Stove_RunCallback();
Parameters
None
Returns
None
Error Codes
None
Memory Management
This function does not create or return a separate object.
Example
// 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
void Stove_RunCallbackWithTimeout(uint32_t timeoutMillisec);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
timeoutMillisec | uint32_t | Y | This is the wait time (in milliseconds). |
Returns
None
Error Codes
None
Memory Management
This function does not create or return a separate object.
Example
// 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.
onFinishedThe 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
void Stove_SendLog(const IStoveSendLogParam* logSendParam, OnSendLogCallback onFinished, void* userData);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
logSendParam | const IStoveSendLogParam* | Y | This is the value of the log entry to be transmitted. It is generated as Stove_CreateParam(k_EStoveLogTypeKind_SendLogParam). |
onFinished | OnSendLogCallback | Y | This is the callback that receives the transmission results. |
userData | void* | N | This is the user data that is passed directly to the callback. |
Returns
None
The method code for this function is
k_EStoveLogMethodCode_SendLog.
Callback
typedef void(__cdecl* OnSendLogCallback)(const IStoveCallbackResult* callbackResult, const IStoveTypeBase* reserved);
| Name | Type | Description |
|---|---|---|
callbackResult | const 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. |
reserved | const 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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | The 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 | |
| 5 | k_EStoveCommonResultCode_InvalidParam | onFinished is nullptr, or contents is not empty, but this is not valid JSON. | x | |
| 17 | k_EStoveCommonResultCode_NotInitialized | The SDK has not been initialized. | x | |
| 44 | k_EStoveCommonResultCode_LocalDbWriteFailed | Failed to write a log record to the local database (formerly known as LOCAL_DB_BACKUP_LOG_FAILED) | x | |
| 82 | k_EStoveCommonResultCode_PayloadSizeExceeded | The log content encoded in UTF-8 exceeded 50 KB (formerly known as LOG_SIZE_EXCEEDED) | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unknown exception has occurred. | O | A temporary issue has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | A handled exception has occurred | O | A 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
| Object | Owner | Release |
|---|---|---|
logSendParam | Caller | Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)logSendParam) Required. You can release it immediately after the call returns. |
Callback callbackResult | SDK | Do not unlock. This will be invalidated once the callback is complete. |
Callback reserved | SDK | The 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
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
onFinishedThe 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
reservedargument of a callback is always a reserved parameter,nullptr. We recommend handling it defensively in the form ofif (reserved)in anticipation of when the value will be populated. - Except for local DB storage failures (such as
k_EStoveCommonResultCode_LocalDbWriteFailedin 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
IStoveResult* Stove_SetGameProfile(const IStoveSetGameProfileParam* gameProfileParams);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
gameProfileParams | const IStoveSetGameProfileParam* | Y | This is the game profile information. It is generated as Stove_CreateParam(k_EStoveBaseTypeKind_SetGameProfileParam). |
Returns
| Type | Description |
|---|---|
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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 5 | k_EStoveCommonResultCode_InvalidParam | gameProfileParams is nullptr | x | |
| 16 | k_EStoveCommonResultCode_BaseNotInitialized | The SDK did not initialize | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unknown exception occurred during execution. | O | A temporary issue has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | An internal exception occurred during execution | O | A temporary issue has occurred. Please try again. [OK] |
Complete list: EStoveCommonResultCode, EStoveResultCode
Memory Management
| Object | Owner | Release |
|---|---|---|
gameProfileParams | Caller | Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)gameProfileParams) Required |
Returned IStoveResult* | Caller | Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result) Required |
Example
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" inStoveGameProfileParamswas 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
IStoveResult* Stove_SetLanguage(const wchar_t* language);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
language | const wchar_t* | Y | This is a language information string. |
Returns
| Type | Description |
|---|---|
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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 5 | k_EStoveCommonResultCode_InvalidParam | language is nullptr or an unsupported language code | x | |
| 16 | k_EStoveCommonResultCode_BaseNotInitialized | The SDK did not initialize | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unknown exception occurred during execution. | O | A temporary issue has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | An internal exception occurred during execution | O | A 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
| Object | Owner | Release |
|---|---|---|
language | Caller | This is a string argument. It is not a target for Destroy. |
Returned IStoveResult* | Caller | Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)result) Required |
Example
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
void Stove_SetStat(const IStoveSetStatParam* param, OnSetStatCallback onFinished, void* userData);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
param | const IStoveSetStatParam* | Y | A parameter containing the ID of the statistic to be modified and the new value. It is created as Stove_CreateParam(k_EStoveGameSupportTypeKind_SetStatParam). |
onFinished | OnSetStatCallback | Y | Callback to receive the update results |
userData | void* | N | User data passed directly to the callback |
Returns
None (void)
The method code for this function is
k_EStoveGameSupportMethodCode_SetStat.
Callback
typedef void(__cdecl* OnSetStatCallback)(const IStoveCallbackResult* callbackResult, const IStoveSetStatOutcome* statOutcome);
| Name | Type | Description |
|---|---|---|
callbackResult | const IStoveCallbackResult* | Call Results |
statOutcome | const 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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 5 | k_EStoveCommonResultCode_InvalidParam | The statistics ID (StatsId) for param is an empty string | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unknown exception occurred during processing | O | A temporary issue has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | An internal exception occurred during processing (e.g., failure to retrieve an entity) | O | A 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 returnsNotInitialized(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
| Object | Owner | Release |
|---|---|---|
param | Caller | Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param) Required (Can be released immediately after the Stove_SetStat() call returns) |
Callback callbackResult | SDK | Do not unlock. This will be invalidated once the callback is complete. |
Callback statOutcome | SDK | Do not unlock. This will be invalidated once the callback is complete. |
Example
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). StatValuedoes 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 inStatValue, 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 asfalse. This is not an error. - The format of the statistics ID for
paramis[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
int32range, it will be truncated to2147483647. The call will still succeed, andIStoveSetStatOutcome::IsUpdated()will betrue. - You can check whether the value has been truncated by seeing if
integer overflowis stored inIStoveSetStatOutcome::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
void Stove_ShutdownNotification(const IStoveTypeBase* param, OnShutdownNotificationCallback onFinished, void* userData);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
param | const IStoveTypeBase* | N | As a reserved argument, a dedicated TypeKind has not been defined. |
onFinished | OnShutdownNotificationCallback | Y | This is the callback that will receive the results. |
userData | void* | N | This is the user data that is passed directly to the callback. |
Returns
None
The method code for this function is
k_EStoveBaseMethodCode_ShutdownNotification.
Callback
typedef void(__cdecl* OnShutdownNotificationCallback)(const IStoveCallbackResult* callbackResult, const IStoveShutdownInfo* shutdown);
| Name | Type | Description |
|---|---|---|
callbackResult | const IStoveCallbackResult* | Here are the results of the call. |
shutdown | const 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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 5 | k_EStoveCommonResultCode_InvalidParam | onFinished is nullptr | x | |
| 16 | k_EStoveCommonResultCode_BaseNotInitialized | The SDK did not initialize | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unknown exception occurred during execution. | O | A temporary issue has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | An internal exception occurred during execution | O | A 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
| Object | Owner | Release |
|---|---|---|
param | Caller | If delivered, Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param) Required |
Callback callbackResult, shutdown | SDK | Do not unlock. This will be invalidated once the callback is complete. |
Example
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 byonFinishedand 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 callStove_ConfirmPurchaseto confirm the purchase.WithWebViewAndConfirmResult: The Stove payment page opens within the Stove Webview, and upon successful payment, the SDK automatically callsStove_ConfirmPurchaseand returns the confirmed purchase result toonFinished. In this case, the caller does not need to callStove_ConfirmPurchaseseparately.
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,
onDestroyis called once along withPopupNotCreated(33). For more details, refer to the "Error Codes and Callbacks" section.
Declaration
void Stove_StartPurchase(const IStoveStartPurchaseParam* params,
OnStartPurchaseCallback onFinished, OnIAPPopupDestroyCallback onDestroy,
void* userData1, void* userData2);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
params | const IStoveStartPurchaseParam* | Y | This is a list of ordered items and purchase action parameters. |
onFinished | OnStartPurchaseCallback | Y | This is the callback that will receive the purchase results. |
onDestroy | OnIAPPopupDestroyCallback | N | This is a callback that is called when all pop-ups created by the SDK have been closed. |
userData1 | void* | N | This is user data that is passed directly to onFinished. |
userData2 | void* | N | This is user data that is passed directly to onDestroy. |
Returns
None
The method code for this function is
k_EStoveIAPMethodCode_StartPurchase.
Callback
typedef void(__cdecl* OnStartPurchaseCallback)(const IStoveCallbackResult* callbackResult, const IStoveStartPurchaseOutcome* outcome);
typedef void(__cdecl* OnIAPPopupDestroyCallback)(const IStoveCallbackResult* callbackResult, const IStoveTypeBase* reserved);
| Name | Type | Description |
|---|---|---|
callbackResult | const IStoveCallbackResult* | Here are the results of the call. |
outcome | const 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). |
reserved | const IStoveTypeBase* | This is a reserved parameter. It is currently always nullptr. |
Both callbacks run on the thread that called Stove_RunCallback().
onFinishedis passed only once per call.onDestroyis 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 codePopupNotCreated(33).
Error Codes
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 17 | k_EStoveCommonResultCode_NotInitialized | The payment feature is not initialized. | x | |
| 60 | k_EStoveCommonResultCode_ViewUiNotInitialized | Operation 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 | |
| 65 | k_EStoveCommonResultCode_WebviewCloseAllFail | Before opening the new payment webview, the system failed to close all previously open IAP webviews. | x | |
| 62 | k_EStoveCommonResultCode_WebviewCreateFail | The attempt to create the payment web view failed. | x | |
| 63 | k_EStoveCommonResultCode_WebviewLoadUrlFail | The payment page URL could not be loaded in the payment webview. | x | |
| 34 | k_EStoveCommonResultCode_WebviewClosedBeforeComplete | WithWebViewAndConfirmResult The WebView closed before a payment completion notification was received from the payment flow (e.g., user cancellation). | O | The purchase was not completed successfully. Please try again. [OK] |
| 66 | k_EStoveCommonResultCode_WebviewCloseFail | An internal closure process failed while the WebView was closing normally. This error is logged as onDestroy, not onFinished. | x | |
| 80 | k_EStoveCommonResultCode_ParameterLengthExceeded | ServiceTxnNo exceeds 50 characters, or ExtraData exceeds 500 characters. | O | The payment information is invalid, so we cannot process the payment. Please try again. [OK] |
| 81 | k_EStoveCommonResultCode_InvalidJsonString | ExtraData is not empty, but it is not in JSON format. | O | The payment information is invalid, so we cannot process the payment. Please try again. [OK] |
| 503 | k_EStoveResultCode_InvalidOrderProductInformation | There are items in your order with a quantity of 0 or less, or with a selling price (SalePrice) that is negative. | O | The payment information is invalid, so we cannot process the payment. Please try again. [OK] |
| 252 | k_EStoveCommonResultCode_NotImplemented | The value of Operation for IStovePurchaseParam is not one of the known values (Default/WithWebView/WithWebViewAndConfirmResult). | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unhandled exception occurred during execution. | O | A temporary issue has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | A managed exception occurred during execution (including missing internal entities such as login tokens). | O | A temporary issue has occurred. Please try again. [OK] |
| 33 | k_EStoveCommonResultCode_PopupNotCreated | The 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 toonFinishedin this function. Please also refer to the error codes in theStove_ConfirmPurchasedocumentation.
Complete list: EStoveCommonResultCode, EStoveResultCode
Memory Management
| Object | Owner | Release |
|---|---|---|
params | Caller | Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)params) Required. Release it after the call returns. |
Each IStoveOrderProductParam contained in params | Caller | The caller retains ownership and must Destroy() after the call returns. |
params contains IStovePurchaseParam | Caller | The caller retains ownership and must Destroy() after the call returns. |
Callback callbackResult | SDK | Do not unlock. This will be invalidated once the callback is complete. |
Callback outcome | SDK | Do not unwrap. This will be invalidated once the callback completes, so you must copy any necessary values within the callback. |
Example
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
onFinishedcallback. - Purchases starting with
Operation,Default, orWithWebViewmust be finalized by calling Stove_ConfirmPurchase. The SDK automatically handles the finalization ofWithWebViewAndConfirmResult. - You can use the
PurchaseProgress(EStovePurchaseProgress) value ofoutcometo 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 wasIStovePurchaseResult. These have now been changed tok_EStoveIAPTypeKind_StartPurchaseParamandIStoveStartPurchaseOutcome, 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_ConfirmPurchase
- Stove_FetchProducts
- EStovePurchaseOperation
- IStoveStartPurchaseParam
- IStoveStartPurchaseOutcome
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 uppercaseI. This notation differs fromBase_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
IStoveResult* Stove_Uninitialize();
Parameters
None
Returns
| Type | Description |
|---|---|
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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 16 | k_EStoveCommonResultCode_BaseNotInitialized | It was called before it had been initialized. | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unknown exception occurred during execution. | O | There was a temporary issue. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | An exception occurred during execution. | O | A temporary problem has occurred. Please try again. [OK] |
Complete List: EStoveCommonResultCode
Memory Management
| Object | Owner | Release |
|---|---|---|
Returned IStoveResult* | Caller | Stove_IStoveTypeBase_Destroy() Required |
Example
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_INITIALIZEDis 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
void Stove_VietnamAgeRatingNotification(const IStoveTypeBase* param, OnVietnamAgeRatingNotificationCallback onFinished, void* userData);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
param | const IStoveTypeBase* | N | As a reserved argument, a dedicated TypeKind has not been defined. |
onFinished | OnVietnamAgeRatingNotificationCallback | Y | This is the callback that will receive the results. |
userData | void* | N | This is user data that is passed directly to the callback. |
Returns
None
The method code for this function is
k_EStoveBaseMethodCode_VietnamAgeRatingNotification.
Callback
typedef void(__cdecl* OnVietnamAgeRatingNotificationCallback)(const IStoveCallbackResult* callbackResult, const IStoveVietnamAgeRatingInfo* ageRatingInfo);
| Name | Type | Description |
|---|---|---|
callbackResult | const IStoveCallbackResult* | Here are the results of the call. |
ageRatingInfo | const 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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 5 | k_EStoveCommonResultCode_InvalidParam | onFinished is nullptr | x | |
| 16 | k_EStoveCommonResultCode_BaseNotInitialized | The SDK did not initialize | x | |
| 31 | k_EStoveCommonResultCode_NotSupportedCountry | The GDS country code for the login account is not Vietnam (vn) | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unknown exception occurred during execution. | O | A temporary issue has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | An internal exception occurred during execution | O | A temporary issue has occurred. Please try again. [OK] |
Complete list: EStoveCommonResultCode, EStoveResultCode
Memory Management
| Object | Owner | Release |
|---|---|---|
param | Caller | If delivered, Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param) Required |
Callback callbackResult, ageRatingInfo | SDK | Do not unlock. This will be invalidated once the callback completes. |
Example
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
void Stove_VietnamOverimmersionNotification(const IStoveTypeBase* param, OnVietnamOverimmersionNotificationCallback onFinished, void* userData);
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
param | const IStoveTypeBase* | N | As a reserved argument, a dedicated TypeKind has not been defined. |
onFinished | OnVietnamOverimmersionNotificationCallback | Y | This is the callback that will receive the results. |
userData | void* | N | This is the user data that is passed directly to the callback. |
Returns
None
The method code for this function is
k_EStoveBaseMethodCode_VietnamOverimmersionNotification.
Callback
typedef void(__cdecl* OnVietnamOverimmersionNotificationCallback)(const IStoveCallbackResult* callbackResult, const IStoveVietnamOverimmersionInfo* overimmersionInfo);
| Name | Type | Description |
|---|---|---|
callbackResult | const IStoveCallbackResult* | Here are the results of the call. |
overimmersionInfo | const 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
| Code | Name | Description | Show to User | In-Game Message |
|---|---|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success | x | |
| 5 | k_EStoveCommonResultCode_InvalidParam | onFinished is nullptr | x | |
| 16 | k_EStoveCommonResultCode_BaseNotInitialized | The SDK did not initialize | x | |
| 31 | k_EStoveCommonResultCode_NotSupportedCountry | The GDS country code for the login account is not Vietnam (vn) | x | |
| 253 | k_EStoveCommonResultCode_UnmanagedException | An unknown exception occurred during execution. | O | A temporary problem has occurred. Please try again. [OK] |
| 254 | k_EStoveCommonResultCode_ManagedException | An internal exception occurred during execution | O | A temporary issue has occurred. Please try again. [OK] |
Complete list: EStoveCommonResultCode, EStoveResultCode
Memory Management
| Object | Owner | Release |
|---|---|---|
param | Caller | If delivered, Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param) Required |
Callbacks callbackResult and overimmersionInfo | SDK | Do not unlock. This will be invalidated once the callback is complete. |
Example
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.