External Platform Support Module Reference — Native

Based on SDK version 1.0.0. 35 items combined in alphabetical order.

Contents

Basic Integration Guide

Kind Integration Guide · Module APIModule · Version 1.0.0

Description

APIModule(External Platform Support Module) is a module that enables games launched via the Steam Launcher to use Stove platform features in exactly the same way as if they were launched via the Stove Launcher. This module handles Stove platform authentication using the user's Steam-authenticated credentials and is responsible for obtaining the tokens and account information required to enter the game.

The only supported platform is Steam. We do not support any other third-party platforms. This module does not include the Steamworks SDK; it operates on the assumption that the game has already integrated and initialized the Steamworks SDK.

The developer is responsible for implementing all screens displayed to users (Terms of Service agreement, access denial notices, penalty notices, maintenance notices, and error pop-ups). The module only provides the values to be displayed on the screen and the resulting code.

This module was previously referred to by a different name in earlier documentation. It is the same module, and its current name is APIModule.

Header Configuration

The distribution binary is APIModule.dll, and there are four public headers. To use the functions, include api_module.h; to access the interface members in a C environment, include api_module_flat.h as well.

Declaration Forms

Interface members are provided in two forms: C++ virtual functions and C flat accessors, and they behave the same way. Flat accessors internally call a virtual function with the same name.

• All public functions are declared as extern "C" + __cdecl. Since a violation of the calling convention in a 32-bit build can cause a stack corruption, you must also adhere to __cdecl when declaring function pointers directly.
• The header file uses the STOVE_MODULE_API macro to denote this calling convention. In MSVC, it is defined as __cdecl, while in other compilers, it is defined as an empty string. The declarations in this document replicate the header notation exactly, and in the example code, the callback functions defined by the game are written as __cdecl. These two notations have the same meaning in MSVC.
• Although the header also declares a typedef (<function-name>_t) for the function pointer of each flat function, it is not shown in this document. Please refer to it only when needed for dynamic loading (GetProcAddress).

In each function documentation page, ## Example lists the two forms side by side under the C · C++ tabs. Since calling the same API using either form yields the same result, you only need to refer to the tab that matches your project environment.

The SDK function (Stove_APIModule_*) is the same in both tabs. The only differences are in how interface members are accessed and how deallocation is indicated. The C++ mentioned here refers to calling the new interface using C++ syntax, which differs from the old C++ interface (Stove::PCSDK::<Module>) in PCSDK3.

Naming Rules

The termination function is Stove_APIModule_UnInitialize. Please note the uppercase I.

Memory Lifetime

All SDK objects have IModuleTypeBase as their root, and the ShouldDestroy() flag determines who is responsible for releasing them.

General Rule — You can determine this with the single line below without having to memorize the source.

c

if (Stove_IModuleTypeBase_ShouldDestroy(obj))   // In C++, obj->ShouldDestroy()
    Stove_IModuleTypeBase_Destroy(obj); // In C++, obj->Destroy()

The object passed as a callback argument and its child objects become invalid as soon as the callback returns. If you need to use a value outside the callback, be sure to perform a deep copy of it inside the callback. Since strings are passed only as pointers (const wchar_t*), storing the pointer can result in a dangling pointer, which may cause a crash.

Ownership of parameter objects remains with the caller even after they are passed to the API. Even for asynchronous functions, you can release them immediately after the function returns. The SDK copies the necessary values at the time of the call.

Initialization Order

1. Obtain a Steam session token from Steamworks (ISteamUser::GetAuthTicketForWebApi; the result is returned via the GetTicketForWebApiResponse_t callback). Since this is a value obtained once per process and reused throughout the game session, save the value you receive and use it as-is for subsequent calls.
2. Use Stove_APIModule_CreateParam(k_EStoveAPIModuleTypeKind_APIInitializeParam) to create IModuleAPIInitializeParam, and configure the runtime environment, platform name (fixed as L"STEAM"), Steam App ID, and Steam User ID.
3. Call Stove_APIModule_Initialize(param, onFinished, userData). Since it is asynchronous, the result is returned via a callback. Release the parameter object after the call.
4. In the game's main loop, start calling Stove_APIModule_RunCallback() every frame. If you don't call this function, the three callbacks won't be triggered, and the integration won't proceed.
5. After receiving the initialization success callback, it calls Stove_APIModule_GameCheckerForSteam. This is a single entry point that handles both login (authentication) and checking whether the game has been launched.
6. The callback branches based on the result.
   1. Success — You are now ready to enter the game. Next, launch PCSDK3.
   2. 406401 (Terms of Service agreement required) — View the Terms of Service at Stove_APIModule_FetchGameTermsForSteam(), obtain consent on the developer's screen, submit via Stove_APIModule_AgreeToGameTermsForSteam(), and then call step 5 again.
   3. Other issues — The game closes after displaying the developer's information screen.
7. It maintains the Stove_APIModule_RunCallback() loop while the game is running.
8. Call Stove_APIModule_UnInitialize() when the game ends. This is a synchronous function, and the caller must free the returned IModuleAPIResult*.

The only case where the game entry check is called again is 406401. Once the terms of service agreement is reflected on the server, 406401 will no longer appear in subsequent calls.

Relationship with PCSDK3

If the game entry check is successful, APIModule directly passes the logged-in status to PCSDK3. There is no process where the developer retrieves the token and passes it to PCSDK3.

All the developer needs to do is launch PCSDK3 as usual after successfully passing the game entry check. From this point on, the behavior is the same as when the game is launched via the Stove Launcher.

Callback Execution Rules

• All callbacks for asynchronous APIs use the __cdecl calling convention. In the header file, this convention is defined as the STOVE_MODULE_API macro in the callback typedef.
• The callback runs on the thread that called Stove_APIModule_RunCallback(), not on an internal SDK thread. This function must be called from the game UI (main) thread. That way, you can interact directly with the game UI within the callback, and no additional synchronization is required.
• If you don't call Stove_APIModule_RunCallback(), the callback will never be triggered. Make sure to run the loop before calling the asynchronous function.
• The values IModuleAPICallbackResult* and IModuleXxxOutcome* received as callback arguments are valid only while the callback is executing. Do not call Destroy().
• The callback does not directly receive void* userData. The value passed when the callback is invoked is retrieved via Stove_IModuleAPICallbackResult_GetUserData(callbackResult).
• userData is a void* that is not managed by the SDK. If it points to a stack variable or a temporary object, it may become a dangling pointer at the time of the callback, which could cause a crash. If you are not using it, pass NULL instead.
• If you pass NULL to onFinished, the request will be sent, but there is no way to receive the result. Always specify a callback.

Common Interface

This is a type shared by all APIs.

The code returned by the server for each API (e.g., 406401 for the game entry check) is passed as GetExternalError(), not GetResultCode(). GetResultCode() contains the value EStoveModuleCommonResultCode (success 0, server response failure 1, HTTP failure 21, etc.). You need to look at both values together to accurately determine the cause of the failure.

Notes

• You do not have to author every string on your notice screens. When the game entry check fails with a restriction (403201) or maintenance (503100), the outcome object carries the notice text; for terms agreement required (406401), call the terms lookup once more to receive the title and body. Display the values you receive as-is. Other failure codes carry no extra data, so you decide the text for those.
• The supported platform is Steam. The platform name in the initialization parameters is a fixed value: L"STEAM".
• Integrating the Steamworks SDK and issuing Steam session tokens are the developer's responsibility. This module does not include the Steamworks SDK.
• Steam session tokens are issued once per process and reused throughout the game session. The same value is used for game entry verification, terms of service agreement, and re-invocation.
• The login process does not vary depending on the account type (AccountType). There is no need to distinguish between account types during the game entry verification process.
• The language setting (Stove_APIModule_SetLanguage) accepts BCP 47-format strings. Examples: L"ko", L"en", L"ja".
• The child objects of the result object (GetRestrictInfo() · GetMaintenanceInfo()) are passed as empty objects when that is not the case. It is safer to include a null check before reading the values.

See Also

EStoveAgreeToGameTermsForSteamResultCode

Kind Result Code · Module APIModule · Version 1.0.0

Description

Stove_APIModule_AgreeToGameTermsForSteam is a specific result code. The value is taken directly from the response code returned by the Stove backend; 0 indicates success.

This value is extracted from the callback argument as Stove_IModuleAPICallbackResult_GetExternalError(). Stove_IModuleAPIResult_GetResultCode() does not contain this value, but rather the value specified in EStoveModuleCommonResultCode (success 0, server response failure 1, HTTP failure 21, etc.). You must examine both values together to accurately determine the cause of the failure.

The values are grouped into HTTP status code families. 4xxxxx indicates a request, authorization, or data issue, while 5xxxxx indicates a server issue. Only 49500 is an exception to this rule; it is a code used exclusively for blocking access.

The consent submission must succeed before you can call the game entry check again. If it fails, an informational screen will appear and the game will close. If you call the game entry check again without having obtained consent, it will fail again with error code 406401.

Declaration

typedef enum EStoveAgreeToGameTermsForSteamResultCode
{
    k_EStoveAgreeToGameTermsForSteamResultCode_Success = 0,

    k_EStoveAgreeToGameTermsForSteamResultCode_BlockedIP = 49500,
    k_EStoveAgreeToGameTermsForSteamResultCode_BadRequest = 400000,
    k_EStoveAgreeToGameTermsForSteamResultCode_InvalidProvider = 401000,
    k_EStoveAgreeToGameTermsForSteamResultCode_GameDataNotFound = 404000,
    k_EStoveAgreeToGameTermsForSteamResultCode_GameTermsNotFound = 404200,

    k_EStoveAgreeToGameTermsForSteamResultCode_ServerErr = 500000,
    k_EStoveAgreeToGameTermsForSteamResultCode_ServerErrCommunication = 500001,
    k_EStoveAgreeToGameTermsForSteamResultCode_ServerErrCircuitOpen = 500002,

    k_EStoveAgreeToGameTermsForSteamResultCode_Max = 0x7fffffff,
} EStoveAgreeToGameTermsForSteamResultCode;

Enum Values

For all error codes, the game must display a notification screen and then exit. If the game entry check is called again before consent is granted, the game will return to the same point.

The code where Show to User is O is the code that instructs the game to display a screen informing the user of a situation. The screen and text are implemented by the developer.

Example

void __cdecl OnAgreeToGameTermsFinished(const IModuleAPICallbackResult* callbackResult,
                                        const IModuleAgreeToGameTermsForSteamOutcome* result)
{
    const IModuleAPIResult* apiResult = Stove_IModuleAPICallbackResult_GetResult(callbackResult);

    if (Stove_IModuleAPIResult_IsSuccessful(apiResult))
    {
        /* Consent reflected — Re-call the game entry check using the same Steam session token. */
        return;
    }

    switch (Stove_IModuleAPICallbackResult_GetExternalError(callbackResult))
    {
    case k_EStoveAgreeToGameTermsForSteamResultCode_BlockedIP:
    case k_EStoveAgreeToGameTermsForSteamResultCode_InvalidProvider:
        /* Display a "Connection Unavailable" message screen, then exit the game */
        break;

    case k_EStoveAgreeToGameTermsForSteamResultCode_ServerErr:
    case k_EStoveAgreeToGameTermsForSteamResultCode_ServerErrCommunication:
    case k_EStoveAgreeToGameTermsForSteamResultCode_ServerErrCircuitOpen:
        /* Display the server status notification screen, then exit the game */
        break;

    default:
        /* Display an error message screen, then exit the game */
        break;
    }
}

Notes

• This code is assigned Stove_IModuleAPICallbackResult_GetExternalError(). Do not confuse it with Stove_IModuleAPIResult_GetResultCode().
• The message provided by the server can be obtained using Stove_IModuleAPICallbackResult_GetErrorMsg().
• When you call the game entry check again after successful consent, pass in the original Steam session token exactly as it was issued. The token is obtained once per process and reused throughout the game session.
• A value not listed here may be returned as GetExternalError(). If the HTTP status code is not 200 but there is no code in the response body, the HTTP status code is passed as-is. Include a default branch in the switch statement.
• Although they use the same numbers, the result codes differ by API due to variations in their value structures. The terms of service agreement does not include the game entry checks 403201, 404001, 406401, or 503100.

Changelog

See Also

• EStoveFetchGameTermsForSteamResultCode
• EStoveGameCheckerForSteamResultCode
• EStoveModuleCommonResultCode
• Basic Integration Guide

EStoveAPIModuleMethodCode

Kind Enum · Module APIModule · Version 1.0.0

Description

This value is read as Stove_IModuleAPIResult_GetMethodCode(). It indicates which function call produced this result.

This is used when you've created a structure that receives the results of multiple requests through a single callback, or when you want to log which call failed in the error log. It is not used to determine whether a result was successful or failed.

The prices are divided into two tiers. 1~6 covers basic functions such as initialization, termination, and configuration, while 80 and above cover business functions that form the workflow for Steam integration.

Declaration

typedef enum EStoveAPIModuleMethodCode
{
    k_EStoveAPIModuleMethodCode_Initialize = 1,
    // ... See the table of enumerated values below
    k_EStoveAPIModuleMethodCode_AgreeToGameTermsForSteam = 82,

    k_EStoveAPIModuleMethodCode_Max = 0x7fffffff
} EStoveAPIModuleMethodCode;

Enum Values

Basic Functions (1–6)

Job Functions (80 or more)

Example

void __cdecl OnGameCheckerFinished(const IModuleAPICallbackResult* callbackResult,
                                   const IModuleGameCheckerForSteamOutcome* result)
{
    const IModuleAPIResult* apiResult = Stove_IModuleAPICallbackResult_GetResult(callbackResult);

    if (Stove_IModuleAPIResult_GetMethodCode(apiResult)
        == k_EStoveAPIModuleMethodCode_GameCheckerForSteam)
    {
        // These are the results from the game entry check call. They are used for log tags and other purposes.
    }
}

Notes

• Enumeration names use the same notation as the corresponding function names. For example, the uppercase I in UnInitialize(2) is consistent with Stove_APIModule_UnInitialize.
• Even if the function call fails, the method code will still be executed. Please use Stove_IModuleAPIResult_IsSuccessful() to determine whether the call was successful.
• The return type of Stove_IModuleAPIResult_GetMethodCode() is uint32_t. If you receive a type conversion warning when comparing it to an enumeration, cast it explicitly.
• The number of the reservation segment is reserved for a new function to be added in the future. Please add a branch default to line switch.

Changelog

See Also

• Basic Integration Guide
• EStoveModuleCommonResultCode
• EStoveAPIModuleTypeKind

EStoveAPIModuleTypeKind

Kind Enum · Module APIModule · Version 1.0.0

Description

This is a type identifier shared by all objects. It has two uses.

• Pass a value greater than Stove_APIModule_CreateParam(kind) to specify which parameter object to create.
• Read Stove_IModuleTypeBase_GetTypeKind(obj) to determine the type of the pointer held in the hand.

Values are divided into intervals. 0~499 is the data type of the result, and 500 or higher is the type of the parameter created and passed when the function is called.

Stove_APIModule_CreateParam() Only four parameter types actually create objects. If you pass a data type value, NULL is returned.

Declaration

typedef enum EStoveAPIModuleTypeKind
{
    k_EStoveAPIModuleTypeKind_Invalid = -1,

    k_EStoveAPIModuleTypeKind_Base = 0,
    // ... See the table of enumerated values below
    k_EStoveAPIModuleTypeKind_AgreeToGameTermsForSteamParam = 503,

    k_EStoveAPIModuleTypeKind_Max = 0x7fffffff,
} EStoveAPIModuleTypeKind;

Enum Values

Common Data Types (0–9)

Game Entry Check Data Types (10–19)

Terms and Conditions Lookup Data Types (20–29)

Terms and Conditions Consent Data Types (30–499)

Parameter Types (500 or more)

This is a value that can be passed to Stove_APIModule_CreateParam().

Example

IModuleGameCheckerForSteamParam* param = (IModuleGameCheckerForSteamParam*)
    Stove_APIModule_CreateParam(k_EStoveAPIModuleTypeKind_GameCheckerForSteamParam);

if (param == NULL)
{
    // This occurs when an unsupported value was passed or when creation failed.
    return;
}

// If necessary, you can review the type to verify it.
if (Stove_IModuleTypeBase_GetTypeKind((IModuleTypeBase*)param)
    == k_EStoveAPIModuleTypeKind_GameCheckerForSteamParam)
{
    // The expected type.
}

// Since this object was created by the caller, be sure to free it.
Stove_IModuleTypeBase_Destroy((IModuleTypeBase*)param);

Notes

• Stove_APIModule_CreateParam() only handles four parameter types (500 or higher). If any other values are passed, it returns NULL, so be sure to check the return value for null.
• Objects created with Stove_APIModule_CreateParam() are owned by the caller. After passing them to the API, you must release them using Stove_IModuleTypeBase_Destroy().
• The result object received via the callback and its child objects are owned by the SDK. It is acceptable to use GetTypeKind() to check the type, but you must not release it.
• The return type of Stove_IModuleTypeBase_GetTypeKind() is int32_t. If you receive a type conversion warning when comparing it to an enumeration, cast it explicitly.
• The number of the reservation section is a placeholder for a new type to be added in the future. Please place a default branch in the switch entry.

Changelog

See Also

• Basic Integration Guide
• EStoveAPIModuleMethodCode
• IModuleGameCheckerForSteamOutcome

EStoveFetchGameTermsForSteamAgType

Kind Enum · Module APIModule · Version 1.0.0

Description

This value specifies which consent flow terms to accept when calling Stove_APIModule_FetchGameTermsForSteam. Set it as Stove_IModuleFetchGameTermsForSteamParam_SetAgType() in the request parameters.

We make this distinction because the terms of service for users joining Steam for the first time differ from those for users transferring their existing accounts.

If no value is specified, 0(Default) will be inserted. Even if you search for 0, the Steam Game Terms of Service will appear. Please insert 2 only when you need the terms of service for the account migration process.

Declaration

typedef enum EStoveFetchGameTermsForSteamAgType
{
    k_EStoveFetchGameTermsForSteamAgType_Default = 0,

    k_EStoveFetchGameTermsForSteamAgType_Steam = 1,
    k_EStoveFetchGameTermsForSteamAgType_Mig = 2,

    k_EStoveFetchGameTermsForSteamAgType_Max = 0x7fffffff,
} EStoveFetchGameTermsForSteamAgType;

Enum Values

Example

IModuleFetchGameTermsForSteamParam* param = (IModuleFetchGameTermsForSteamParam*)
    Stove_APIModule_CreateParam(k_EStoveAPIModuleTypeKind_FetchGameTermsForSteamParam);

Stove_IModuleFetchGameTermsForSteamParam_SetGameId(param, gameId);
Stove_IModuleFetchGameTermsForSteamParam_SetAgType(param, k_EStoveFetchGameTermsForSteamAgType_Steam);

Stove_APIModule_FetchGameTermsForSteam(param, OnFetchGameTermsFinished, NULL);

// Since this object was created by the caller, be sure to release it.
Stove_IModuleTypeBase_Destroy((IModuleTypeBase*)param);

Notes

• The default value is 0. When you create a parameter object, it contains 0; if you do not specify a value, this is used in the request as-is. Both 0 and 1 accept the Steam Game Services Terms of Service.
• 1 and 2 refer to different sets of terms and conditions. You must enter the value that corresponds to the game's intended flow so that the correct terms and conditions are displayed to the user.
• If the game access check fails due to 406401 (requires agreement to the terms of service), the standard procedure for obtaining consent is 1 (or 0 without a value). 2 is used only when transferring an existing account to Steam.
• The parameter type of Stove_IModuleFetchGameTermsForSteamParam_SetAgType() is int32_t. You can pass enumeration values directly.
• If you enter an undefined value, it will be treated as 0.

Changelog

See Also

• EStoveFetchGameTermsForSteamResultCode
• EStoveAPIModuleTypeKind
• Basic Integration Guide

EStoveFetchGameTermsForSteamResultCode

Kind Result Code · Module APIModule · Version 1.0.0

Description

Stove_APIModule_FetchGameTermsForSteam is a specific result code. The value is taken directly from the response code returned by the Stove backend; 0 indicates success.

This value is extracted from the callback argument as Stove_IModuleAPICallbackResult_GetExternalError(). Stove_IModuleAPIResult_GetResultCode() does not contain this value, but rather the value from EStoveModuleCommonResultCode (success 0, server response failure 1, HTTP failure 21, etc.). You must examine both values together to accurately determine the cause of the failure.

The values are grouped by HTTP status code series. 4xxxxx indicates a request or data issue, while 5xxxxx indicates a server issue.

Viewing the Terms of Service is the first step in the process that occurs when the game entry check fails with error code 406401 (Terms of Service agreement required). If the Terms of Service check fails, there is no way to obtain consent, so the user cannot enter the game. A notification screen will appear, and the game will then close.

Declaration

typedef enum EStoveFetchGameTermsForSteamResultCode
{
    k_EStoveFetchGameTermsForSteamResultCode_Success = 0,

    k_EStoveFetchGameTermsForSteamResultCode_BadRequest = 400000,
    k_EStoveFetchGameTermsForSteamResultCode_GameDataNotFound = 404000,
    k_EStoveFetchGameTermsForSteamResultCode_GameTermsNotFound = 404200,

    k_EStoveFetchGameTermsForSteamResultCode_ServerErr = 500000,
    k_EStoveFetchGameTermsForSteamResultCode_ServerErrCommunication = 500001,

    k_EStoveFetchGameTermsForSteamResultCode_Max = 0x7fffffff,
} EStoveFetchGameTermsForSteamResultCode;

Enum Values

Any error code must display a notification screen and then exit the game. If the terms of service are not received, consent cannot be granted, and without consent, the game entry check will continue to fail with error code 406401.

The code where Show to User equals O is the code that instructs the game to display a screen informing the user of the situation. The screen and text are implemented by the developer.

Example

void __cdecl OnFetchGameTermsFinished(const IModuleAPICallbackResult* callbackResult,
                                      const IModuleFetchGameTermsForSteamOutcome* result)
{
    const IModuleAPIResult* apiResult = Stove_IModuleAPICallbackResult_GetResult(callbackResult);

    if (Stove_IModuleAPIResult_IsSuccessful(apiResult))
    {
        /* Fill in the list of terms and conditions on the developer consent screen. */
        return;
    }

    switch (Stove_IModuleAPICallbackResult_GetExternalError(callbackResult))
    {
    case k_EStoveFetchGameTermsForSteamResultCode_GameTermsNotFound:
    case k_EStoveFetchGameTermsForSteamResultCode_GameDataNotFound:
        /* Displays a message stating that the terms of service cannot be retrieved, then exits the game */
        break;

    case k_EStoveFetchGameTermsForSteamResultCode_ServerErr:
    case k_EStoveFetchGameTermsForSteamResultCode_ServerErrCommunication:
        /* Display the server status notification screen, then exit the game */
        break;

    default:
        /* Display an error message screen, then exit the game */
        break;
    }
}

Notes

• This code is assigned Stove_IModuleAPICallbackResult_GetExternalError(). Do not confuse it with Stove_IModuleAPIResult_GetResultCode().
• The message provided by the server can be obtained as Stove_IModuleAPICallbackResult_GetErrorMsg().
• A value not listed here may appear as GetExternalError(). If the HTTP status code is not 200 but there is no code in the response body, the HTTP status code is passed as-is. Include a branch default in the switch statement.
• Although they use the same number, there are separate result codes for each API with different value structures. For viewing the terms of service, the codes 49500, 401000, 403201, 404001, 406401, 503100, and 500002 are not available for checking the terms of service.
• The scope of the terms and conditions to be retrieved is specified by the EStoveFetchGameTermsForSteamAgType parameter in the request.

Changelog

See Also

• EStoveFetchGameTermsForSteamAgType
• EStoveAgreeToGameTermsForSteamResultCode
• EStoveModuleCommonResultCode
• Basic Integration Guide

EStoveGameCheckerForSteamResultCode

Kind Result Code · Module APIModule · Version 1.0.0

Description

Stove_APIModule_GameCheckerForSteam is a specific result code. The value is taken directly from the response code returned by the Stove backend; 0 indicates success.

This value is extracted from the callback argument as Stove_IModuleAPICallbackResult_GetExternalError(). Stove_IModuleAPIResult_GetResultCode() does not contain this value, but rather EStoveModuleCommonResultCode (success 0, server response failure 1, HTTP failure 21, etc.). You must examine both values together to accurately determine the cause of the failure.

The values are grouped by HTTP status code series. 4xxxxx indicates a request, authorization, or data issue, while 5xxxxx indicates a server issue. Only 49500 is an exception to this rule; it is a code used exclusively for blocking connections.

The only case where the game entry check is called again is 406401 (requires agreement to the terms and conditions). In all other cases of failure, a message screen is displayed, and the game is terminated.

Declaration

typedef enum EStoveGameCheckerForSteamResultCode
{
    k_EStoveGameCheckerForSteamResultCode_Success = 0,

    k_EStoveGameCheckerForSteamResultCode_BlockedIP = 49500,
    k_EStoveGameCheckerForSteamResultCode_BadRequest = 400000,
    k_EStoveGameCheckerForSteamResultCode_InvalidProvider = 401000,
    k_EStoveGameCheckerForSteamResultCode_GameRestrict = 403201,
    k_EStoveGameCheckerForSteamResultCode_GameDataNotFound = 404000,
    k_EStoveGameCheckerForSteamResultCode_InvalidGameClientKey = 404001,
    k_EStoveGameCheckerForSteamResultCode_GameTermsNotFound = 404200,
    k_EStoveGameCheckerForSteamResultCode_NotAgreeTerms = 406401,

    k_EStoveGameCheckerForSteamResultCode_ServerErr = 500000,
    k_EStoveGameCheckerForSteamResultCode_ServerErrCommunication = 500001,
    k_EStoveGameCheckerForSteamResultCode_ServerErrCircuitOpen = 500002,
    k_EStoveGameCheckerForSteamResultCode_GameServerMaintenance = 503100,

    k_EStoveGameCheckerForSteamResultCode_Max = 0x7fffffff,
} EStoveGameCheckerForSteamResultCode;

Enum Values

For all error codes except 406401, the game must be closed after the error message is displayed. Calling the game entry check again will yield the same result.

• 403201 Sanctions: Displays the sanction information (sanction period, reason, and message) for the result object on the information screen.
• 503100 The inspection displays the inspection details (inspection period, title, and body) of the result object on the information screen.

The code where Show to User equals O is used to display a screen that informs the user of a specific situation in the game. The screen and text are implemented by the developer. However, 403201, 503100, and 406401 are (provided by the API).

406401 is not an error notice but the terms agreement screen. Instead of closing the game after the notice, take the consent, submit it, and call the game entry check again.

Example

RequestGameTerms() in the example is not an SDK function; it is defined in the example of the Stove_APIModule_FetchGameTermsForSteam page.

void __cdecl OnGameCheckerFinished(const IModuleAPICallbackResult* callbackResult,
                                   const IModuleGameCheckerForSteamOutcome* result)
{
    const IModuleAPIResult* apiResult = Stove_IModuleAPICallbackResult_GetResult(callbackResult);

    if (Stove_IModuleAPIResult_IsSuccessful(apiResult))
    {
        /* Entering the Game — This leads to launching PCSDK3. */
        return;
    }

    switch (Stove_IModuleAPICallbackResult_GetExternalError(callbackResult))
    {
    case k_EStoveGameCheckerForSteamResultCode_NotAgreeTerms:
        /* This callback carries no terms body. Call the terms lookup to get the screen values. */
        /* Order: lookup -> developer consent screen -> submit consent -> game entry check again. */
        RequestGameTerms(g_GameId);   /* calls Stove_APIModule_FetchGameTermsForSteam() */
        break;

    case k_EStoveGameCheckerForSteamResultCode_GameRestrict:
        /* Display the sanctions notice screen using the sanctions information from the result object, then exit the game */
        break;

    case k_EStoveGameCheckerForSteamResultCode_GameServerMaintenance:
        /* Display the inspection guide screen using the inspection information from the result object, then exit the game */
        break;

    case k_EStoveGameCheckerForSteamResultCode_BlockedIP:
    case k_EStoveGameCheckerForSteamResultCode_InvalidProvider:
        /* Display a "Connection Unavailable" message screen, then exit the game */
        break;

    default:
        /* Display an error message screen, then exit the game */
        break;
    }
}

Notes

• This code is assigned to Stove_IModuleAPICallbackResult_GetExternalError(). Do not confuse it with Stove_IModuleAPIResult_GetResultCode().
• The message provided by the server can be retrieved using Stove_IModuleAPICallbackResult_GetErrorMsg().
• Once your agreement to the terms and conditions is reflected on the server, 406401 will no longer appear in subsequent calls.
• A value not listed here may appear as GetExternalError(). If the HTTP status code is not 200 but there is no code in the response body, the HTTP status code is passed as-is. Include a default branch in the switch statement.
• Although they use the same number, there are separate result codes for each API with different value structures. Use EStoveFetchGameTermsForSteamResultCode to view the terms and conditions and EStoveAgreeToGameTermsForSteamResultCode to agree to them. 404001, 406401, and 503100 are used exclusively for game entry checks.

See Also

• Stove_APIModule_GameCheckerForSteam
• IModuleGameCheckerForSteamOutcome
• Basic Integration Guide

EStoveModuleCommonResultCode

Kind Result Code · Module APIModule · Version 1.0.0

Description

This is the return code used by all functions. A successful result is 0.

If you're just looking at whether it works, using Stove_IModuleAPIResult_IsSuccessful() is simpler.

This enumeration does not include the API-specific codes returned by the server (such as 406401). The server code is returned separately as Stove_IModuleAPICallbackResult_GetExternalError(). To determine the cause of the failure, you must examine both values together.

The Relationship Between Result Code and API-Specific Code

For a complete list of codes by API, please refer to the documentation for each API. Game Entry Check · View Terms and Conditions · Agreement to Terms and Conditions

Declaration

typedef enum EStoveModuleCommonResultCode
{
    k_EStoveModuleCommonResultCode_Success = 0,
    k_EStoveModuleCommonResultCode_Fail = 1,
    // ... See the table of enumerated values below
    k_EStoveModuleCommonResultCode_UnknownError = 255,

    k_EStoveModuleCommonResultCode_Max = 0x7fffffff
} EStoveModuleCommonResultCode;

Enum Values

The code where Show to User equals O is code that instructs the game to display a screen informing the user of a certain situation. The screen layout and text are determined by the developer. — means that this code is not passed to the game callback, so there is no need to determine whether to display it.

General Results

Call Condition Error

We need to fix the game's integration code. There is no need to notify users.

Communication and Response Errors

System and Runtime Errors

253 and 254 are classified by exception type. 254 is a formatted exception, so it comes with a cause string, while 253 is an exception where the type cannot be specified, so it has no cause string. The screen displayed to the user can be the same, but please distinguish between the two codes in the log. This helps narrow down the cause when inquiries are made.

Example

void __cdecl OnGameCheckerFinished(const IModuleAPICallbackResult* callbackResult,
                                   const IModuleGameCheckerForSteamOutcome* result)
{
    const IModuleAPIResult* apiResult = Stove_IModuleAPICallbackResult_GetResult(callbackResult);

    if (Stove_IModuleAPIResult_IsSuccessful(apiResult))
    {
        // Please implement the logic for a successful outcome.
        return;
    }

    switch (Stove_IModuleAPIResult_GetResultCode(apiResult))
    {
    case k_EStoveModuleCommonResultCode_Fail:
        // This is a case where the server returned an error. The code branches based on the value returned by GetExternalError().
        break;

    case k_EStoveModuleCommonResultCode_HttpError:
    case k_EStoveModuleCommonResultCode_ResponseError:
        // Displays a screen showing the network or server status.
        break;

    case k_EStoveModuleCommonResultCode_UnmanagedException:
    case k_EStoveModuleCommonResultCode_ManagedException:
        // Displays a temporary error message screen.
        break;

    default:
        // Please implement other error-handling mechanisms.
        break;
    }
}

Notes

• The error codes returned by the server for each API are passed as Stove_IModuleAPICallbackResult_GetExternalError(), not as this enumeration. If you make decisions based solely on the error code, you won't be able to identify the cause of the failure.
• 1(Fail) and 21(HttpError) both contain server code in GetExternalError(). Even if the resulting code is different, you must not proceed without checking the server code.
• The message provided by the server can be obtained as Stove_IModuleAPICallbackResult_GetErrorMsg(). Since this string becomes invalid once the callback returns, be sure to copy it if needed.
• 24(ResponseValueIsNull) and 25(ResponseInvalidValueFormat) are displayed when the server response does not conform to the specifications. Since this is not an issue that can be resolved by the game, we respond by displaying an information screen; please contact us if the issue occurs again.
• In the "View Terms and Conditions" and "Agree to Terms and Conditions" sections, 24 takes precedence over 1 (Fail). If the server returns a failure code without sending a result value, the result code is overwritten by 24, and the actual reason remains only in GetExternalError(). Therefore, you must always check GetExternalError() first to determine the cause of the failure.
• If you pass NULL to onFinished, it will be treated as a parameter error, but since there is no callback to receive the result, nothing will be observed in the game. Always specify a callback.
• The return type of Stove_IModuleAPIResult_GetResultCode() is uint32_t. If you receive a type conversion warning when comparing it to an enumeration, cast it explicitly.

Changelog

See Also

• Basic Integration Guide
• EStoveGameCheckerForSteamResultCode
• EStoveFetchGameTermsForSteamResultCode
• EStoveAgreeToGameTermsForSteamResultCode
• EStoveAPIModuleMethodCode

IModuleAgreeToGameTermsForSteamOutcome

Kind Struct · Module APIModule · Version 1.0.0

Description

This is the result data passed as the second argument to the Stove_APIModule_AgreeToGameTermsForSteam callback. It contains a single consent identifier (GUID) issued by the server.

A consent ID is a value issued by the server to distinguish between consent processing results. The module does not interpret this value; it simply passes it along as-is. The game does not need to use this value directly, but it is helpful to log it in case troubleshooting is required.

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

This object belongs to the SDK and becomes invalid as soon as the callback returns. Do not call Destroy(); if you want to retain the value, copy it within the callback.

Declaration

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

Members

Memory Management

Example

void __cdecl OnAgreeToGameTermsFinished(const IModuleAPICallbackResult* callbackResult,
                                        const IModuleAgreeToGameTermsForSteamOutcome* result)
{
    const IModuleAPIResult* apiResult = Stove_IModuleAPICallbackResult_GetResult(callbackResult);

    if (Stove_IModuleAPIResult_IsSuccessful(apiResult))
    {
        const wchar_t* guid =
            Stove_IModuleAgreeToGameTermsForSteamOutcome_GetGuid(result);
        (void)guid; /* I'll make a note of it. */

        /* Since the consent has been reflected, the game entry check is called again. */
    }
    else
    {
        /* Please implement the logic for when an error occurs. */
    }

    /* `result` does not call `Destroy()`. */
}

Notes

• If the consent submission is successful, the game entry check (Stove_APIModule_GameCheckerForSteam) is called again. At this point, the Steam session token retains the same value.
• If the operation fails, this object will not be populated with a value. Check whether the operation succeeded first.
• Success is determined not by this object, but by the result of the first argument passed to the callback. The reason for failure is identified as Stove_IModuleAPICallbackResult_GetExternalError().

See Also

• Stove_APIModule_AgreeToGameTermsForSteam
• IModuleAgreeToGameTermsForSteamParam
• EStoveAgreeToGameTermsForSteamResultCode

IModuleAgreeToGameTermsForSteamParam

Kind Struct · Module APIModule · Version 1.0.0

Description

Contains the parameters required for the Stove_APIModule_AgreeToGameTermsForSteam call. Sets the game ID and Steam session token.

Set it to Stove_APIModule_CreateParam(k_EStoveAPIModuleTypeKind_AgreeToGameTermsForSteamParam), fill in the value, call the function, and when the function returns, release it as Destroy().

The developer is responsible for implementing the process of displaying the terms and conditions screen to the user and obtaining their consent. This API is only responsible for submitting the consent status to the server.

For the Steam session token, enter the exact value used for the game entry check. Since this value is issued once per process and reused throughout the game session, do not request a new one for this call.

Declaration

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

Members

Memory Management

Example

IModuleAgreeToGameTermsForSteamParam* param =
    (IModuleAgreeToGameTermsForSteamParam*)Stove_APIModule_CreateParam(
        k_EStoveAPIModuleTypeKind_AgreeToGameTermsForSteamParam);

Stove_IModuleAgreeToGameTermsForSteamParam_SetGameId(param, L"YOUR_GAME_ID");
Stove_IModuleAgreeToGameTermsForSteamParam_SetSteamSessionToken(param, steamSessionToken);

Stove_APIModule_AgreeToGameTermsForSteam(param, OnAgreeToGameTermsFinished, NULL);

Stove_IModuleTypeBase_Destroy((IModuleTypeBase*)param);

Notes

• Do not include which terms and conditions you agreed to in the parameter. Your consent will be treated as covering all the terms and conditions you viewed.
• If the consent submission is successful, the game entry check is called again. The same Steam session token is used at this time as well.
• If you call this before initialization is complete, it will fail with error k_EStoveModuleCommonResultCode_NotInitialized(10).

See Also

• Stove_APIModule_AgreeToGameTermsForSteam
• IModuleAgreeToGameTermsForSteamOutcome
• IModuleFetchGameTermsForSteamParam
• Stove_APIModule_CreateParam

IModuleAPICallbackResult

Kind Struct · Module APIModule · Version 1.0.0

Description

This is the result passed as the first argument to the callback of all asynchronous APIs. It wraps IModuleAPIResult and contains the error message, the response code returned by the server, and the userData pointer passed at the time of the call.

You can only determine the cause of the failure by looking at both values together. GetResult()'s ResultCode contains the common error code, while GetExternalError() contains the specific API error code returned by the server.

If you branch based solely on GetResultCode(), you won't be able to distinguish between "Non-acceptance of Terms" (406401), "Sanctions" (403201), and "Inspection" (503100). Please use the GetExternalError() value for screen branching.

This object and the result object obtained from GetResult() are owned by the SDK. Do not call Destroy(); instead, copy any values you need to keep within the callback.

Declaration

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

Members

Memory Management

Example

void __cdecl OnGameCheckerFinished(const IModuleAPICallbackResult* callbackResult,
                                   const IModuleGameCheckerForSteamOutcome* result)
{
    const IModuleAPIResult* apiResult = Stove_IModuleAPICallbackResult_GetResult(callbackResult);

    if (Stove_IModuleAPIResult_IsSuccessful(apiResult))
    {
        /* Please implement the logic for the success case. */
        return;
    }

    /* Common Result Codes — Determines whether the communication itself failed. */
    uint32_t resultCode = Stove_IModuleAPIResult_GetResultCode(apiResult);

    /* Code provided by the server — Use this value for screen branching. */
    int32_t externalError = Stove_IModuleAPICallbackResult_GetExternalError(callbackResult);

    if (externalError == k_EStoveGameCheckerForSteamResultCode_NotAgreeTerms)
    {
        /* You will be redirected to the Terms and Conditions agreement screen. */
    }
    else if (resultCode == k_EStoveModuleCommonResultCode_HttpError)
    {
        /* A communication failure message will be displayed. */
    }
    else
    {
        const wchar_t* errorMsg = Stove_IModuleAPICallbackResult_GetErrorMsg(callbackResult);
        (void)errorMsg; /* I'm logging this. */
    }

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

Notes

• The callback runs on the thread that called Stove_APIModule_RunCallback(), not on an internal SDK thread. This function is called from the game UI (main) thread.
• userData is not passed directly as a callback argument. It is retrieved via Stove_IModuleAPICallbackResult_GetUserData().
• If you pass a stack variable or a temporary object via userData, it will have already been destroyed by the time the callback is executed, resulting in a dangling pointer that can cause a crash. If you don't use it, pass NULL instead.
• The meaning of the value ExternalError varies by API. For game access checks, see EStoveGameCheckerForSteamResultCode; for viewing the terms of service, see EStoveFetchGameTermsForSteamResultCode; and for agreeing to the terms of service, see EStoveAgreeToGameTermsForSteamResultCode.
• If the operation is successful, ExternalError is 0. Check the value only if the operation fails.

See Also

• IModuleAPIResult
• EStoveModuleCommonResultCode
• Stove_APIModule_RunCallback
• Basic Integration Guide

IModuleAPIInitializeParam

Kind Struct · Module APIModule · Version 1.0.0

Description

Contains the parameters required for the Stove_APIModule_Initialize call. Set the execution environment, platform name, Steam app ID, and Steam user ID.

Create it as Stove_APIModule_CreateParam(k_EStoveAPIModuleTypeKind_APIInitializeParam), fill in the value, pass it to the initialization function, and when the function returns, release it as Destroy(). Although this is an asynchronous function, the SDK copies the value at the time of the call, so you can release it immediately without having to wait for the callback.

The platform name is fixed as L"STEAM". This is because the only supported external platform is Steam.

Declaration

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

Members

Environment If you enter a string other than L"live" · L"sandbox", initialization will fail with error 2(InvalidParam). The same applies to an empty string. Please be especially careful with the following two cases.

• Spaces before or after the value are not allowed. If there are spaces, such as in L"LIVE ", the command will fail.
• It is not case-sensitive. L"LIVE", L"Live", and L"live" all function the same way.

If the operation fails, you can check which value was incorrect by looking at the Stove_IModuleAPICallbackResult_GetErrorMsg() message in the callback.

Memory Management

Example

IModuleAPIInitializeParam* param =
    (IModuleAPIInitializeParam*)Stove_APIModule_CreateParam(
        k_EStoveAPIModuleTypeKind_APIInitializeParam);

Stove_IModuleAPIInitializeParam_SetEnvironment(param, L"live");
Stove_IModuleAPIInitializeParam_SetPlatformName(param, L"STEAM");
Stove_IModuleAPIInitializeParam_SetSteamAppId(param, L"YOUR_STEAM_APP_ID");
Stove_IModuleAPIInitializeParam_SetSteamUserId(param, steamUserId);

Stove_APIModule_Initialize(param, OnInitializeFinished, NULL);

/* Although it is an asynchronous function, you can release the parameters immediately. */
Stove_IModuleTypeBase_Destroy((IModuleTypeBase*)param);

Notes

• The game ID is not included in this parameter. Enter it in the "Game Entry Check," "Terms and Conditions View," and "Terms and Conditions Agreement" parameters, respectively.
• The Steam session token is also not included in this parameter. The session token is issued once per process, and the same value is used for both the game entry check and the terms of service agreement parameter.
• Initialization is asynchronous. To receive the callback, you must be running Stove_APIModule_RunCallback() in the game loop.
• If you call it again when it has already been initialized, it will fail with error k_EStoveModuleCommonResultCode_AlreadyInitialized(11).

See Also

• Stove_APIModule_Initialize
• Stove_APIModule_CreateParam
• EStoveAPIModuleTypeKind
• Basic Integration Guide

IModuleAPIResult

Kind Struct · Module APIModule · Version 1.0.0

Description

This is the result of calling a synchronous function. It contains the name of the function that generated the result (MethodCode) and the result code (ResultCode).

Functions that operate synchronously, such as Stove_APIModule_UnInitialize(), Stove_APIModule_SetLanguage(), Stove_APIModule_GetGdsInfo(), and Stove_APIModule_GetVersion(), return this object. Objects received through this path must be released by the caller.

In an asynchronous callback, you receive an object of the same type as IModuleAPICallbackResult in GetResult(). In this case, since the SDK owns it, you do not need to release it.

ResultCode contains the value EStoveModuleCommonResultCode (success 0, failure 1, HTTP failure 21, etc.). The API-specific code returned by the server (e.g., 406401) is not this value but is passed as GetExternalError() in the callback result.

Declaration

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

Members

Memory Management

Example

/* Synchronous function — The caller releases the returned result object. */
IModuleAPIResult* result = Stove_APIModule_SetLanguage(L"ko");

if (Stove_IModuleAPIResult_IsSuccessful(result))
{
    /* Please implement the logic for a successful outcome. */
}
else
{
    uint32_t resultCode = Stove_IModuleAPIResult_GetResultCode(result);
    uint32_t methodCode = Stove_IModuleAPIResult_GetMethodCode(result);
    (void)resultCode;
    (void)methodCode;
    /* Please implement the logic for when an error occurs. */
}

Stove_IModuleTypeBase_Destroy((IModuleTypeBase*)result);

Notes

• IsSuccessful() has the same meaning as ResultCode == 0. If you're only looking at whether it succeeded or failed, IsSuccessful() is easier to read.
• To accurately determine the cause of the failure, you need to examine both ResultCode and GetExternalError() in the callback path. ResultCode alone is not enough to identify the reason provided by the server.
• MethodCode is used to distinguish between the results of different API calls when logging them in a single location.
• If you do not deallocate the return value of a synchronous function, memory leaks will occur. You must deallocate it even if you only check the result code and then discard it.

See Also

• IModuleAPICallbackResult
• EStoveModuleCommonResultCode
• EStoveAPIModuleMethodCode
• IModuleTypeBase

IModuleFetchGameTermsForSteamContent

Kind Struct · Module APIModule · Version 1.0.0

Description

This is a single set of terms and conditions generated from IModuleFetchGameTermsForSteamOutcome to GetContentAt(index). It includes the title and body text to be displayed on the screen, the effective date, and the consent type.

The consent type (AgreeType) is the classification the server assigns to each terms item. FIRST_MUST refers to terms that require first-time consent (Steam Game Service Terms of Use), while NONE marks an item outside that classification. Decide by this value, never by the array position.

Present every item you received on one screen. Instead of a checkbox per item, place a single combined consent checkbox at the bottom of the screen. Consent is not split by type.

The values map to the screen as follows: Title is the terms title, Text is the terms body, EnforcedDt is the effective date, and AgreeType is the consent type. The screen title, the button and checkbox labels, and the date format are decided by the developer.

The terms body (Text) is delivered as HTML.

The value entered in STOVE Partners is relayed as-is, so it contains HTML by default. If your game UI cannot display HTML as-is, plain text can be provided instead — please contact technical support.

This object is owned by the parent result object. Do not call Destroy(); instead, copy the string to be displayed within the callback.

Declaration

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

Members

Memory Management

Example

AddRequiredTermsSection() · AddNoticeTermsSection() in the example are placeholder functions that the SDK does not provide. They belong to your game UI, so implement them yourself.

/* Copying one terms item into a screen model. */
typedef struct GameTermsItem
{
    wchar_t* Title;         /* terms title */
    wchar_t* Text;          /* terms body */
    int64_t  EnforcedDt;    /* effective date (epoch milliseconds) */
    int      MustAgree;     /* mandatory or not */
} GameTermsItem;

static int CopyTermsItem(const IModuleFetchGameTermsForSteamContent* content,
                         GameTermsItem* item)
{
    const wchar_t* title;
    const wchar_t* text;
    const wchar_t* agreeType;

    if (content == NULL || item == NULL)
    {
        return 0;
    }

    title     = Stove_IModuleFetchGameTermsForSteamContent_GetTitle(content);
    text      = Stove_IModuleFetchGameTermsForSteamContent_GetText(content);
    agreeType = Stove_IModuleFetchGameTermsForSteamContent_GetAgreeType(content);

    /* AgreeType is a string, not an enumeration. Never decide by array position. */
    item->MustAgree = (agreeType != NULL && wcscmp(agreeType, L"FIRST_MUST") == 0);

    /* The pointers go invalid once the callback returns, so copy them here. */
    item->Title      = _wcsdup(title != NULL ? title : L"");
    item->Text       = _wcsdup(text != NULL ? text : L"");
    item->EnforcedDt = Stove_IModuleFetchGameTermsForSteamContent_GetEnforcedDt(content);

    return 1;
}

static void ReadTerms(const IModuleFetchGameTermsForSteamOutcome* result)
{
    uint32_t contentCount =
        Stove_IModuleFetchGameTermsForSteamOutcome_GetContentCount(result);

    for (uint32_t i = 0; i < contentCount; ++i)
    {
        const IModuleFetchGameTermsForSteamContent* content =
            Stove_IModuleFetchGameTermsForSteamOutcome_GetContentAt(result, i);

        GameTermsItem item;
        if (CopyTermsItem(content, &item) == 0)
        {
            continue;
        }

        if (item.MustAgree)
        {
            /* Terms that require first-time consent. Mark them as required on screen. */
            AddRequiredTermsSection(&item);
        }
        else
        {
            /* Any other item. It also requires consent, so show it as well. */
            AddNoticeTermsSection(&item);
        }
    }

    /* Never call Destroy() on content. */
}

Notes

• This object cannot be obtained on its own. It can only be accessed as GetContentAt(index) of the parent result object.
• AgreeType is a string, not an enumeration. When comparing, treat it as a string.
• The body is delivered as HTML. It is relayed exactly as entered in STOVE Partners, and neither the SDK nor the server transforms it.
• The body is long, so place it in a scrollable area. Never truncate or summarize it.
• If displaying HTML as-is is not feasible for your UI, plain text can be provided instead — please contact technical support.
• EnforcedDt is a Unix epoch value in milliseconds. When passing it to an API that uses seconds, divide it by 1000. The game handles the display format conversion.

See Also

• IModuleFetchGameTermsForSteamOutcome
• Stove_APIModule_FetchGameTermsForSteam
• EStoveFetchGameTermsForSteamAgType

IModuleFetchGameTermsForSteamOutcome

Kind Struct · Module APIModule · Version 1.0.0

Description

This is the result data passed as the second argument to the Stove_APIModule_FetchGameTermsForSteam callback. It contains the list of terms and conditions to be displayed to the user.

There may be multiple records. Instead of using an array pointer, we read them using the count and index accessors. We use GetContentCount() to get the count and GetContentAt(index) to retrieve them one by one.

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

This object and the items obtained via GetContentAt() are owned by the SDK and become invalid the moment the callback returns. Do not call Destroy(); instead, perform a deep copy of the title and body to be displayed on the screen within the callback.

Declaration

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

Members

Memory Management

Example

ShowGameTermsUI() in the example is a placeholder function that the SDK does not provide. It belongs to your game UI, so implement it yourself.

/* Model handed to the terms screen. Fill one entry per returned item. */
typedef struct GameTermsItem
{
    wchar_t* Title;         /* terms title */
    wchar_t* Text;          /* terms body */
    int64_t  EnforcedDt;    /* effective date (epoch milliseconds) */
    int      MustAgree;     /* mandatory or not */
} GameTermsItem;

#define MAX_GAME_TERMS 16
static GameTermsItem g_Terms[MAX_GAME_TERMS];
static uint32_t      g_TermsCount = 0;

void __cdecl OnFetchGameTermsFinished(const IModuleAPICallbackResult* callbackResult,
                                      const IModuleFetchGameTermsForSteamOutcome* result)
{
    const IModuleAPIResult* apiResult = Stove_IModuleAPICallbackResult_GetResult(callbackResult);

    if (!Stove_IModuleAPIResult_IsSuccessful(apiResult))
    {
        /* Implement your failure handling here. */
        return;
    }

    uint32_t contentCount =
        Stove_IModuleFetchGameTermsForSteamOutcome_GetContentCount(result);

    if (contentCount == 0)
    {
        /* Nothing to display. Do not open the consent screen. */
        return;
    }

    g_TermsCount = 0;

    for (uint32_t i = 0; i < contentCount && g_TermsCount < MAX_GAME_TERMS; ++i)
    {
        const IModuleFetchGameTermsForSteamContent* content =
            Stove_IModuleFetchGameTermsForSteamOutcome_GetContentAt(result, i);
        if (content == NULL)
        {
            continue;
        }

        const wchar_t* title =
            Stove_IModuleFetchGameTermsForSteamContent_GetTitle(content);
        const wchar_t* text =
            Stove_IModuleFetchGameTermsForSteamContent_GetText(content);
        const wchar_t* agreeType =
            Stove_IModuleFetchGameTermsForSteamContent_GetAgreeType(content);

        /* The pointers above go invalid once the callback returns, so copy them here. */
        GameTermsItem* item = &g_Terms[g_TermsCount++];
        item->Title      = _wcsdup(title != NULL ? title : L"");
        item->Text       = _wcsdup(text != NULL ? text : L"");
        item->EnforcedDt = Stove_IModuleFetchGameTermsForSteamContent_GetEnforcedDt(content);
        item->MustAgree  = (agreeType != NULL && wcscmp(agreeType, L"FIRST_MUST") == 0);
    }

    /* Show the terms screen with the copied values. Display every item you received. */
    ShowGameTermsUI(g_Terms, g_TermsCount);

    /* Never call Destroy() on result or on the terms items. */
}

Notes

• Indices start at 0 and are valid up to GetContentCount() - 1. If you go outside this range, NULL will be returned, so be sure to check for null values even inside loops.
• GetContentAt() The lifetime of the object returned here is the same as that of this object. It becomes invalid once the callback completes.
• The terms body can be lengthy. Instead of rendering the screen inside the callback, it is better to copy the values and build the screen outside the callback.
• The body (Text) is delivered as HTML. If that does not fit your UI, contact technical support to receive plain text instead.
• If the search results show 0 entries, it means there are no terms and conditions to display on the screen. Please verify the number of entries before proceeding to submit your consent.
• One item corresponds to one block on the terms screen (title, body, effective date, consent type). If several items are returned, repeat that block for each of them.

See Also

• IModuleFetchGameTermsForSteamContent
• Stove_APIModule_FetchGameTermsForSteam
• IModuleFetchGameTermsForSteamParam
• EStoveFetchGameTermsForSteamResultCode

IModuleFetchGameTermsForSteamParam

Kind Struct · Module APIModule · Version 1.0.0

Description

Contains the parameters required for the Stove_APIModule_FetchGameTermsForSteam call. Sets the game ID and the terms and conditions type.

Set it to Stove_APIModule_CreateParam(k_EStoveAPIModuleTypeKind_FetchGameTermsForSteamParam), fill in the value, call the function, and when the function returns, release it as Destroy().

The "Terms Type" (AgType) is a value that determines which set of terms to apply. The Steam Game Service Terms of Service are k_EStoveFetchGameTermsForSteamAgType_Steam (1), and the AGS Transfer Terms are k_EStoveFetchGameTermsForSteamAgType_Mig (2).

AgType The default value is k_EStoveFetchGameTermsForSteamAgType_Default (0), and querying with this value will return the Steam Game Terms of Service. Set this to 2 only when you need the AGS Transfer Terms of Service.

Declaration

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

Members

Memory Management

Example

IModuleFetchGameTermsForSteamParam* param =
    (IModuleFetchGameTermsForSteamParam*)Stove_APIModule_CreateParam(
        k_EStoveAPIModuleTypeKind_FetchGameTermsForSteamParam);

Stove_IModuleFetchGameTermsForSteamParam_SetGameId(param, L"YOUR_GAME_ID");
Stove_IModuleFetchGameTermsForSteamParam_SetAgType(param, k_EStoveFetchGameTermsForSteamAgType_Steam);

Stove_APIModule_FetchGameTermsForSteam(param, OnFetchGameTermsFinished, NULL);

Stove_IModuleTypeBase_Destroy((IModuleTypeBase*)param);

Notes

• AgType is declared as int32_t. Simply enter the enumeration value as is.
• This parameter does not contain a Steam session token. Terms of Service lookups work based solely on the game ID and the type of terms of service.
• If the game entry check fails with error code 406401 (Terms of Service not accepted), use this API to retrieve the Terms of Service, display them on the screen, and submit the form with error code Stove_APIModule_AgreeToGameTermsForSteam after obtaining consent.

See Also

• Stove_APIModule_FetchGameTermsForSteam
• EStoveFetchGameTermsForSteamAgType
• IModuleFetchGameTermsForSteamOutcome
• Stove_APIModule_CreateParam

IModuleGameCheckerForSteamGdsInfo

Kind Struct · Module APIModule · Version 1.0.0

Description

This is regional information derived from IModuleGameCheckerForSteamOutcome to GetGdsInfo(). It includes the country of access, the regulations applicable to that country, the time zone, and the language.

The system identifies the server based on the connection IP address. If it cannot be identified, the default value is filled in, and IsDefault becomes true. Use this value on screens that require regulatory notation (e.g., GDPR) or for time displays.

This object is owned by the parent result object. Do not call Destroy(); instead, copy any values you wish to retain within the callback.

Declaration

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

Members

Memory Management

Example

void __cdecl OnGameCheckerFinished(const IModuleAPICallbackResult* callbackResult,
                                   const IModuleGameCheckerForSteamOutcome* result)
{
    const IModuleAPIResult* apiResult = Stove_IModuleAPICallbackResult_GetResult(callbackResult);

    if (!Stove_IModuleAPIResult_IsSuccessful(apiResult))
    {
        /* Please implement the logic for when an error occurs. */
        return;
    }

    const IModuleGameCheckerForSteamGdsInfo* gdsInfo =
        Stove_IModuleGameCheckerForSteamOutcome_GetGdsInfo(result);

    if (gdsInfo != NULL)
    {
        const wchar_t* nation = Stove_IModuleGameCheckerForSteamGdsInfo_GetNation(gdsInfo);
        const wchar_t* regulation = Stove_IModuleGameCheckerForSteamGdsInfo_GetRegulation(gdsInfo);
        int32_t utcOffset =
            Stove_IModuleGameCheckerForSteamGdsInfo_GetUtcOffset(gdsInfo);

        /* Copy the values you want to use outside the callback here. */
        (void)nation;
        (void)regulation;
        (void)utcOffset;
    }

    /* Do not call Destroy() on gdsInfo. */
}

Notes

• The unit of UtcOffset is minutes. To convert to hours, divide by 60. If you need to handle time zones accurately, it is safer to use the IANA time zone ID Timezone in conjunction with this value.
• This object does not have a member that returns the client's IP address. Even if some documentation states that the IP address interpreted by the server is required, it is not provided by the current interface.
• It is a different type from IModuleStoveGDSInfo, which has the same member composition. In that case, it is an object returned by the synchronization lookup function, and the caller must release it.
• If the game entry check fails, an object with an empty value is passed.

See Also

• IModuleGameCheckerForSteamOutcome
• IModuleStoveGDSInfo
• Stove_APIModule_GetGdsInfo

IModuleGameCheckerForSteamMaintenanceInfo

Kind Struct · Module APIModule · Version 1.0.0

Description

This is maintenance information obtained from IModuleGameCheckerForSteamOutcome to GetMaintenanceInfo(). It includes the maintenance period, as well as the title and body of the announcement.

This value is populated when the game entry check fails due to maintenance (k_EStoveGameCheckerForSteamResultCode_GameServerMaintenance, 503100). In all other cases, it is passed as an empty object.

The maintenance notice screen is implemented by the developer. You can use the title (Title) and body (Msg) as-is on the screen.

This object is owned by the parent result object. Do not call Destroy(); instead, copy the values you want to keep inside the callback.

Declaration

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

Members

Memory Management

Example

ShowNoticeUI() in the example is a placeholder function that the SDK does not provide. It belongs to your game UI, so implement it yourself.

void __cdecl OnGameCheckerFinished(const IModuleAPICallbackResult* callbackResult,
                                   const IModuleGameCheckerForSteamOutcome* result)
{
    const IModuleAPIResult* apiResult = Stove_IModuleAPICallbackResult_GetResult(callbackResult);

    if (Stove_IModuleAPIResult_IsSuccessful(apiResult))
    {
        /* Please implement the logic for a successful outcome. */
        return;
    }

    if (Stove_IModuleAPICallbackResult_GetExternalError(callbackResult)
        == k_EStoveGameCheckerForSteamResultCode_GameServerMaintenance)
    {
        const IModuleGameCheckerForSteamMaintenanceInfo* maintenanceInfo =
            Stove_IModuleGameCheckerForSteamOutcome_GetMaintenanceInfo(result);

        if (maintenanceInfo != NULL)
        {
            const wchar_t* title =
                Stove_IModuleGameCheckerForSteamMaintenanceInfo_GetTitle(maintenanceInfo);
            const wchar_t* msg =
                Stove_IModuleGameCheckerForSteamMaintenanceInfo_GetMsg(maintenanceInfo);
            int64_t endDt =
                Stove_IModuleGameCheckerForSteamMaintenanceInfo_GetEndDt(maintenanceInfo);

            /* Use the text delivered by the SDK as-is on the notice screen. */
            /* ShowNoticeUI is the notice screen you implement. */
            ShowNoticeUI(title,   /* maintenance notice title - use as the screen title */
                         msg,     /* maintenance notice body - use as the body */
                         endDt);  /* maintenance end time (epoch ms) - the game picks the format */

            /* Close the game once the user confirms. Calling again yields the same result. */
        }
    }

    /* Do not call Destroy() in maintenanceInfo. */
}

Notes

• This object is passed even when it is not being inspected. It is passed as an empty object, but please perform a null check as well.
• Whether a check has been performed is determined by the return code (GetExternalError() is 503100), not by the value of this object.
• UseYn is the string "Y" / "N", not bool.
• During the check, calling the game entry check again will produce the same result. Please handle this by displaying the guidance screen and then exiting the game.

See Also

• IModuleGameCheckerForSteamOutcome
• IModuleGameCheckerForSteamRestrictInfo
• EStoveGameCheckerForSteamResultCode

IModuleGameCheckerForSteamMember

Kind Struct · Module APIModule · Version 1.0.0

Description

This is member information obtained as IModuleGameCheckerForSteamOutcome of GetMember(). It contains account-level information such as the Stove member number, nickname, country of registration, verification status, and registration date and time.

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

This object is owned by the parent result object. Do not call Destroy(); instead, copy any values you wish to retain within the callback.

Declaration

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

Members

Memory Management

Example

void __cdecl OnGameCheckerFinished(const IModuleAPICallbackResult* callbackResult,
                                   const IModuleGameCheckerForSteamOutcome* result)
{
    const IModuleAPIResult* apiResult = Stove_IModuleAPICallbackResult_GetResult(callbackResult);

    if (!Stove_IModuleAPIResult_IsSuccessful(apiResult))
    {
        /* Please implement the logic for when a failure occurs. */
        return;
    }

    const IModuleGameCheckerForSteamMember* member =
        Stove_IModuleGameCheckerForSteamOutcome_GetMember(result);

    if (member != NULL)
    {
        int64_t memberNo = Stove_IModuleGameCheckerForSteamMember_GetMemberNo(member);
        const wchar_t* nickname = Stove_IModuleGameCheckerForSteamMember_GetNickname(member);
        const wchar_t* personVerifyYn =
            Stove_IModuleGameCheckerForSteamMember_GetPersonVerifyYn(member);

        /* Copy the values you want to use outside the callback here. */
        (void)memberNo;
        (void)nickname;
        (void)personVerifyYn;
    }

    /* Do not call Destroy() on `member`. */
}

Notes

• The three fields for authentication status are the strings "Y" and "N", not bool. When comparing them, treat them as strings.
• RegDt and BirthDt are values in milliseconds relative to the epoch. The game handles converting them into a format suitable for display.
• The linking procedure does not vary depending on the account type. AccountType is a value that is only referenced when the game requires it.
• If the game entry check fails, an object with an empty value is passed.

See Also

• IModuleGameCheckerForSteamOutcome
• IModuleGameCheckerForSteamUser
• Stove_APIModule_GameCheckerForSteam

IModuleGameCheckerForSteamOutcome

Kind Struct · Module APIModule · Version 1.0.0

Description

This is the result data passed as the second argument to the Stove_APIModule_GameCheckerForSteam callback. It contains the issued token and expiration time, as well as member information, game user IDs, region information, sanctions information, and maintenance information as child objects.

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

Token and member information are populated only when the operation is successful. Sanction information is populated during a sanction (403201), and maintenance information is populated during a maintenance (503100); when neither applies, the object contains empty values.

This object and all its child objects are owned by the SDK and become invalid the moment the callback returns. Do not call Destroy(); instead, perform a deep copy of any values you want to keep within the callback. Since strings are passed by pointer, saving the pointer itself can create a dangling pointer, which may cause a crash.

Declaration

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

Members

Child object

Subobjects also provide access functions following the same rule (Stove_<Interface>_<Method>). Please refer to the respective documents for details on their member composition.

Memory Management

Example

void __cdecl OnGameCheckerFinished(const IModuleAPICallbackResult* callbackResult,
                                   const IModuleGameCheckerForSteamOutcome* result)
{
    const IModuleAPIResult* apiResult = Stove_IModuleAPICallbackResult_GetResult(callbackResult);

    if (Stove_IModuleAPIResult_IsSuccessful(apiResult))
    {
        /* Token — Copy it to save it. */
        const wchar_t* accessToken = Stove_IModuleGameCheckerForSteamOutcome_GetAccessToken(result);
        int64_t expiresInMs = Stove_IModuleGameCheckerForSteamOutcome_GetExpiresIn(result);
        (void)accessToken;
        (void)expiresInMs;

        /* Subobject — Member Information */
        const IModuleGameCheckerForSteamMember* member =
            Stove_IModuleGameCheckerForSteamOutcome_GetMember(result);
        if (member != NULL)
        {
            int64_t memberNo = Stove_IModuleGameCheckerForSteamMember_GetMemberNo(member);
            const wchar_t* nickname = Stove_IModuleGameCheckerForSteamMember_GetNickname(member);
            (void)memberNo;
            (void)nickname;
        }

        /* Game User ID */
        const IModuleGameCheckerForSteamUser* user =
            Stove_IModuleGameCheckerForSteamOutcome_GetUser(result);
        if (user != NULL)
        {
            const wchar_t* userId = Stove_IModuleGameCheckerForSteamUser_GetUserId(user);
            (void)userId;
        }
        return;
    }

    /* If sanctions apply, the system reads the sanctions information and displays it on the guidance screen. */
    if (Stove_IModuleAPICallbackResult_GetExternalError(callbackResult)
        == k_EStoveGameCheckerForSteamResultCode_GameRestrict)
    {
        const IModuleGameCheckerForSteamRestrictInfo* restrictInfo =
            Stove_IModuleGameCheckerForSteamOutcome_GetRestrictInfo(result);
        if (restrictInfo != NULL)
        {
            const wchar_t* label =
                Stove_IModuleGameCheckerForSteamRestrictInfo_GetBanTypeLabel(restrictInfo);
            (void)label;
        }
    }

    /* "result" and all its child objects will be invalidated once this callback finishes. Do not call Destroy(). */
}

Notes

• ExpiresIn (milliseconds) and ExpireIn (seconds) differ by only one character in their names but represent different units. Please do not confuse them.
• Subobjects are passed as empty objects even when that isn't the case. Still, it's safer to include a null check.
• I believe the cause of the failure is Stove_IModuleAPICallbackResult_GetExternalError(), the first argument of the callback, rather than this object.
• The regional information (IModuleGameCheckerForSteamGdsInfo) does not contain a field that returns the client IP as interpreted by the server.

See Also

• Stove_APIModule_GameCheckerForSteam
• IModuleGameCheckerForSteamParam
• EStoveGameCheckerForSteamResultCode
• Basic Integration Guide

IModuleGameCheckerForSteamParam

Kind Struct · Module APIModule · Version 1.0.0

Description

Contains the parameters required for the Stove_APIModule_GameCheckerForSteam call. Set the two values: the game ID and the Steam session token.

Set it to Stove_APIModule_CreateParam(k_EStoveAPIModuleTypeKind_GameCheckerForSteamParam), fill in the value, call the function, and when the function returns, release it by setting it to Destroy(). Although this is an asynchronous function, the SDK copies the value at the time of the call, so you can release it immediately without waiting for the callback.

Steam session tokens are issued once per process by Steamworks and are reused throughout the game session. You do not need to issue a new one each time you call the function.

Declaration

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

Members

Memory Management

Example

IModuleGameCheckerForSteamParam* param =
    (IModuleGameCheckerForSteamParam*)Stove_APIModule_CreateParam(
        k_EStoveAPIModuleTypeKind_GameCheckerForSteamParam);

Stove_IModuleGameCheckerForSteamParam_SetGameId(param, L"YOUR_GAME_ID");
Stove_IModuleGameCheckerForSteamParam_SetSteamSessionToken(param, steamSessionToken);

Stove_APIModule_GameCheckerForSteam(param, OnGameCheckerFinished, NULL);

Stove_IModuleTypeBase_Destroy((IModuleTypeBase*)param);

Notes

• If the call fails due to non-acceptance of the terms of service (406401) and you need to call the game entry check again, create a new parameter object, but use the same Steam session token you received initially.
• If called before initialization is complete, it will fail with error k_EStoveModuleCommonResultCode_NotInitialized(10).
• The request will proceed normally even after the parameters are released. There is no need to keep the object alive until the callback is received.

See Also

• Stove_APIModule_GameCheckerForSteam
• IModuleGameCheckerForSteamOutcome
• Stove_APIModule_CreateParam
• EStoveGameCheckerForSteamResultCode

IModuleGameCheckerForSteamRestrictInfo

Kind Struct · Module APIModule · Version 1.0.0

Description

This is account restriction information obtained from IModuleGameCheckerForSteamOutcome to GetRestrictInfo(). It includes the restriction period, restriction type, and reason.

This value is populated when the game entry check fails due to sanctions (k_EStoveGameCheckerForSteamResultCode_GameRestrict, 403201). In all other cases, it is passed as an empty object.

The penalty notification screen is implemented by the developer. The text to display on the screen can include the localized BanTypeLabel and the reason explanation BlockReasonComment.

This object is owned by the parent result object. Do not call Destroy(); instead, copy the values you want to keep inside the callback.

Declaration

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

Members

Memory Management

Example

ShowNoticeUI() in the example is a placeholder function that the SDK does not provide. It belongs to your game UI, so implement it yourself.

void __cdecl OnGameCheckerFinished(const IModuleAPICallbackResult* callbackResult,
                                   const IModuleGameCheckerForSteamOutcome* result)
{
    const IModuleAPIResult* apiResult = Stove_IModuleAPICallbackResult_GetResult(callbackResult);

    if (Stove_IModuleAPIResult_IsSuccessful(apiResult))
    {
        /* Please implement the logic for a successful outcome. */
        return;
    }

    if (Stove_IModuleAPICallbackResult_GetExternalError(callbackResult)
        == k_EStoveGameCheckerForSteamResultCode_GameRestrict)
    {
        const IModuleGameCheckerForSteamRestrictInfo* restrictInfo =
            Stove_IModuleGameCheckerForSteamOutcome_GetRestrictInfo(result);

        if (restrictInfo != NULL)
        {
            const wchar_t* banTypeLabel =
                Stove_IModuleGameCheckerForSteamRestrictInfo_GetBanTypeLabel(restrictInfo);
            const wchar_t* reason =
                Stove_IModuleGameCheckerForSteamRestrictInfo_GetBlockReasonComment(restrictInfo);
            int64_t endDt =
                Stove_IModuleGameCheckerForSteamRestrictInfo_GetEndDt(restrictInfo);

            /* Use the text delivered by the SDK as-is on the notice screen. */
            /* ShowNoticeUI is the notice screen you implement. */
            ShowNoticeUI(banTypeLabel,  /* restriction label - use as the screen title */
                         reason,        /* restriction reason - use as the body */
                         endDt);        /* restriction end time (epoch ms) - the game picks the format */

            /* Close the game once the user confirms. Calling again yields the same result. */
        }
    }

    /* Do not call Destroy() on `restrictInfo`. */
}

Notes

• This object is passed even when sanctions are not in effect. It is passed as an empty object, but please also perform a null check.
• Whether a sanction applies is determined by the resulting code (GetExternalError() becomes 403201), not by the value of this object.
• For permanent sanctions, EndDt could result in a value far in the future. It is safer to set an upper limit when calculating and displaying the remaining duration.
• If you need a display message, use BanTypeLabel. Type and BlockReasonCd are code values used to branch game-related processing.

See Also

• IModuleGameCheckerForSteamOutcome
• IModuleGameCheckerForSteamMaintenanceInfo
• EStoveGameCheckerForSteamResultCode

IModuleGameCheckerForSteamUser

Kind Struct · Module APIModule · Version 1.0.0

Description

This is game user information obtained from IModuleGameCheckerForSteamOutcome to GetUser(). It contains the unique identifier used to distinguish users within the game and a list of the registration paths associated with that user.

This object is owned by the parent result object. Do not call Destroy(); instead, copy the values you wish to preserve within the callback.

Declaration

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

Members

Memory Management

Example

void __cdecl OnGameCheckerFinished(const IModuleAPICallbackResult* callbackResult,
                                   const IModuleGameCheckerForSteamOutcome* result)
{
    const IModuleAPIResult* apiResult = Stove_IModuleAPICallbackResult_GetResult(callbackResult);

    if (!Stove_IModuleAPIResult_IsSuccessful(apiResult))
    {
        /* Please implement the logic for when an error occurs. */
        return;
    }

    const IModuleGameCheckerForSteamUser* user =
        Stove_IModuleGameCheckerForSteamOutcome_GetUser(result);

    if (user != NULL)
    {
        const wchar_t* userId = Stove_IModuleGameCheckerForSteamUser_GetUserId(user);
        (void)userId;

    }

    /* Do not call Destroy() on `user`. */
}

Notes

• If the game entry check fails, an object with an empty value is passed.

See Also

• IModuleGameCheckerForSteamOutcome
• Stove_APIModule_GameCheckerForSteam

IModuleStoveGDSInfo

Kind Struct · Module APIModule · Version 1.0.0

Description

Stove_APIModule_GetGdsInfo is the regional information returned as an output parameter. It contains the country of access, the regulations applicable to that country, the time zone, and the language.

The system identifies the server based on its connection IP. If it cannot be identified, the default value is filled in, and IsDefault becomes true.

Since this is an object passed as an out parameter to a synchronous function, the caller must free it. Although it has the same member structure as the IModuleGameCheckerForSteamGdsInfo included in the game entry check results, its type and deallocation rules are different.

Declaration

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

Members

Memory Management

Example

IModuleStoveGDSInfo* gdsInfo = NULL;
IModuleAPIResult* result = Stove_APIModule_GetGdsInfo(&gdsInfo);

if (Stove_IModuleAPIResult_IsSuccessful(result) && gdsInfo != NULL)
{
    const wchar_t* nation = Stove_IModuleStoveGDSInfo_GetNation(gdsInfo);
    const wchar_t* lang = Stove_IModuleStoveGDSInfo_GetLang(gdsInfo);
    int32_t utcOffset = Stove_IModuleStoveGDSInfo_GetUtcOffset(gdsInfo);
    (void)nation;
    (void)lang;
    (void)utcOffset;
    /* Please implement the logic for the success case. */
}
else
{
    /* Please implement the logic for when an error occurs. */
}

if (gdsInfo != NULL)
{
    Stove_IModuleTypeBase_Destroy((IModuleTypeBase*)gdsInfo);
}
Stove_IModuleTypeBase_Destroy((IModuleTypeBase*)result);

Notes

• The unit of UtcOffset is minutes. To convert it to hours, divide by 60. If you need to handle time zones accurately, it is safer to use the IANA time zone ID Timezone along with it.
• This object does not have a member that returns the client IP as interpreted by the server.
• The out parameter and the return value are different objects. You must free both of them to prevent a memory leak.
• If the call fails, the out parameter may not be populated. Check for null values first.

See Also

• Stove_APIModule_GetGdsInfo
• IModuleGameCheckerForSteamGdsInfo
• IModuleAPIResult

IModuleTypeBase

Kind Struct · Module APIModule · Version 1.0.0

Description

This is the base interface for all IModule* objects provided by APIModule. It offers four functions: runtime type checking, ownership verification, deallocation, and extension lookup.

Since the parameter object, the result object, and the data object passed to the callback all inherit from this interface, you can cast any object to IModuleTypeBase* to release it or check its type.

The responsibility for deallocation varies by object. If ShouldDestroy() returns true, the caller must deallocate it using Destroy(); if it returns false, the SDK owns it, so it must not be deallocated.

Declaration

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

Members

Memory Management

You must not call Destroy() on objects owned by the SDK. This includes IModuleAPICallbackResult and IModuleXxxOutcome—which are passed as callback arguments—and their child objects.

Example

/* You can determine whether any IModule* object has been released in the same way. */
static void ReleaseIfNeeded(IModuleTypeBase* obj)
{
    if (obj == NULL)
    {
        return;
    }

    if (Stove_IModuleTypeBase_ShouldDestroy(obj))
    {
        Stove_IModuleTypeBase_Destroy(obj);
    }
}

void Sample(void)
{
    IModuleTypeBase* param =
        Stove_APIModule_CreateParam(k_EStoveAPIModuleTypeKind_GameCheckerForSteamParam);

    /* Check Type */
    if (Stove_IModuleTypeBase_GetTypeKind(param)
        == k_EStoveAPIModuleTypeKind_GameCheckerForSteamParam)
    {
        /* Set the parameters and call the API. */
    }

    ReleaseIfNeeded(param);
}

Notes

• Stove_APIModule_CreateParam() returns IModuleTypeBase*. When using it, cast it to an interface pointer that matches the requested type, and when freeing it, cast it back to IModuleTypeBase*.
• Destroy() accepts only non-const pointers. All other accessors accept const pointers.
• You must not reuse a pointer to a deallocated object. After deallocation, it is safest to initialize it to NULL.
• QueryExt() is reserved for future versions in case the interface needs to be expanded. It is not needed in the current configuration.

See Also

• EStoveAPIModuleTypeKind
• IModuleAPIResult
• IModuleAPICallbackResult
• Basic Integration Guide

Stove_APIModule_AgreeToGameTermsForSteam

Kind Function · Module APIModule · Version 1.0.0

Description

This function submits the user's consent to the server from the developer's Terms of Service screen. It is called when the game entry check fails with the error 406401 (Terms of Service consent required); it displays the Terms of Service (Stove_APIModule_FetchGameTermsForSteam()), obtains the user's consent, and then executes this function.

If this call succeeds, it calls Stove_APIModule_GameCheckerForSteam() again to continue checking for game entry.

Call this after receiving the success callback from Stove_APIModule_Initialize(). If called before initialization, it will fail with k_EStoveModuleCommonResultCode_NotInitialized(10). For the Steam session token passed to param, use the exact same value used for the game entry check.

This is an asynchronous function. The result is passed to onFinished, and to receive the callback, you must be running Stove_APIModule_RunCallback() in the game loop.

The code returned by the server to indicate acceptance of the terms of service is Stove_IModuleAPICallbackResult_GetExternalError(), not Stove_IModuleAPIResult_GetResultCode(). If you make a decision based solely on the result code, you won't be able to determine the cause of the failure.

Declaration

void Stove_APIModule_AgreeToGameTermsForSteam(const IModuleAgreeToGameTermsForSteamParam* param, OnAPIModuleAgreeToGameTermsForSteamCallback onFinished, void* userData);

Parameters

The members of param are as follows.

Returns

None

Callback

typedef void(STOVE_MODULE_API* OnAPIModuleAgreeToGameTermsForSteamCallback)(const IModuleAPICallbackResult* callbackResult, const IModuleAgreeToGameTermsForSteamOutcome* result);

The callback runs on the thread that called Stove_APIModule_RunCallback(). It is not an internal SDK thread. Stove_APIModule_RunCallback() must be called from the game UI (main) thread.

A callback is called only once per request.

Error Codes

This is the value obtained from Stove_IModuleAPIResult_GetResultCode().

The terms and conditions acceptance code is Stove_IModuleAPICallbackResult_GetExternalError(). Full list: EStoveAgreeToGameTermsForSteamResultCode

Complete list: EStoveModuleCommonResultCode

Memory Management

Example

void __cdecl OnAgreeToGameTermsFinished(const IModuleAPICallbackResult* callbackResult,
                                        const IModuleAgreeToGameTermsForSteamOutcome* result)
{
    const IModuleAPIResult* apiResult = Stove_IModuleAPICallbackResult_GetResult(callbackResult);

    if (Stove_IModuleAPIResult_IsSuccessful(apiResult))
    {
        // Success — Using the same Steam session token
        // Call `Stove_APIModule_GameCheckerForSteam()` again.
        return;
    }

    // Please implement the logic for when a failure occurs.
    // int32_t agreeCode = Stove_IModuleAPICallbackResult_GetExternalError(callbackResult);
}

void SubmitGameTermsAgreement(const wchar_t* gameId, const wchar_t* steamSessionToken)
{
    IModuleAgreeToGameTermsForSteamParam* param = (IModuleAgreeToGameTermsForSteamParam*)
        Stove_APIModule_CreateParam(k_EStoveAPIModuleTypeKind_AgreeToGameTermsForSteamParam);

    Stove_IModuleAgreeToGameTermsForSteamParam_SetGameId(param, gameId);
    Stove_IModuleAgreeToGameTermsForSteamParam_SetSteamSessionToken(param, steamSessionToken);

    Stove_APIModule_AgreeToGameTermsForSteam(param, OnAgreeToGameTermsFinished, NULL);

    // Since this object was created by the caller, be sure to release it.
    Stove_IModuleTypeBase_Destroy((IModuleTypeBase*)param);
}

// Called every frame in the game loop (game UI thread)
// Stove_APIModule_RunCallback();

Notes

• Consent is submitted per game, not per item. The parameter carries only the game ID and the Steam session token; it does not report which items were checked. Even if you place a checkbox on each item, submit only once.
• Call this function only if the user has agreed to the required terms and conditions. This function simply submits the request without checking whether consent has been given.
• The Steam session token is the exact value used to verify access to the game. It is issued once per process and reused throughout the game session.
• After the operation succeeds, the game entry check is called again. The same token is used in this case as well.
• The value returned by GetGuid() is an identifier used for internal processing by Stove. The game does not need to interpret or store it.
• Be sure to make a copy of any strings you want to keep within the callback. Once the callback returns, the pointer becomes invalid.

See Also

• Stove_APIModule_FetchGameTermsForSteam
• Stove_APIModule_GameCheckerForSteam
• IModuleAgreeToGameTermsForSteamOutcome
• EStoveAgreeToGameTermsForSteamResultCode
• Basic Integration Guide

Stove_APIModule_CreateParam

Kind Function · Module APIModule · Version 1.0.0

Description

All parameter objects for APIModule are created using this single function. It creates an object corresponding to the value specified in kind and returns it as IModuleTypeBase*; the game then casts it to the desired parameter type, populates it with values, and passes it to the API.