외부플랫폼연동모듈 레퍼런스 — Native

SDK 버전 1.0.0 기준이에요. 항목 35개를 이름순으로 모은 통합 문서예요.

Contents

기본 연동 안내

종류 연동 안내 · 모듈 APIModule · 버전 1.0.0

Description

APIModule(외부플랫폼연동모듈)은 스팀 런처로 실행된 게임이 스토브 런처로 실행한 것과 똑같이 스토브 플랫폼 기능을 쓸 수 있도록 이어 주는 모듈이에요. 스팀에서 인증된 사용자 정보로 스토브 플랫폼 인증을 처리하고, 게임 진입에 필요한 토큰과 회원 정보를 확보하는 시점까지가 이 모듈의 역할이에요.

지원 플랫폼은 스팀(Steam) 하나예요. 다른 외부 플랫폼은 제공하지 않아요. 이 모듈은 Steamworks SDK 를 포함하지 않으며, 게임이 Steamworks SDK 를 이미 연동하고 초기화해 두었다는 것을 전제로 동작해요.

사용자에게 보여 줄 화면(약관 동의 · 접속 불가 안내 · 제재 안내 · 점검 안내 · 오류 팝업)은 모두 개발사가 구현해요. 모듈은 화면에 넣을 값과 결과 코드만 제공해요.

이 모듈은 이전 자료에서 다른 이름으로 불린 적이 있어요. 모두 같은 모듈이며, 현재 명칭은 APIModule 이에요.

헤더 구성

배포 바이너리는 APIModule.dll 이고, 공개 헤더는 4종이에요. 함수를 쓰려면 api_module.h 를, C 환경에서 인터페이스 멤버에 접근하려면 api_module_flat.h 를 함께 포함해요.

Declaration Forms

인터페이스 멤버는 C++ 가상 함수와 C flat 접근자 두 가지 형태로 제공되며, 동작은 같아요. flat 접근자는 내부에서 같은 이름의 가상 함수를 호출해요.

• 모든 공개 함수는 extern "C" + __cdecl 로 공개돼요. 32비트 빌드에서 호출 규약이 어긋나면 스택이 깨지므로, 함수 포인터를 직접 선언할 때도 __cdecl 을 지켜야 해요.
• 헤더는 이 호출 규약을 STOVE_MODULE_API 매크로로 표기해요. MSVC 에서는 __cdecl 로, 그 밖의 컴파일러에서는 빈 문자열로 정의돼요. 이 문서의 선언은 헤더 표기를 그대로 옮겼고, 예제 코드에서 게임이 정의하는 콜백 함수는 __cdecl 로 적었어요. 두 표기는 MSVC 에서 같은 뜻이에요.
• 헤더에는 각 flat 함수의 함수 포인터 typedef(<함수명>_t)도 함께 선언되어 있지만 이 문서에서는 표기하지 않아요. 동적 로딩(GetProcAddress) 용도로 필요할 때만 참고하세요.

각 함수 문서의 ## Example 은 두 형태를 C · C++ 탭으로 나란히 싣어요. 같은 API 를 어느 쪽으로 호출해도 결과가 같으므로 프로젝트 환경에 맞는 탭 하나만 보면 돼요.

SDK 함수(Stove_APIModule_*)는 두 탭에서 같아요. 달라지는 것은 인터페이스 멤버 접근과 해제 표기뿐이에요. 여기서 말하는 C++ 는 신규 인터페이스를 C++ 문법으로 호출하는 것이며, PCSDK3 의 구 C++ 인터페이스(Stove::PCSDK::<Module>)와는 달라요.

Naming Rules

종료 함수는 Stove_APIModule_UnInitialize 예요. 대문자 I 에 주의하세요.

Memory Lifetime

모든 SDK 오브젝트는 IModuleTypeBase 를 뿌리로 하며, ShouldDestroy() 플래그로 해제 책임이 정해져요.

일반 규칙 — 출처를 외울 필요 없이 아래 한 줄로 판단할 수 있어요.

c

if (Stove_IModuleTypeBase_ShouldDestroy(obj))   // C++ 에서는 obj->ShouldDestroy()
    Stove_IModuleTypeBase_Destroy(obj);         // C++ 에서는 obj->Destroy()

콜백 인자로 받은 객체와 그 하위 객체는 콜백이 반환되는 즉시 무효가 돼요. 콜백 밖에서 써야 하는 값은 콜백 안에서 깊은 복사해 두세요. 문자열은 const wchar_t* 포인터만 넘어오므로 포인터를 보관하면 댕글링 포인터가 되어서 크래시의 원인이 될 수 있어요.

파라미터 객체는 API 에 넘긴 뒤에도 소유권이 호출자에게 남아요. 비동기 함수라도 함수가 반환한 뒤 바로 해제할 수 있어요. SDK 는 필요한 값을 호출 시점에 복사해요.

Initialization Order

1. Steamworks 에서 스팀 세션 토큰을 발급받아요 (ISteamUser::GetAuthTicketForWebApi, 결과는 GetTicketForWebApiResponse_t 콜백으로 와요). 프로세스당 한 번 받아 게임 세션 동안 재사용하는 값이므로, 받은 값을 보관해 두고 이후 호출에 그대로 넣어요.
2. Stove_APIModule_CreateParam(k_EStoveAPIModuleTypeKind_APIInitializeParam) 로 IModuleAPIInitializeParam 을 만들고 실행 환경 · 플랫폼 이름(L"STEAM" 고정) · 스팀 앱 ID · 스팀 사용자 ID 를 설정해요.
3. Stove_APIModule_Initialize(param, onFinished, userData) 를 호출해요. 비동기이므로 결과는 콜백으로 와요. 호출 뒤 파라미터 객체를 해제해요.
4. 게임 메인 루프에서 매 프레임 Stove_APIModule_RunCallback() 을 호출하기 시작해요. 이 함수를 돌리지 않으면 3번의 콜백이 오지 않아 연동이 진행되지 않아요.
5. 초기화 성공 콜백을 받은 뒤 Stove_APIModule_GameCheckerForSteam 을 호출해요. 로그인(인증)과 게임 진입 체크를 겸하는 단일 진입점이에요.
6. 콜백에서 결과에 따라 분기해요.
   1. 성공 — 게임 진입이 가능한 상태예요. 이어서 PCSDK3 를 기동해요.
   2. 406401(약관 동의 필요) — Stove_APIModule_FetchGameTermsForSteam() 으로 약관을 조회하고, 개발사 화면으로 동의를 받은 뒤 Stove_APIModule_AgreeToGameTermsForSteam() 으로 제출한 다음 5번을 다시 호출해요.
   3. 그 밖의 실패 — 개발사 안내 화면을 띄운 뒤 게임을 종료해요.
7. 게임이 실행되는 동안 Stove_APIModule_RunCallback() 루프를 계속 유지해요.
8. 게임 종료 시 Stove_APIModule_UnInitialize() 를 호출해요. 동기 함수이며 반환된 IModuleAPIResult* 는 호출자가 해제해요.

게임 진입 체크를 다시 호출하는 경우는 406401 하나뿐이에요. 약관 동의가 서버에 반영되고 나면 이후 호출에서 406401 이 다시 나오지 않아요.

PCSDK3 와의 관계

게임 진입 체크가 성공하면 APIModule 이 로그인 상태를 PCSDK3 쪽으로 직접 이어 줘요. 개발사가 토큰을 꺼내 PCSDK3 에 전달하는 절차는 없어요.

개발사가 할 일은 게임 진입 체크 성공 뒤에 평소대로 PCSDK3 를 기동하는 것뿐이에요. 이 시점부터는 스토브 런처로 실행한 경우와 동작이 같아요.

Callback Execution Rules

• 모든 비동기 API 의 콜백은 __cdecl 호출 규약을 써요. 헤더의 콜백 typedef 에는 이 규약이 STOVE_MODULE_API 매크로로 적혀 있어요.
• 콜백은 SDK 내부 스레드가 아니라 Stove_APIModule_RunCallback() 을 호출한 스레드에서 실행돼요. 이 함수는 게임 UI(메인) 스레드에서 호출해야 해요. 그러면 콜백 안에서 게임 UI 를 바로 다룰 수 있고 별도의 동기화가 필요 없어요.
• Stove_APIModule_RunCallback() 을 호출하지 않으면 콜백은 영원히 오지 않아요. 비동기 함수를 호출하기 전부터 루프를 돌리세요.
• 콜백 인자로 받은 IModuleAPICallbackResult* 와 IModuleXxxOutcome* 은 콜백이 실행되는 동안에만 유효해요. Destroy() 를 호출하지 마세요.
• 콜백은 void* userData 를 직접 받지 않아요. 호출할 때 넘긴 값은 Stove_IModuleAPICallbackResult_GetUserData(callbackResult) 로 꺼내요.
• userData 는 SDK 가 관리하지 않는 void* 이에요. 스택 변수나 임시 객체를 가리키면 콜백 시점에 댕글링 포인터가 되어서 크래시의 원인이 될 수 있어요. 쓰지 않으면 NULL 을 넘기세요.
• onFinished 에 NULL 을 넘기면 요청은 나가지만 결과를 받을 방법이 없어요. 항상 콜백을 지정하세요.

Common Interface

모든 API 가 공유하는 타입이에요.

서버가 내려주는 API 별 코드(예: 게임 진입 체크의 406401)는 GetResultCode() 가 아니라 GetExternalError() 로 전달돼요. GetResultCode() 에는 EStoveModuleCommonResultCode 값(성공 0, 서버 응답 실패 1, HTTP 실패 21 등)이 담겨요. 두 값을 함께 봐야 실패 원인을 정확히 알 수 있어요.

Notes

• 안내 화면에 쓸 문구를 개발사가 전부 만들어야 하는 것은 아니에요. 게임 진입 체크가 제재(403201) · 점검(503100) 으로 실패하면 결과 객체에 안내 문구가 담겨 오고, 약관 동의 필요(406401) 는 약관 조회를 한 번 더 호출하면 제목과 본문을 받아요. 받은 값은 그대로 화면에 보여 주세요. 그 밖의 실패 코드는 부가 정보 없이 코드만 오므로 문구를 개발사가 정해요.
• 지원 플랫폼은 스팀 하나예요. 초기화 파라미터의 플랫폼 이름은 L"STEAM" 고정값이에요.
• Steamworks SDK 연동과 스팀 세션 토큰 발급은 개발사 몫이에요. 이 모듈은 Steamworks SDK 를 포함하지 않아요.
• 스팀 세션 토큰은 프로세스당 한 번 발급받아 게임 세션 동안 재사용해요. 게임 진입 체크 · 약관 동의 · 재호출 모두 같은 값을 써요.
• 계정 유형(AccountType)에 따라 연동 절차가 달라지지 않아요. 게임 진입 체크 동선에서 계정 유형을 구분해 처리할 필요가 없어요.
• 언어 설정(Stove_APIModule_SetLanguage)은 BCP 47 형식 문자열을 받아요. 예: L"ko", L"en", L"ja".
• 결과 객체의 하위 객체(GetRestrictInfo() · GetMaintenanceInfo())는 해당 상황이 아닐 때 값이 비어 있는 객체로 전달돼요. 값을 읽기 전에 널 검사를 함께 해 두는 편이 안전해요.

See Also

EStoveAgreeToGameTermsForSteamResultCode

종류 결과코드 · 모듈 APIModule · 버전 1.0.0

Description

Stove_APIModule_AgreeToGameTermsForSteam 전용 결과 코드예요. 값은 스토브 백엔드가 내려주는 응답 코드를 그대로 옮긴 것이며, 성공은 0 이에요.

이 값은 콜백 인자에서 Stove_IModuleAPICallbackResult_GetExternalError() 로 꺼내요. Stove_IModuleAPIResult_GetResultCode() 에는 이 값이 아니라 EStoveModuleCommonResultCode 값(성공 0, 서버 응답 실패 1, HTTP 실패 21 등)이 담겨요. 두 값을 함께 봐야 실패 원인을 정확히 알 수 있어요.

값은 HTTP 상태 코드 계열로 묶여 있어요. 4xxxxx 는 요청 · 권한 · 데이터 문제, 5xxxxx 는 서버 문제예요. 49500 만 이 규칙에서 벗어난 접속 차단 전용 코드예요.

동의 제출이 성공해야 게임 진입 체크를 다시 호출할 수 있어요. 실패하면 안내 화면을 띄운 뒤 게임을 종료해요. 동의를 받지 못한 상태로 게임 진입 체크를 다시 호출하면 다시 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

모든 실패 코드는 안내 화면을 띄운 뒤 게임을 종료해야 해요. 동의가 반영되지 않은 상태에서 게임 진입 체크를 다시 호출하면 같은 자리로 되돌아와요.

Show to User 가 O 인 코드는 게임이 사용자에게 상황을 알리는 화면을 띄워야 하는 코드예요. 화면과 문구는 개발사가 구현해요.

Example

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

    if (Stove_IModuleAPIResult_IsSuccessful(apiResult))
    {
        /* 동의 반영 완료 — 같은 스팀 세션 토큰으로 게임 진입 체크를 다시 호출합니다. */
        return;
    }

    switch (Stove_IModuleAPICallbackResult_GetExternalError(callbackResult))
    {
    case k_EStoveAgreeToGameTermsForSteamResultCode_BlockedIP:
    case k_EStoveAgreeToGameTermsForSteamResultCode_InvalidProvider:
        /* 접속 불가 안내 화면을 띄운 뒤 게임 종료 */
        break;

    case k_EStoveAgreeToGameTermsForSteamResultCode_ServerErr:
    case k_EStoveAgreeToGameTermsForSteamResultCode_ServerErrCommunication:
    case k_EStoveAgreeToGameTermsForSteamResultCode_ServerErrCircuitOpen:
        /* 서버 상태 안내 화면을 띄운 뒤 게임 종료 */
        break;

    default:
        /* 오류 안내 화면을 띄운 뒤 게임 종료 */
        break;
    }
}

Notes

• 이 코드는 Stove_IModuleAPICallbackResult_GetExternalError() 로 전달돼요. Stove_IModuleAPIResult_GetResultCode() 와 혼동하지 마세요.
• 서버가 함께 내려주는 안내 문구는 Stove_IModuleAPICallbackResult_GetErrorMsg() 로 얻어요.
• 동의가 성공한 뒤 게임 진입 체크를 다시 호출할 때는 처음 발급받은 스팀 세션 토큰을 그대로 넣어요. 토큰은 프로세스당 한 번 받아 게임 세션 동안 재사용해요.
• 이 목록에 없는 값이 GetExternalError() 로 올라올 수 있어요. HTTP 상태 코드가 200 이 아닌데 응답 본문에 코드가 없으면 HTTP 상태 코드가 그대로 전달돼요. switch 문에는 default 분기를 두세요.
• 같은 번호를 쓰지만 값 구성이 다른 결과 코드가 API 별로 따로 있어요. 약관 동의에는 게임 진입 체크의 403201 · 404001 · 406401 · 503100 이 없어요.

Changelog

See Also

• EStoveFetchGameTermsForSteamResultCode
• EStoveGameCheckerForSteamResultCode
• EStoveModuleCommonResultCode
• 기본 연동 안내

EStoveAPIModuleMethodCode

종류 열거형 · 모듈 APIModule · 버전 1.0.0

Description

Stove_IModuleAPIResult_GetMethodCode() 로 읽는 값이에요. 이 결과가 어떤 함수 호출에서 나온 것인지 를 알려 줘요.

콜백 하나로 여러 요청의 결과를 받는 구조를 만들었거나, 오류 로그에 어느 호출이 실패했는지 남기려 할 때 써요. 결과의 성공 · 실패 판단에는 쓰지 않아요.

값은 두 구간으로 나뉘어요. 1~6 은 초기화 · 종료 · 설정 같은 기본 함수, 80 이상은 스팀 연동 동선을 이루는 업무 함수예요.

Declaration

typedef enum EStoveAPIModuleMethodCode
{
    k_EStoveAPIModuleMethodCode_Initialize = 1,
    // ... 이하 열거값 표 참조
    k_EStoveAPIModuleMethodCode_AgreeToGameTermsForSteam = 82,

    k_EStoveAPIModuleMethodCode_Max = 0x7fffffff
} EStoveAPIModuleMethodCode;

Enum Values

기본 함수 (1 ~ 6)

업무 함수 (80 이상)

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)
    {
        // 게임 진입 체크 호출에서 나온 결과입니다. 로그 태그 등에 활용합니다.
    }
}

Notes

• 열거값 이름은 대응하는 함수 이름과 같은 표기를 써요. 예를 들어 UnInitialize(2)의 대문자 I 는 Stove_APIModule_UnInitialize 와 맞춘 것이에요.
• 함수 호출이 실패해도 메서드 코드는 그대로 채워져요. 성공 여부는 Stove_IModuleAPIResult_IsSuccessful() 로 따로 판단하세요.
• Stove_IModuleAPIResult_GetMethodCode() 의 반환 타입은 uint32_t 이에요. 열거형과 비교할 때 형 변환 경고가 나면 명시적으로 캐스팅하세요.
• 예약 구간의 번호는 앞으로 새 함수가 추가될 자리예요. switch 문에는 default 분기를 두세요.

Changelog

See Also

• 기본 연동 안내
• EStoveModuleCommonResultCode
• EStoveAPIModuleTypeKind

EStoveAPIModuleTypeKind

종류 열거형 · 모듈 APIModule · 버전 1.0.0

Description

모든 오브젝트가 공통으로 들고 있는 타입 식별값이에요. 쓰임새는 두 가지예요.

• Stove_APIModule_CreateParam(kind) 에 넘겨 어떤 파라미터 객체를 만들지 지정해요.
• Stove_IModuleTypeBase_GetTypeKind(obj) 로 읽어 손에 든 포인터가 어떤 타입인지 확인해요.

값은 구간으로 나뉘어요. 0~499 는 결과로 받는 데이터 타입, 500 이상은 호출할 때 만들어 넘기는 파라미터 타입이에요.

Stove_APIModule_CreateParam() 이 실제로 객체를 만들어 주는 값은 파라미터 타입 4개뿐이에요. 데이터 타입 값을 넘기면 NULL 이 반환돼요.

Declaration

typedef enum EStoveAPIModuleTypeKind
{
    k_EStoveAPIModuleTypeKind_Invalid = -1,

    k_EStoveAPIModuleTypeKind_Base = 0,
    // ... 이하 열거값 표 참조
    k_EStoveAPIModuleTypeKind_AgreeToGameTermsForSteamParam = 503,

    k_EStoveAPIModuleTypeKind_Max = 0x7fffffff,
} EStoveAPIModuleTypeKind;

Enum Values

공통 데이터 타입 (0 ~ 9)

게임 진입 체크 데이터 타입 (10 ~ 19)

약관 조회 데이터 타입 (20 ~ 29)

약관 동의 데이터 타입 (30 ~ 499)

파라미터 타입 (500 이상)

Stove_APIModule_CreateParam() 에 넘길 수 있는 값이에요.

Example

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

if (param == NULL)
{
    // 지원하지 않는 값을 넘겼거나 생성에 실패한 경우입니다.
    return;
}

// 필요하면 타입을 되짚어 확인할 수 있습니다.
if (Stove_IModuleTypeBase_GetTypeKind((IModuleTypeBase*)param)
    == k_EStoveAPIModuleTypeKind_GameCheckerForSteamParam)
{
    // 예상한 타입입니다.
}

// 호출자가 만든 객체이므로 반드시 해제합니다.
Stove_IModuleTypeBase_Destroy((IModuleTypeBase*)param);

Notes

• Stove_APIModule_CreateParam() 은 파라미터 타입(500 이상) 4개만 처리해요. 그 밖의 값을 넘기면 NULL 을 돌려주므로 반환값의 널 검사를 빠뜨리지 마세요.
• Stove_APIModule_CreateParam() 으로 만든 객체는 호출자 소유예요. API 에 넘긴 뒤 Stove_IModuleTypeBase_Destroy() 로 해제해야 해요.
• 콜백으로 받은 결과 객체와 그 하위 객체는 SDK 소유예요. 타입을 확인하는 용도로 GetTypeKind() 를 쓰는 것은 괜찮지만 해제하면 안 돼요.
• Stove_IModuleTypeBase_GetTypeKind() 의 반환 타입은 int32_t 이에요. 열거형과 비교할 때 형 변환 경고가 나면 명시적으로 캐스팅하세요.
• 예약 구간의 번호는 앞으로 새 타입이 추가될 자리예요. switch 문에는 default 분기를 두세요.

Changelog

See Also

• 기본 연동 안내
• EStoveAPIModuleMethodCode
• IModuleGameCheckerForSteamOutcome

EStoveFetchGameTermsForSteamAgType

종류 열거형 · 모듈 APIModule · 버전 1.0.0

Description

Stove_APIModule_FetchGameTermsForSteam 을 호출할 때 어떤 동의 동선의 약관을 받을지 지정하는 값이에요. 요청 파라미터의 Stove_IModuleFetchGameTermsForSteamParam_SetAgType() 로 설정해요.

스팀에서 처음 게임에 들어오는 사용자에게 받는 약관과, 기존 계정을 옮겨 오는 사용자에게 받는 약관이 다르기 때문에 구분해요.

값을 설정하지 않으면 0(Default) 이 들어가요. 0 으로 조회해도 스팀 게임 서비스 약관이 내려와요. 기존 계정을 옮겨 오는 동선의 약관이 필요할 때만 2 를 넣으세요.

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);

// 호출자가 만든 객체이므로 반드시 해제합니다.
Stove_IModuleTypeBase_Destroy((IModuleTypeBase*)param);

Notes

• 기본값은 0 이에요. 파라미터 객체를 만들면 0 이 들어 있고, 설정하지 않으면 그대로 요청에 쓰예요. 0 과 1 은 모두 스팀 게임 서비스 약관을 받아요.
• 1 과 2 는 서로 다른 약관 묶음을 가리켜요. 게임이 진행하려는 동선에 맞는 값을 넣어야 사용자에게 보여 줄 약관이 올바르게 내려와요.
• 게임 진입 체크가 406401(약관 동의 필요)로 실패해 동의를 받는 일반적인 경우는 1(또는 값을 넣지 않은 0)이에요. 2 는 기존 계정을 스팀으로 옮겨 오는 동선에서만 써요.
• Stove_IModuleFetchGameTermsForSteamParam_SetAgType() 의 파라미터 타입은 int32_t 이에요. 열거형 값을 그대로 넘길 수 있어요.
• 정의되지 않은 값을 넣으면 0 과 같게 처리돼요.

Changelog

See Also

• EStoveFetchGameTermsForSteamResultCode
• EStoveAPIModuleTypeKind
• 기본 연동 안내

EStoveFetchGameTermsForSteamResultCode

종류 결과코드 · 모듈 APIModule · 버전 1.0.0

Description

Stove_APIModule_FetchGameTermsForSteam 전용 결과 코드예요. 값은 스토브 백엔드가 내려주는 응답 코드를 그대로 옮긴 것이며, 성공은 0 이에요.

이 값은 콜백 인자에서 Stove_IModuleAPICallbackResult_GetExternalError() 로 꺼내요. Stove_IModuleAPIResult_GetResultCode() 에는 이 값이 아니라 EStoveModuleCommonResultCode 값(성공 0, 서버 응답 실패 1, HTTP 실패 21 등)이 담겨요. 두 값을 함께 봐야 실패 원인을 정확히 알 수 있어요.

값은 HTTP 상태 코드 계열로 묶여 있어요. 4xxxxx 는 요청 · 데이터 문제, 5xxxxx 는 서버 문제예요.

약관 조회는 게임 진입 체크가 406401(약관 동의 필요)로 실패했을 때 진행하는 동선의 첫 단계예요. 약관 조회가 실패하면 동의를 받을 방법이 없으므로 게임에 들어갈 수 없어요. 안내 화면을 띄운 뒤 게임을 종료해요.

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

모든 실패 코드는 안내 화면을 띄운 뒤 게임을 종료해야 해요. 약관을 받지 못하면 동의를 진행할 수 없고, 동의가 없으면 게임 진입 체크가 계속 406401 로 실패해요.

Show to User 가 O 인 코드는 게임이 사용자에게 상황을 알리는 화면을 띄워야 하는 코드예요. 화면과 문구는 개발사가 구현해요.

Example

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

    if (Stove_IModuleAPIResult_IsSuccessful(apiResult))
    {
        /* 약관 목록을 개발사 동의 화면에 채워 넣습니다. */
        return;
    }

    switch (Stove_IModuleAPICallbackResult_GetExternalError(callbackResult))
    {
    case k_EStoveFetchGameTermsForSteamResultCode_GameTermsNotFound:
    case k_EStoveFetchGameTermsForSteamResultCode_GameDataNotFound:
        /* 약관 정보를 불러올 수 없다는 안내 화면을 띄운 뒤 게임 종료 */
        break;

    case k_EStoveFetchGameTermsForSteamResultCode_ServerErr:
    case k_EStoveFetchGameTermsForSteamResultCode_ServerErrCommunication:
        /* 서버 상태 안내 화면을 띄운 뒤 게임 종료 */
        break;

    default:
        /* 오류 안내 화면을 띄운 뒤 게임 종료 */
        break;
    }
}

Notes

• 이 코드는 Stove_IModuleAPICallbackResult_GetExternalError() 로 전달돼요. Stove_IModuleAPIResult_GetResultCode() 와 혼동하지 마세요.
• 서버가 함께 내려주는 안내 문구는 Stove_IModuleAPICallbackResult_GetErrorMsg() 로 얻어요.
• 이 목록에 없는 값이 GetExternalError() 로 올라올 수 있어요. HTTP 상태 코드가 200 이 아닌데 응답 본문에 코드가 없으면 HTTP 상태 코드가 그대로 전달돼요. switch 문에는 default 분기를 두세요.
• 같은 번호를 쓰지만 값 구성이 다른 결과 코드가 API 별로 따로 있어요. 약관 조회에는 게임 진입 체크의 49500 · 401000 · 403201 · 404001 · 406401 · 503100 과 500002 가 없어요.
• 조회할 약관의 범위는 요청 파라미터의 EStoveFetchGameTermsForSteamAgType 으로 지정해요.

Changelog

See Also

• EStoveFetchGameTermsForSteamAgType
• EStoveAgreeToGameTermsForSteamResultCode
• EStoveModuleCommonResultCode
• 기본 연동 안내

EStoveGameCheckerForSteamResultCode

종류 결과코드 · 모듈 APIModule · 버전 1.0.0

Description

Stove_APIModule_GameCheckerForSteam 전용 결과 코드예요. 값은 스토브 백엔드가 내려주는 응답 코드를 그대로 옮긴 것이며, 성공은 0 이에요.

이 값은 콜백 인자에서 Stove_IModuleAPICallbackResult_GetExternalError() 로 꺼내요. Stove_IModuleAPIResult_GetResultCode() 에는 이 값이 아니라 EStoveModuleCommonResultCode(성공 0, 서버 응답 실패 1, HTTP 실패 21 등)가 담겨요. 두 값을 함께 봐야 실패 원인을 정확히 알 수 있어요.

값은 HTTP 상태 코드 계열로 묶여 있어요. 4xxxxx 는 요청 · 권한 · 데이터 문제, 5xxxxx 는 서버 문제예요. 49500 만 이 규칙에서 벗어난 접속 차단 전용 코드예요.

게임 진입 체크를 다시 호출하는 경우는 406401(약관 동의 필요) 하나뿐이에요. 나머지 실패는 안내 화면을 띄운 뒤 게임을 종료해요.

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

406401 을 제외한 모든 실패 코드는 안내 화면을 띄운 뒤 반드시 게임을 종료해야 해요. 게임 진입 체크를 다시 호출해도 같은 결과가 나와요.

• 403201 제재는 결과 객체의 제재 정보(제재 기간 · 사유 · 표시 문구)를 안내 화면에 써요
• 503100 점검은 결과 객체의 점검 정보(점검 기간 · 제목 · 본문)를 안내 화면에 써요

Show to User 가 O 인 코드는 게임이 사용자에게 상황을 알리는 화면을 띄워야 하는 코드예요. 화면과 문구는 개발사가 구현해요. 다만 403201 · 503100 · 406401 은 (API 에서 문구를 전달해요).

406401 은 오류 안내가 아니라 약관 동의 화면이에요. 다른 코드처럼 안내 후 게임을 종료하는 것이 아니라, 동의를 받아 제출한 뒤 게임 진입 체크를 다시 호출해요.

Example

예제의 RequestGameTerms() 는 SDK 함수가 아니라 예제에서 만든 함수예요. 정의는 Stove_APIModule_FetchGameTermsForSteam 문서의 예제에 있어요.

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

    if (Stove_IModuleAPIResult_IsSuccessful(apiResult))
    {
        /* 게임 진입 — PCSDK3 기동으로 이어갑니다. */
        return;
    }

    switch (Stove_IModuleAPICallbackResult_GetExternalError(callbackResult))
    {
    case k_EStoveGameCheckerForSteamResultCode_NotAgreeTerms:
        /* 이 콜백에는 약관 본문이 없습니다. 약관 조회를 호출해 화면에 채울 값을 받습니다. */
        /* 조회 -> 개발사 동의 화면 -> 동의 제출 -> 게임 진입 체크 재호출 순서입니다. */
        RequestGameTerms(g_GameId);   /* Stove_APIModule_FetchGameTermsForSteam() 호출 */
        break;

    case k_EStoveGameCheckerForSteamResultCode_GameRestrict:
        /* 결과 객체의 제재 정보로 제재 안내 화면을 띄운 뒤 게임 종료 */
        break;

    case k_EStoveGameCheckerForSteamResultCode_GameServerMaintenance:
        /* 결과 객체의 점검 정보로 점검 안내 화면을 띄운 뒤 게임 종료 */
        break;

    case k_EStoveGameCheckerForSteamResultCode_BlockedIP:
    case k_EStoveGameCheckerForSteamResultCode_InvalidProvider:
        /* 접속 불가 안내 화면을 띄운 뒤 게임 종료 */
        break;

    default:
        /* 오류 안내 화면을 띄운 뒤 게임 종료 */
        break;
    }
}

Notes

• 이 코드는 Stove_IModuleAPICallbackResult_GetExternalError() 로 전달돼요. Stove_IModuleAPIResult_GetResultCode() 와 혼동하지 마세요.
• 서버가 함께 내려주는 안내 문구는 Stove_IModuleAPICallbackResult_GetErrorMsg() 로 얻어요.
• 약관 동의가 서버에 반영되면 이후 호출에서 406401 이 다시 나오지 않아요.
• 이 목록에 없는 값이 GetExternalError() 로 올라올 수 있어요. HTTP 상태 코드가 200 이 아닌데 응답 본문에 코드가 없으면 HTTP 상태 코드가 그대로 전달돼요. switch 문에는 default 분기를 두세요.
• 같은 번호를 쓰지만 값 구성이 다른 결과 코드가 API 별로 따로 있어요. 약관 조회는 EStoveFetchGameTermsForSteamResultCode, 약관 동의는 EStoveAgreeToGameTermsForSteamResultCode 를 써요. 404001 · 406401 · 503100 은 게임 진입 체크에만 있어요.

See Also

• Stove_APIModule_GameCheckerForSteam
• IModuleGameCheckerForSteamOutcome
• 기본 연동 안내

EStoveModuleCommonResultCode

종류 결과코드 · 모듈 APIModule · 버전 1.0.0

Description

모든 함수가 공통으로 사용하는 결과 코드예요. 성공은 0 이에요.

성공 여부만 볼 때는 Stove_IModuleAPIResult_IsSuccessful() 을 쓰는 편이 간단해요.

이 열거형에는 서버가 내려주는 API 별 코드(406401 등)가 담기지 않아요. 서버 코드는 Stove_IModuleAPICallbackResult_GetExternalError() 로 따로 전달돼요. 실패 원인을 구분하려면 두 값을 함께 봐야 해요.

결과 코드와 API 별 코드의 관계

API 별 코드의 전체 목록은 각 API 문서를 참조하세요. 게임 진입 체크 · 약관 조회 · 약관 동의

Declaration

typedef enum EStoveModuleCommonResultCode
{
    k_EStoveModuleCommonResultCode_Success = 0,
    k_EStoveModuleCommonResultCode_Fail = 1,
    // ... 이하 열거값 표 참조
    k_EStoveModuleCommonResultCode_UnknownError = 255,

    k_EStoveModuleCommonResultCode_Max = 0x7fffffff
} EStoveModuleCommonResultCode;

Enum Values

Show to User 가 O 인 코드는 게임이 사용자에게 상황을 알리는 화면을 띄워야 하는 코드예요. 화면 구성과 문구는 개발사가 정해요. — 는 이 코드가 게임 콜백으로 전달되지 않아 표시를 판단할 일이 없다는 뜻이에요.

일반 결과

호출 조건 오류

게임의 연동 코드를 고쳐야 하는 상황이에요. 사용자에게 알릴 내용이 없어요.

통신 및 응답 오류

시스템 및 런타임 오류

253 과 254 는 예외의 종류로 구분돼요. 254 는 형식이 있는 예외라 원인 문자열이 함께 오고, 253 은 종류를 특정할 수 없는 예외라 원인 문자열이 없어요. 사용자에게 보여 줄 화면은 같아도 되지만, 로그에는 두 코드를 구분해 남겨 두세요. 문의 시 원인을 좁히는 데 쓰예요.

Example

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

    if (Stove_IModuleAPIResult_IsSuccessful(apiResult))
    {
        // 성공 시 로직을 구현해 주세요.
        return;
    }

    switch (Stove_IModuleAPIResult_GetResultCode(apiResult))
    {
    case k_EStoveModuleCommonResultCode_Fail:
        // 서버가 사유를 내려준 경우입니다. GetExternalError() 값으로 분기합니다.
        break;

    case k_EStoveModuleCommonResultCode_HttpError:
    case k_EStoveModuleCommonResultCode_ResponseError:
        // 네트워크 또는 서버 상태 안내 화면을 띄웁니다.
        break;

    case k_EStoveModuleCommonResultCode_UnmanagedException:
    case k_EStoveModuleCommonResultCode_ManagedException:
        // 일시적인 오류 안내 화면을 띄웁니다.
        break;

    default:
        // 그 밖의 실패 처리를 구현해 주세요.
        break;
    }
}

Notes

• 서버가 내려주는 API 별 코드는 이 열거형이 아니라 Stove_IModuleAPICallbackResult_GetExternalError() 로 전달돼요. 결과 코드만 보고 분기하면 실패 원인을 구분할 수 없어요.
• 1(Fail)과 21(HttpError)은 둘 다 GetExternalError() 에 서버 코드가 담겨요. 결과 코드가 다르다고 해서 서버 코드를 확인하지 않고 넘어가면 안 돼요.
• 서버가 함께 내려주는 안내 문구는 Stove_IModuleAPICallbackResult_GetErrorMsg() 로 얻어요. 이 문자열은 콜백이 반환되면 무효가 되므로 필요하면 복사해 두세요.
• 24(ResponseValueIsNull)와 25(ResponseInvalidValueFormat)는 서버 응답이 규격과 다를 때 전달돼요. 게임이 고칠 수 있는 문제가 아니므로 안내 화면을 띄우는 것으로 대응하고, 재현되면 문의해 주세요.
• 약관 조회·약관 동의에서는 24 가 1(Fail)보다 우선해요. 서버가 실패 코드를 내려주면서 결과 값을 함께 보내지 않으면 결과 코드가 24 로 덮이고, 실제 사유는 GetExternalError() 에만 남아요. 그래서 실패 원인은 항상 GetExternalError() 로 먼저 확인해야 해요.
• onFinished 에 NULL 을 넘기면 파라미터 오류로 처리되지만, 결과를 받을 콜백이 없으므로 게임에서는 아무것도 관측되지 않아요. 항상 콜백을 지정하세요.
• Stove_IModuleAPIResult_GetResultCode() 의 반환 타입은 uint32_t 이에요. 열거형과 비교할 때 형 변환 경고가 나면 명시적으로 캐스팅하세요.

Changelog

See Also

• 기본 연동 안내
• EStoveGameCheckerForSteamResultCode
• EStoveFetchGameTermsForSteamResultCode
• EStoveAgreeToGameTermsForSteamResultCode
• EStoveAPIModuleMethodCode

IModuleAgreeToGameTermsForSteamOutcome

종류 구조체 · 모듈 APIModule · 버전 1.0.0

Description

Stove_APIModule_AgreeToGameTermsForSteam 의 콜백 두 번째 인자로 전달되는 결과 데이터예요. 서버가 발급한 동의 식별값(guid) 하나를 담아요.

동의 식별값은 서버가 동의 처리 결과를 구분하려고 발급하는 값이에요. 모듈은 값을 해석하지 않고 그대로 전달만 해요. 게임이 이 값을 직접 쓸 일은 없으며, 문제를 확인해야 할 때 로그로 남겨 두면 도움이 돼요.

SDK 가 채워서 콜백으로 전달하는 데이터형이에요. 호출자가 직접 만들지 않아요.

이 객체는 SDK 소유이며 콜백이 반환되는 순간 무효가 돼요. Destroy() 를 호출하지 말고, 값을 남겨 두려면 콜백 안에서 복사하세요.

Declaration

typedef struct IModuleAgreeToGameTermsForSteamOutcome IModuleAgreeToGameTermsForSteamOutcome;
// 멤버 접근은 아래 멤버 표의 접근 함수를 사용합니다.

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; /* 로그로 남겨 둡니다. */

        /* 동의가 반영되었으므로 게임 진입 체크를 다시 호출합니다. */
    }
    else
    {
        /* 실패 시 로직을 구현해 주세요. */
    }

    /* result 에는 Destroy() 를 호출하지 않습니다. */
}

Notes

• 동의 제출이 성공하면 게임 진입 체크(Stove_APIModule_GameCheckerForSteam)를 다시 호출해요. 이때 스팀 세션 토큰은 같은 값을 그대로 써요.
• 실패했을 때는 이 객체에 값이 채워지지 않아요. 성공 여부를 먼저 확인하세요.
• 성공 여부는 이 객체가 아니라 콜백 첫 번째 인자의 결과로 판단해요. 실패 사유는 Stove_IModuleAPICallbackResult_GetExternalError() 로 확인해요.

See Also

• Stove_APIModule_AgreeToGameTermsForSteam
• IModuleAgreeToGameTermsForSteamParam
• EStoveAgreeToGameTermsForSteamResultCode

IModuleAgreeToGameTermsForSteamParam

종류 구조체 · 모듈 APIModule · 버전 1.0.0

Description

Stove_APIModule_AgreeToGameTermsForSteam 호출에 필요한 파라미터를 담아요. 게임 ID 와 스팀 세션 토큰을 설정해요.

Stove_APIModule_CreateParam(k_EStoveAPIModuleTypeKind_AgreeToGameTermsForSteamParam) 으로 만들고, 값을 채운 뒤 호출하고, 함수가 반환하면 Destroy() 로 해제해요.

사용자에게 약관 화면을 보여 주고 동의를 받는 절차는 개발사가 구현해요. 이 API 는 동의 사실을 서버에 제출하는 역할만 해요.

스팀 세션 토큰은 게임 진입 체크에 쓴 값을 그대로 넣어요. 프로세스당 한 번 발급받아 게임 세션 동안 재사용하는 값이므로 이 호출을 위해 다시 발급받지 않아요.

Declaration

typedef struct IModuleAgreeToGameTermsForSteamParam IModuleAgreeToGameTermsForSteamParam;
// 멤버 접근은 아래 멤버 표의 접근 함수를 사용합니다.

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

• 어떤 약관에 동의했는지는 파라미터에 넣지 않아요. 조회한 약관 전체에 대한 동의로 처리돼요.
• 동의 제출이 성공하면 게임 진입 체크를 다시 호출해요. 이때도 같은 스팀 세션 토큰을 써요.
• 초기화가 끝나기 전에 호출하면 k_EStoveModuleCommonResultCode_NotInitialized(10) 로 실패해요.

See Also

• Stove_APIModule_AgreeToGameTermsForSteam
• IModuleAgreeToGameTermsForSteamOutcome
• IModuleFetchGameTermsForSteamParam
• Stove_APIModule_CreateParam

IModuleAPICallbackResult

종류 구조체 · 모듈 APIModule · 버전 1.0.0

Description

모든 비동기 API 의 콜백 첫 번째 인자로 전달되는 결과예요. IModuleAPIResult 를 감싸고, 오류 메시지 · 서버가 내려준 결과 코드 · 호출할 때 넘긴 userData 포인터를 함께 담아요.

실패 원인은 두 값을 함께 봐야 알 수 있어요. GetResult() 의 ResultCode 에는 공통 결과 코드가, GetExternalError() 에는 서버가 내려준 API 별 코드가 담겨요.

GetResultCode() 만 보고 분기하면 약관 미동의(406401) · 제재(403201) · 점검(503100) 을 구분할 수 없어요. 화면 분기는 GetExternalError() 값으로 하세요.

이 객체와 GetResult() 로 얻은 결과 객체는 SDK 소유예요. Destroy() 를 호출하지 말고, 보관할 값은 콜백 안에서 복사해 두세요.

Declaration

typedef struct IModuleAPICallbackResult IModuleAPICallbackResult;
// 멤버 접근은 아래 멤버 표의 접근 함수를 사용합니다.

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))
    {
        /* 성공 시 로직을 구현해 주세요. */
        return;
    }

    /* 공통 결과 코드 — 통신 자체가 실패했는지 판단합니다. */
    uint32_t resultCode = Stove_IModuleAPIResult_GetResultCode(apiResult);

    /* 서버가 내려준 코드 — 화면 분기는 이 값으로 합니다. */
    int32_t externalError = Stove_IModuleAPICallbackResult_GetExternalError(callbackResult);

    if (externalError == k_EStoveGameCheckerForSteamResultCode_NotAgreeTerms)
    {
        /* 약관 동의 화면으로 이동합니다. */
    }
    else if (resultCode == k_EStoveModuleCommonResultCode_HttpError)
    {
        /* 통신 실패 안내를 띄웁니다. */
    }
    else
    {
        const wchar_t* errorMsg = Stove_IModuleAPICallbackResult_GetErrorMsg(callbackResult);
        (void)errorMsg; /* 로그로 남깁니다. */
    }

    /* callbackResult, apiResult, result 는 Destroy() 를 호출하지 않습니다. */
}

Notes

• 콜백은 SDK 내부 스레드가 아니라 Stove_APIModule_RunCallback() 을 호출한 스레드에서 실행돼요. 이 함수는 게임 UI(메인) 스레드에서 호출해요.
• userData 는 콜백 인자로 직접 오지 않아요. Stove_IModuleAPICallbackResult_GetUserData() 로 꺼내요.
• userData 로 스택 변수나 임시 객체를 넘기면 콜백 시점에 이미 소멸해 댕글링 포인터가 되어서 크래시의 원인이 될 수 있어요. 쓰지 않으면 NULL 을 넘기세요.
• ExternalError 값의 의미는 API 마다 달라요. 게임 진입 체크는 EStoveGameCheckerForSteamResultCode, 약관 조회는 EStoveFetchGameTermsForSteamResultCode, 약관 동의는 EStoveAgreeToGameTermsForSteamResultCode 를 참고하세요.
• 성공했을 때 ExternalError 는 0 이에요. 실패했을 때만 값을 확인하세요.

See Also

• IModuleAPIResult
• EStoveModuleCommonResultCode
• Stove_APIModule_RunCallback
• 기본 연동 안내

IModuleAPIInitializeParam

종류 구조체 · 모듈 APIModule · 버전 1.0.0

Description

Stove_APIModule_Initialize 호출에 필요한 파라미터를 담아요. 실행 환경 · 플랫폼 이름 · 스팀 앱 ID · 스팀 사용자 ID 를 설정해요.

Stove_APIModule_CreateParam(k_EStoveAPIModuleTypeKind_APIInitializeParam) 으로 만들고, 값을 채운 뒤 초기화 함수에 넘기고, 함수가 반환하면 Destroy() 로 해제해요. 비동기 함수이지만 SDK 가 호출 시점에 값을 복사하므로 콜백을 기다릴 필요 없이 바로 해제할 수 있어요.

플랫폼 이름은 L"STEAM" 고정이에요. 지원하는 외부 플랫폼이 스팀 하나이기 때문이에요.

Declaration

typedef struct IModuleAPIInitializeParam IModuleAPIInitializeParam;
// 멤버 접근은 아래 멤버 표의 접근 함수를 사용합니다.

Members

Environment 에 L"live" · L"sandbox" 가 아닌 문자열을 넣으면 초기화가 2(InvalidParam)로 실패해요. 빈 문자열도 같아요. 다음 두 가지를 특히 조심하세요.

• 앞뒤 공백을 허용하지 않아요. L"LIVE " 처럼 공백이 붙으면 실패해요.
• 대소문자는 가리지 않아요. L"LIVE" · L"Live" · L"live" 는 모두 같게 동작해요.

실패했을 때 어느 값이 잘못되었는지는 콜백의 Stove_IModuleAPICallbackResult_GetErrorMsg() 메시지로 확인할 수 있어요.

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);

/* 비동기 함수이지만 파라미터는 바로 해제할 수 있습니다. */
Stove_IModuleTypeBase_Destroy((IModuleTypeBase*)param);

Notes

• 게임 ID 는 이 파라미터에 없어요. 게임 진입 체크 · 약관 조회 · 약관 동의 파라미터에 각각 넣어요.
• 스팀 세션 토큰도 이 파라미터에 없어요. 세션 토큰은 프로세스당 한 번 발급받아 두고, 게임 진입 체크와 약관 동의 파라미터에 같은 값을 넣어요.
• 초기화는 비동기예요. 콜백을 받으려면 게임 루프에서 Stove_APIModule_RunCallback() 을 돌리고 있어야 해요.
• 이미 초기화된 상태에서 다시 호출하면 k_EStoveModuleCommonResultCode_AlreadyInitialized(11) 로 실패해요.

See Also

• Stove_APIModule_Initialize
• Stove_APIModule_CreateParam
• EStoveAPIModuleTypeKind
• 기본 연동 안내

IModuleAPIResult

종류 구조체 · 모듈 APIModule · 버전 1.0.0

Description

동기 함수의 호출 결과예요. 어떤 함수가 만든 결과인지(MethodCode)와 결과 코드(ResultCode)를 담아요.

Stove_APIModule_UnInitialize() · Stove_APIModule_SetLanguage() · Stove_APIModule_GetGdsInfo() · Stove_APIModule_GetVersion() 처럼 동기로 동작하는 함수가 이 객체를 반환해요. 이 경로로 받은 객체는 호출자가 해제해야 해요.

비동기 콜백에서는 IModuleAPICallbackResult 의 GetResult() 로 같은 타입의 객체를 얻어요. 이 경우에는 SDK 가 소유하므로 해제하지 않아요.

ResultCode 에는 EStoveModuleCommonResultCode 값(성공 0, 실패 1, HTTP 실패 21 등)이 담겨요. 서버가 내려주는 API 별 코드(예: 406401)는 이 값이 아니라 콜백 결과의 GetExternalError() 로 전달돼요.

Declaration

typedef struct IModuleAPIResult IModuleAPIResult;
// 멤버 접근은 아래 멤버 표의 접근 함수를 사용합니다.

Members

Memory Management

Example

/* 동기 함수 — 반환된 결과 객체는 호출자가 해제합니다. */
IModuleAPIResult* result = Stove_APIModule_SetLanguage(L"ko");

if (Stove_IModuleAPIResult_IsSuccessful(result))
{
    /* 성공 시 로직을 구현해 주세요. */
}
else
{
    uint32_t resultCode = Stove_IModuleAPIResult_GetResultCode(result);
    uint32_t methodCode = Stove_IModuleAPIResult_GetMethodCode(result);
    (void)resultCode;
    (void)methodCode;
    /* 실패 시 로직을 구현해 주세요. */
}

Stove_IModuleTypeBase_Destroy((IModuleTypeBase*)result);

Notes

• IsSuccessful() 은 ResultCode == 0 과 같은 뜻이에요. 성공 여부만 볼 때는 IsSuccessful() 을 쓰는 편이 읽기 좋아요.
• 실패 원인을 정확히 알려면 콜백 경로에서는 ResultCode 와 GetExternalError() 를 함께 봐야 해요. ResultCode 만으로는 서버가 내려준 사유를 구분할 수 없어요.
• MethodCode 는 여러 API 의 결과를 한 곳에서 로그로 남길 때 어떤 호출의 결과인지 구분하는 용도로 써요.
• 동기 함수의 반환값을 해제하지 않으면 메모리가 새어 나가요. 결과 코드만 확인하고 버리는 경우에도 반드시 해제해야 해요.

See Also

• IModuleAPICallbackResult
• EStoveModuleCommonResultCode
• EStoveAPIModuleMethodCode
• IModuleTypeBase

IModuleFetchGameTermsForSteamContent

종류 구조체 · 모듈 APIModule · 버전 1.0.0

Description

IModuleFetchGameTermsForSteamOutcome 의 GetContentAt(index) 로 얻는 약관 한 건이에요. 화면에 띄울 제목과 본문, 시행 일시, 동의 유형을 담아요.

동의 유형(AgreeType)은 서버가 약관을 분류해 내려주는 값이에요. FIRST_MUST 는 최초 동의가 필요한 약관(스팀 게임 서비스 이용 약관)이고, NONE 은 그 분류에 해당하지 않는 항목이에요. 배열 순서가 아니라 이 값으로 판단해야 해요.

내려온 약관은 한 화면에 모아 보여 주세요. 동의 체크는 항목마다 두지 않고 화면 아래쪽에 통합 동의 하나로 두면 돼요. 동의를 유형별로 나누지 않아요.

각 값이 화면 어디에 들어가는지는 다음과 같아요. Title 은 약관 제목, Text 는 약관 본문, EnforcedDt 는 시행 일시, AgreeType 은 동의 유형 구분이에요. 화면 제목과 버튼 · 체크박스 라벨, 날짜 표기 형식은 개발사가 정해요.

약관 본문(Text)은 HTML 로 전달돼요.

스토브 파트너스에 입력된 값을 그대로 전달하므로 기본적으로 HTML 이 담겨 와요. 게임 UI 구현상 HTML 을 그대로 표시하기 어렵다면 평문으로 바꿔 받을 수 있으니 기술지원으로 문의해 주세요.

이 객체는 상위 결과 객체가 소유해요. Destroy() 를 호출하지 말고, 화면에 띄울 문자열은 콜백 안에서 복사해 두세요.

Declaration

typedef struct IModuleFetchGameTermsForSteamContent IModuleFetchGameTermsForSteamContent;
// 멤버 접근은 아래 멤버 표의 접근 함수를 사용합니다.

Members

Memory Management

Example

예제의 AddRequiredTermsSection() · AddNoticeTermsSection() 는 SDK 가 제공하지 않는 가상 함수예요. 게임 UI 와 연결되는 부분이라 개발사가 직접 구현해야 해요.

/* 약관 한 건을 화면 모델로 옮기는 예입니다. */
typedef struct GameTermsItem
{
    wchar_t* Title;         /* 약관 제목 */
    wchar_t* Text;          /* 약관 본문 */
    int64_t  EnforcedDt;    /* 시행 일시 (epoch 밀리초) */
    int      MustAgree;     /* 필수 동의 여부 */
} 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 은 열거형이 아니라 문자열입니다. 배열 순서로 판단하지 않습니다. */
    item->MustAgree = (agreeType != NULL && wcscmp(agreeType, L"FIRST_MUST") == 0);

    /* 콜백이 반환되면 포인터가 무효가 되므로 여기서 복사합니다. */
    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)
        {
            /* 최초 동의가 필요한 약관입니다. 화면에 필수 표시를 함께 노출합니다. */
            AddRequiredTermsSection(&item);
        }
        else
        {
            /* 그 밖의 항목입니다. 이 항목도 동의 대상이므로 함께 보여 줍니다. */
            AddNoticeTermsSection(&item);
        }
    }

    /* content 에는 Destroy() 를 호출하지 않습니다. */
}

Notes

• 이 객체는 단독으로 얻을 수 없어요. 상위 결과 객체의 GetContentAt(index) 로만 접근해요.
• AgreeType 은 열거형이 아니라 문자열이에요. 비교할 때 문자열로 비교하세요.
• 본문은 HTML 로 전달돼요. 스토브 파트너스에 입력된 값을 그대로 전달하며 SDK 나 서버가 가공하지 않아요.
• 본문이 길어서 스크롤 가능한 영역에 넣어야 해요. 잘라내거나 요약하면 안 돼요.
• HTML 을 그대로 표시하기 어렵다면 평문으로 바꿔 받을 수 있으니 기술지원으로 문의해 주세요.
• EnforcedDt 는 Unix epoch 밀리초 값이에요. 초 단위 API 에 넘길 때는 1000 으로 나누세요. 표시 형식 변환은 게임 쪽에서 처리해요.

See Also

• IModuleFetchGameTermsForSteamOutcome
• Stove_APIModule_FetchGameTermsForSteam
• EStoveFetchGameTermsForSteamAgType

IModuleFetchGameTermsForSteamOutcome

종류 구조체 · 모듈 APIModule · 버전 1.0.0

Description

Stove_APIModule_FetchGameTermsForSteam 의 콜백 두 번째 인자로 전달되는 결과 데이터예요. 사용자에게 보여 줄 약관 목록을 담아요.

약관은 여러 건이 올 수 있어요. 배열 포인터로 주지 않고 개수와 인덱스 접근자로 읽어요. GetContentCount() 로 개수를 얻고 GetContentAt(index) 로 한 건씩 꺼내요.

SDK 가 채워서 콜백으로 전달하는 데이터형이에요. 호출자가 직접 만들지 않아요.

이 객체와 GetContentAt() 으로 얻은 항목은 SDK 소유이며 콜백이 반환되는 순간 무효가 돼요. Destroy() 를 호출하지 말고, 화면에 띄울 제목과 본문은 콜백 안에서 깊은 복사해 두세요.

Declaration

typedef struct IModuleFetchGameTermsForSteamOutcome IModuleFetchGameTermsForSteamOutcome;
// 멤버 접근은 아래 멤버 표의 접근 함수를 사용합니다.

Members

Memory Management

Example

예제의 ShowGameTermsUI() 는 SDK 가 제공하지 않는 가상 함수예요. 게임 UI 와 연결되는 부분이라 개발사가 직접 구현해야 해요.

/* 약관 화면에 넘길 모델입니다. 항목 수만큼 채워서 화면으로 넘깁니다. */
typedef struct GameTermsItem
{
    wchar_t* Title;         /* 약관 제목 */
    wchar_t* Text;          /* 약관 본문 */
    int64_t  EnforcedDt;    /* 시행 일시 (epoch 밀리초) */
    int      MustAgree;     /* 필수 동의 여부 */
} 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))
    {
        /* 실패 시 로직을 구현해 주세요. */
        return;
    }

    uint32_t contentCount =
        Stove_IModuleFetchGameTermsForSteamOutcome_GetContentCount(result);

    if (contentCount == 0)
    {
        /* 화면에 띄울 약관이 없습니다. 동의 화면을 띄우지 않습니다. */
        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);

        /* 콜백이 반환되면 위 포인터가 무효가 되므로 여기서 복사합니다. */
        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);
    }

    /* 복사한 값으로 약관 화면을 띄웁니다. 항목이 여러 건이면 전부 보여 줍니다. */
    ShowGameTermsUI(g_Terms, g_TermsCount);

    /* result 와 약관 항목에는 Destroy() 를 호출하지 않습니다. */
}

Notes

• 인덱스는 0 부터 시작하고 GetContentCount() - 1 까지 유효해요. 범위를 벗어나면 NULL 이 반환되므로 반복문 안에서도 널 검사를 해 두세요.
• GetContentAt() 이 돌려주는 객체의 수명은 이 객체와 같아요. 콜백이 끝나면 함께 무효가 돼요.
• 약관 본문은 길 수 있어요. 콜백 안에서 화면을 그리기보다 값을 복사해 두고 콜백 밖에서 화면을 구성하는 편이 좋아요.
• 본문(Text)은 HTML 로 전달돼요. 화면에 넣기 어렵다면 기술지원으로 문의해 평문으로 바꿔 받을 수 있어요.
• 조회 결과가 0 건이면 화면에 띄울 약관이 없다는 뜻이에요. 동의 제출로 넘어가기 전에 개수를 확인하세요.
• 항목 하나가 약관 화면의 한 묶음(제목 · 본문 · 시행 일시 · 동의 유형)에 대응해요. 항목이 여러 건이면 그 수만큼 반복해서 보여 주세요.

See Also

• IModuleFetchGameTermsForSteamContent
• Stove_APIModule_FetchGameTermsForSteam
• IModuleFetchGameTermsForSteamParam
• EStoveFetchGameTermsForSteamResultCode

IModuleFetchGameTermsForSteamParam

종류 구조체 · 모듈 APIModule · 버전 1.0.0

Description

Stove_APIModule_FetchGameTermsForSteam 호출에 필요한 파라미터를 담아요. 게임 ID 와 약관 종류를 설정해요.

Stove_APIModule_CreateParam(k_EStoveAPIModuleTypeKind_FetchGameTermsForSteamParam) 으로 만들고, 값을 채운 뒤 호출하고, 함수가 반환하면 Destroy() 로 해제해요.

약관 종류(AgType)는 어떤 약관 묶음을 받을지 정하는 값이에요. 스팀 게임 서비스 이용 약관은 k_EStoveFetchGameTermsForSteamAgType_Steam(1), AGS 이관 약관은 k_EStoveFetchGameTermsForSteamAgType_Mig(2) 예요.

AgType 초기값은 k_EStoveFetchGameTermsForSteamAgType_Default(0) 이며, 이 값으로 조회하면 스팀 게임 서비스 약관이 내려와요. AGS 이관 약관이 필요할 때만 2 로 설정하세요.

Declaration

typedef struct IModuleFetchGameTermsForSteamParam IModuleFetchGameTermsForSteamParam;
// 멤버 접근은 아래 멤버 표의 접근 함수를 사용합니다.

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 는 int32_t 로 선언되어 있어요. 열거값을 그대로 넣으면 돼요.
• 이 파라미터에는 스팀 세션 토큰이 없어요. 약관 조회는 게임 ID 와 약관 종류만으로 동작해요.
• 게임 진입 체크가 406401(약관 미동의)로 실패했을 때 이 API 로 약관을 받아 화면에 띄우고, 동의를 받은 뒤 Stove_APIModule_AgreeToGameTermsForSteam 으로 제출해요.

See Also

• Stove_APIModule_FetchGameTermsForSteam
• EStoveFetchGameTermsForSteamAgType
• IModuleFetchGameTermsForSteamOutcome
• Stove_APIModule_CreateParam

IModuleGameCheckerForSteamGdsInfo

종류 구조체 · 모듈 APIModule · 버전 1.0.0

Description

IModuleGameCheckerForSteamOutcome 의 GetGdsInfo() 로 얻는 지역 정보예요. 접속 국가와 그 국가에 적용되는 규제, 시간대, 언어를 담아요.

국가는 서버가 접속 IP 로 판별해요. 판별하지 못하면 기본값이 채워지고 IsDefault 가 true 가 돼요. 규제 표기(예: GDPR)가 필요한 화면이나 시간 표시에 이 값을 써요.

이 객체는 상위 결과 객체가 소유해요. Destroy() 를 호출하지 말고, 보관할 값은 콜백 안에서 복사해 두세요.

Declaration

typedef struct IModuleGameCheckerForSteamGdsInfo IModuleGameCheckerForSteamGdsInfo;
// 멤버 접근은 아래 멤버 표의 접근 함수를 사용합니다.

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))
    {
        /* 실패 시 로직을 구현해 주세요. */
        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);

        /* 콜백 밖에서 쓸 값은 여기서 복사합니다. */
        (void)nation;
        (void)regulation;
        (void)utcOffset;
    }

    /* gdsInfo 에는 Destroy() 를 호출하지 않습니다. */
}

Notes

• UtcOffset 의 단위는 분이에요. 시(hour)로 환산할 때는 60 으로 나누세요. 시간대를 정확히 다뤄야 하면 IANA 시간대 ID 인 Timezone 을 함께 쓰는 편이 안전해요.
• 이 객체에는 클라이언트 IP 를 돌려주는 멤버가 없어요. 서버가 해석한 IP 값이 필요하다고 안내한 자료가 있더라도 현재 인터페이스에서는 제공하지 않아요.
• 멤버 구성이 같은 IModuleStoveGDSInfo 와는 다른 타입이에요. 그쪽은 동기 조회 함수가 돌려주는 객체이고 호출자가 해제해야 해요.
• 게임 진입 체크가 실패하면 값이 비어 있는 객체로 전달돼요.

See Also

• IModuleGameCheckerForSteamOutcome
• IModuleStoveGDSInfo
• Stove_APIModule_GetGdsInfo

IModuleGameCheckerForSteamMaintenanceInfo

종류 구조체 · 모듈 APIModule · 버전 1.0.0

Description

IModuleGameCheckerForSteamOutcome 의 GetMaintenanceInfo() 로 얻는 점검 정보예요. 점검 기간과 안내 제목 · 본문을 담아요.

게임 진입 체크가 점검(k_EStoveGameCheckerForSteamResultCode_GameServerMaintenance, 503100)으로 실패했을 때 값이 채워져요. 그 밖의 상황에서는 값이 비어 있는 객체로 전달돼요.

점검 안내 화면은 개발사가 구현해요. 제목(Title)과 본문(Msg)을 그대로 화면에 쓸 수 있어요.

이 객체는 상위 결과 객체가 소유해요. Destroy() 를 호출하지 말고, 보관할 값은 콜백 안에서 복사해 두세요.

Declaration

typedef struct IModuleGameCheckerForSteamMaintenanceInfo IModuleGameCheckerForSteamMaintenanceInfo;
// 멤버 접근은 아래 멤버 표의 접근 함수를 사용합니다.

Members

Memory Management

Example

예제의 ShowNoticeUI() 는 SDK 가 제공하지 않는 가상 함수예요. 게임 UI 와 연결되는 부분이라 개발사가 직접 구현해야 해요.

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

    if (Stove_IModuleAPIResult_IsSuccessful(apiResult))
    {
        /* 성공 시 로직을 구현해 주세요. */
        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);

            /* 점검 안내 문구는 SDK 가 내려준 값을 그대로 씁니다. */
            /* ShowNoticeUI 는 개발사가 구현하는 안내 화면입니다. */
            ShowNoticeUI(title,   /* 점검 공지 제목 — 화면 제목으로 씁니다. */
                         msg,     /* 점검 공지 본문 — 본문으로 씁니다. */
                         endDt);  /* 점검 종료 일시 (epoch 밀리초) — 표기 형식은 게임에서 정합니다. */

            /* 사용자가 확인하면 게임을 종료합니다. 다시 호출해도 같은 결과가 나옵니다. */
        }
    }

    /* maintenanceInfo 에는 Destroy() 를 호출하지 않습니다. */
}

Notes

• 점검 상황이 아닐 때도 이 객체 자체는 전달돼요. 값이 비어 있는 객체로 오지만 널 검사도 함께 하세요.
• 점검 여부는 이 객체의 값이 아니라 결과 코드(GetExternalError() 가 503100)로 판단해요.
• UseYn 은 bool 이 아니라 "Y" / "N" 문자열이에요.
• 점검 중에는 게임 진입 체크를 다시 호출해도 같은 결과가 나와요. 안내 화면을 띄운 뒤 게임을 종료하는 흐름으로 처리하세요.

See Also

• IModuleGameCheckerForSteamOutcome
• IModuleGameCheckerForSteamRestrictInfo
• EStoveGameCheckerForSteamResultCode

IModuleGameCheckerForSteamMember

종류 구조체 · 모듈 APIModule · 버전 1.0.0

Description

IModuleGameCheckerForSteamOutcome 의 GetMember() 로 얻는 회원 정보예요. 스토브 회원 번호 · 닉네임 · 가입 국가 · 인증 여부 · 가입 일시 등 계정 단위 정보를 담아요.

SDK 가 채워서 콜백으로 전달하는 데이터형이에요. 호출자가 직접 만들지 않아요.

이 객체는 상위 결과 객체가 소유해요. Destroy() 를 호출하지 말고, 보관할 값은 콜백 안에서 복사해 두세요.

Declaration

typedef struct IModuleGameCheckerForSteamMember IModuleGameCheckerForSteamMember;
// 멤버 접근은 아래 멤버 표의 접근 함수를 사용합니다.

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))
    {
        /* 실패 시 로직을 구현해 주세요. */
        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);

        /* 콜백 밖에서 쓸 값은 여기서 복사합니다. */
        (void)memberNo;
        (void)nickname;
        (void)personVerifyYn;
    }

    /* member 에는 Destroy() 를 호출하지 않습니다. */
}

Notes

• 인증 여부 세 필드는 bool 이 아니라 "Y" / "N" 문자열이에요. 비교할 때 문자열로 비교하세요.
• RegDt 와 BirthDt 는 epoch 밀리초 값이에요. 화면에 표시할 형식으로 바꾸는 것은 게임 쪽에서 처리해요.
• 계정 유형에 따라 연동 절차가 달라지지 않아요. AccountType 은 게임이 필요할 때만 참고하는 값이에요.
• 게임 진입 체크가 실패하면 값이 비어 있는 객체로 전달돼요.

See Also

• IModuleGameCheckerForSteamOutcome
• IModuleGameCheckerForSteamUser
• Stove_APIModule_GameCheckerForSteam

IModuleGameCheckerForSteamOutcome

종류 구조체 · 모듈 APIModule · 버전 1.0.0

Description

Stove_APIModule_GameCheckerForSteam 의 콜백 두 번째 인자로 전달되는 결과 데이터예요. 발급된 토큰과 만료 시간, 그리고 회원 정보 · 게임 유저 식별값 · 지역 정보 · 제재 정보 · 점검 정보를 하위 객체로 담아요.

SDK 가 채워서 콜백으로 전달하는 데이터형이에요. 호출자가 직접 만들지 않아요.

토큰과 회원 정보는 성공했을 때만 채워져요. 제재 정보는 제재(403201), 점검 정보는 점검(503100) 상황에서 채워지며, 해당하지 않을 때는 값이 비어 있는 객체가 들어 있어요.

이 객체와 모든 하위 객체는 SDK 소유이며 콜백이 반환되는 순간 무효가 돼요. Destroy() 를 호출하지 말고, 보관할 값은 콜백 안에서 깊은 복사해 두세요. 문자열은 포인터만 넘어오므로 포인터를 저장하면 댕글링 포인터가 되어서 크래시의 원인이 될 수 있어요.

Declaration

typedef struct IModuleGameCheckerForSteamOutcome IModuleGameCheckerForSteamOutcome;
// 멤버 접근은 아래 멤버 표의 접근 함수를 사용합니다.

Members

하위 객체

하위 객체도 같은 규칙(Stove_<Interface>_<Method>)의 접근 함수를 제공해요. 멤버 구성은 각 문서를 참고하세요.

Memory Management

Example

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

    if (Stove_IModuleAPIResult_IsSuccessful(apiResult))
    {
        /* 토큰 — 보관하려면 복사합니다. */
        const wchar_t* accessToken = Stove_IModuleGameCheckerForSteamOutcome_GetAccessToken(result);
        int64_t expiresInMs = Stove_IModuleGameCheckerForSteamOutcome_GetExpiresIn(result);
        (void)accessToken;
        (void)expiresInMs;

        /* 하위 객체 — 회원 정보 */
        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;
        }

        /* 게임 유저 식별값 */
        const IModuleGameCheckerForSteamUser* user =
            Stove_IModuleGameCheckerForSteamOutcome_GetUser(result);
        if (user != NULL)
        {
            const wchar_t* userId = Stove_IModuleGameCheckerForSteamUser_GetUserId(user);
            (void)userId;
        }
        return;
    }

    /* 제재 상황이면 제재 정보를 읽어 안내 화면에 씁니다. */
    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 와 모든 하위 객체는 이 콜백이 끝나면 무효처리됩니다. Destroy() 를 호출하지 마십시오. */
}

Notes

• ExpiresIn(밀리초)과 ExpireIn(초)은 이름이 한 글자만 다르고 단위가 달라요. 혼동하지 마세요.
• 하위 객체는 해당 상황이 아니어도 값이 비어 있는 객체로 전달돼요. 그래도 널 검사를 함께 해 두는 편이 안전해요.
• 실패 사유는 이 객체가 아니라 콜백 첫 번째 인자의 Stove_IModuleAPICallbackResult_GetExternalError() 로 판단해요.
• 지역 정보(IModuleGameCheckerForSteamGdsInfo)에는 서버가 해석한 클라이언트 IP 를 돌려주는 멤버가 없어요.

See Also

• Stove_APIModule_GameCheckerForSteam
• IModuleGameCheckerForSteamParam
• EStoveGameCheckerForSteamResultCode
• 기본 연동 안내

IModuleGameCheckerForSteamParam

종류 구조체 · 모듈 APIModule · 버전 1.0.0

Description

Stove_APIModule_GameCheckerForSteam 호출에 필요한 파라미터를 담아요. 게임 ID 와 스팀 세션 토큰 두 값을 설정해요.

Stove_APIModule_CreateParam(k_EStoveAPIModuleTypeKind_GameCheckerForSteamParam) 으로 만들고, 값을 채운 뒤 호출하고, 함수가 반환하면 Destroy() 로 해제해요. 비동기 함수이지만 SDK 가 호출 시점에 값을 복사하므로 콜백을 기다리지 않고 바로 해제할 수 있어요.

스팀 세션 토큰은 Steamworks 에서 프로세스당 한 번 발급받아 게임 세션 동안 그대로 재사용해요. 호출할 때마다 새로 발급받을 필요는 없어요.

Declaration

typedef struct IModuleGameCheckerForSteamParam IModuleGameCheckerForSteamParam;
// 멤버 접근은 아래 멤버 표의 접근 함수를 사용합니다.

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

• 약관 미동의(406401) 로 실패해 게임 진입 체크를 다시 호출할 때는 파라미터 객체를 새로 만들되, 스팀 세션 토큰은 처음 받은 값을 그대로 넣어요.
• 초기화가 끝나기 전에 호출하면 k_EStoveModuleCommonResultCode_NotInitialized(10) 로 실패해요.
• 파라미터를 해제한 뒤에도 요청은 정상적으로 진행돼요. 콜백이 올 때까지 객체를 살려 둘 필요가 없어요.

See Also

• Stove_APIModule_GameCheckerForSteam
• IModuleGameCheckerForSteamOutcome
• Stove_APIModule_CreateParam
• EStoveGameCheckerForSteamResultCode

IModuleGameCheckerForSteamRestrictInfo

종류 구조체 · 모듈 APIModule · 버전 1.0.0

Description

IModuleGameCheckerForSteamOutcome 의 GetRestrictInfo() 로 얻는 이용 제재 정보예요. 제재 기간 · 제재 유형 · 사유를 담아요.

게임 진입 체크가 제재(k_EStoveGameCheckerForSteamResultCode_GameRestrict, 403201)로 실패했을 때 값이 채워져요. 그 밖의 상황에서는 값이 비어 있는 객체로 전달돼요.

제재 안내 화면은 개발사가 구현해요. 화면에 표시할 문구로는 현지화된 BanTypeLabel 과 사유 설명인 BlockReasonComment 를 쓸 수 있어요.

이 객체는 상위 결과 객체가 소유해요. Destroy() 를 호출하지 말고, 보관할 값은 콜백 안에서 복사해 두세요.

Declaration

typedef struct IModuleGameCheckerForSteamRestrictInfo IModuleGameCheckerForSteamRestrictInfo;
// 멤버 접근은 아래 멤버 표의 접근 함수를 사용합니다.

Members

Memory Management

Example

예제의 ShowNoticeUI() 는 SDK 가 제공하지 않는 가상 함수예요. 게임 UI 와 연결되는 부분이라 개발사가 직접 구현해야 해요.

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

    if (Stove_IModuleAPIResult_IsSuccessful(apiResult))
    {
        /* 성공 시 로직을 구현해 주세요. */
        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);

            /* 제재 안내 문구는 SDK 가 내려준 값을 그대로 씁니다. */
            /* ShowNoticeUI 는 개발사가 구현하는 안내 화면입니다. */
            ShowNoticeUI(banTypeLabel,  /* 제재 유형 표시 문구 — 화면 제목으로 씁니다. */
                         reason,        /* 제재 사유 — 본문으로 씁니다. */
                         endDt);        /* 제재 종료 일시 (epoch 밀리초) — 표기 형식은 게임에서 정합니다. */

            /* 사용자가 확인하면 게임을 종료합니다. 다시 호출해도 같은 결과가 나옵니다. */
        }
    }

    /* restrictInfo 에는 Destroy() 를 호출하지 않습니다. */
}

Notes

• 제재 상황이 아닐 때도 이 객체 자체는 전달돼요. 값이 비어 있는 객체로 오지만 널 검사도 함께 하세요.
• 제재 여부는 이 객체의 값이 아니라 결과 코드(GetExternalError() 가 403201)로 판단해요.
• 영구 제재는 EndDt 가 매우 먼 미래 값으로 올 수 있어요. 남은 기간을 계산해 표시할 때 상한을 두는 편이 안전해요.
• 표시 문구가 필요하면 BanTypeLabel 을 쓰세요. Type 과 BlockReasonCd 는 게임 쪽 처리를 분기할 때 쓰는 코드성 값이에요.

See Also

• IModuleGameCheckerForSteamOutcome
• IModuleGameCheckerForSteamMaintenanceInfo
• EStoveGameCheckerForSteamResultCode

IModuleGameCheckerForSteamUser

종류 구조체 · 모듈 APIModule · 버전 1.0.0

Description

IModuleGameCheckerForSteamOutcome 의 GetUser() 로 얻는 게임 유저 정보예요. 게임 안에서 사용자를 구분하는 식별값과, 이 사용자가 연결한 가입 경로 목록을 담아요.

이 객체는 상위 결과 객체가 소유해요. Destroy() 를 호출하지 말고, 보관할 값은 콜백 안에서 복사해 두세요.

Declaration

typedef struct IModuleGameCheckerForSteamUser IModuleGameCheckerForSteamUser;
// 멤버 접근은 아래 멤버 표의 접근 함수를 사용합니다.

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))
    {
        /* 실패 시 로직을 구현해 주세요. */
        return;
    }

    const IModuleGameCheckerForSteamUser* user =
        Stove_IModuleGameCheckerForSteamOutcome_GetUser(result);

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

    }

    /* user 에는 Destroy() 를 호출하지 않습니다. */
}

Notes

• 게임 진입 체크가 실패하면 값이 비어 있는 객체로 전달돼요.

See Also

• IModuleGameCheckerForSteamOutcome
• Stove_APIModule_GameCheckerForSteam

IModuleStoveGDSInfo

종류 구조체 · 모듈 APIModule · 버전 1.0.0

Description

Stove_APIModule_GetGdsInfo 가 out 파라미터로 돌려주는 지역 정보예요. 접속 국가와 그 국가에 적용되는 규제, 시간대, 언어를 담아요.

국가는 서버가 접속 IP 로 판별해요. 판별하지 못하면 기본값이 채워지고 IsDefault 가 true 가 돼요.

동기 함수의 out 파라미터로 받는 객체이므로 호출자가 해제해야 해요. 게임 진입 체크 결과에 들어 있는 IModuleGameCheckerForSteamGdsInfo 와 멤버 구성은 같지만 타입과 해제 규칙이 달라요.

Declaration

typedef struct IModuleStoveGDSInfo IModuleStoveGDSInfo;
// 멤버 접근은 아래 멤버 표의 접근 함수를 사용합니다.

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;
    /* 성공 시 로직을 구현해 주세요. */
}
else
{
    /* 실패 시 로직을 구현해 주세요. */
}

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

Notes

• UtcOffset 의 단위는 분이에요. 시(hour)로 환산할 때는 60 으로 나누세요. 시간대를 정확히 다뤄야 하면 IANA 시간대 ID 인 Timezone 을 함께 쓰는 편이 안전해요.
• 이 객체에는 서버가 해석한 클라이언트 IP 를 돌려주는 멤버가 없어요.
• out 파라미터와 반환값은 서로 다른 객체예요. 둘 다 해제해야 메모리가 새지 않아요.
• 호출이 실패하면 out 파라미터가 채워지지 않을 수 있어요. 널 검사를 먼저 하세요.

See Also

• Stove_APIModule_GetGdsInfo
• IModuleGameCheckerForSteamGdsInfo
• IModuleAPIResult

IModuleTypeBase

종류 구조체 · 모듈 APIModule · 버전 1.0.0

Description

APIModule 이 제공하는 모든 IModule* 오브젝트의 뿌리가 되는 인터페이스예요. 런타임 타입 확인, 해제 책임 확인, 해제, 확장 조회 네 가지 기능을 제공해요.

파라미터 객체 · 결과 객체 · 콜백으로 전달되는 데이터 객체가 모두 이 인터페이스를 상속하므로, 어떤 객체든 IModuleTypeBase* 로 캐스팅해 해제하거나 타입을 확인할 수 있어요.

해제 책임은 객체마다 달라요. ShouldDestroy() 가 true 를 반환하면 호출자가 Destroy() 로 해제해야 하고, false 면 SDK 가 소유하므로 해제하면 안 돼요.

Declaration

typedef struct IModuleTypeBase IModuleTypeBase;
// 멤버 접근은 아래 멤버 표의 접근 함수를 사용합니다.

Members

Memory Management

SDK 소유 객체에 Destroy() 를 호출하면 안 돼요. 콜백 인자로 전달되는 IModuleAPICallbackResult 와 IModuleXxxOutcome, 그 하위 객체가 여기에 해당해요.

Example

/* 어떤 IModule* 객체든 해제 여부를 같은 방식으로 판단할 수 있습니다. */
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);

    /* 타입 확인 */
    if (Stove_IModuleTypeBase_GetTypeKind(param)
        == k_EStoveAPIModuleTypeKind_GameCheckerForSteamParam)
    {
        /* 파라미터를 설정하고 API 를 호출합니다. */
    }

    ReleaseIfNeeded(param);
}

Notes

• Stove_APIModule_CreateParam() 은 IModuleTypeBase* 를 반환해요. 사용할 때는 요청한 종류에 맞는 인터페이스 포인터로 캐스팅하고, 해제할 때는 다시 IModuleTypeBase* 로 캐스팅해요.
• Destroy() 만 비 const 포인터를 받아요. 나머지 접근자는 모두 const 포인터를 받아요.
• 해제한 객체의 포인터를 다시 쓰면 안 돼요. 해제 뒤에는 NULL 로 초기화해 두는 편이 안전해요.
• QueryExt() 는 후속 버전에서 인터페이스를 늘릴 때를 대비해 마련된 자리예요. 현재 형상에서 쓸 일은 없어요.

See Also

• EStoveAPIModuleTypeKind
• IModuleAPIResult
• IModuleAPICallbackResult
• 기본 연동 안내

Stove_APIModule_AgreeToGameTermsForSteam

종류 함수 · 모듈 APIModule · 버전 1.0.0

Description

개발사 약관 화면에서 사용자가 동의한 결과를 서버에 제출해요. 게임 진입 체크가 406401(약관 동의 필요)로 실패했을 때, Stove_APIModule_FetchGameTermsForSteam() 으로 약관을 보여 주고 동의를 받은 다음 호출하는 함수예요.

이 호출이 성공하면 Stove_APIModule_GameCheckerForSteam() 을 다시 호출해 게임 진입 체크를 이어 가요.

Stove_APIModule_Initialize() 의 성공 콜백을 받은 뒤에 호출해요. 초기화 전에 호출하면 k_EStoveModuleCommonResultCode_NotInitialized(10) 로 실패해요. param 에 넣는 스팀 세션 토큰은 게임 진입 체크에 쓴 값을 그대로 넣어요.

비동기 함수예요. 결과는 onFinished 로 전달되며, 콜백을 받으려면 게임 루프에서 Stove_APIModule_RunCallback() 을 돌리고 있어야 해요.

서버가 내려주는 약관 동의 코드는 Stove_IModuleAPIResult_GetResultCode() 가 아니라 Stove_IModuleAPICallbackResult_GetExternalError() 로 전달돼요. 결과 코드만 보고 분기하면 실패 원인을 구분할 수 없어요.

Declaration

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

Parameters

param 의 멤버는 다음과 같아요.

Returns

없음

Callback

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

콜백은 Stove_APIModule_RunCallback() 을 호출한 스레드에서 실행돼요. SDK 내부 스레드가 아니에요. Stove_APIModule_RunCallback() 은 게임 UI(메인) 스레드에서 호출해야 해요.

콜백은 요청 하나당 한 번만 호출돼요.

Error Codes

Stove_IModuleAPIResult_GetResultCode() 로 얻는 값이에요.

약관 동의 코드는 Stove_IModuleAPICallbackResult_GetExternalError() 로 전달돼요. 전체 목록: EStoveAgreeToGameTermsForSteamResultCode

전체 목록: 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))
    {
        // 성공 — 같은 스팀 세션 토큰으로
        // Stove_APIModule_GameCheckerForSteam() 을 다시 호출합니다.
        return;
    }

    // 실패 시 로직을 구현해 주세요.
    // 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);

    // 호출자가 만든 객체이므로 반드시 해제합니다.
    Stove_IModuleTypeBase_Destroy((IModuleTypeBase*)param);
}

// 게임 루프에서 매 프레임 호출 (게임 UI 스레드)
// Stove_APIModule_RunCallback();

Notes

• 동의 제출은 항목 단위가 아니라 게임 단위예요. 파라미터에는 게임 아이디와 스팀 세션 토큰만 넣으며, 어떤 항목에 동의했는지는 보내지 않아요. 화면에 체크박스를 항목별로 두더라도 제출은 한 번만 해요.
• 사용자가 필수 약관에 동의한 경우에만 호출하세요. 이 함수는 동의 여부를 판단하지 않고 제출만 해요.
• 스팀 세션 토큰은 게임 진입 체크에 쓴 값을 그대로 넣어요. 프로세스당 한 번 발급받아 게임 세션 동안 재사용하는 값이에요.
• 성공한 뒤에는 게임 진입 체크를 다시 호출해요. 이때도 같은 토큰을 써요.
• GetGuid() 로 얻는 값은 스토브 내부 처리에 쓰이는 식별값이에요. 게임이 해석하거나 보관할 필요는 없어요.
• 콜백 안에서 보관할 문자열은 반드시 복사해 두세요. 콜백이 반환되면 포인터가 무효가 돼요.

See Also

• Stove_APIModule_FetchGameTermsForSteam
• Stove_APIModule_GameCheckerForSteam
• IModuleAgreeToGameTermsForSteamOutcome
• EStoveAgreeToGameTermsForSteamResultCode
• 기본 연동 안내

Stove_APIModule_CreateParam

종류 함수 · 모듈 APIModule · 버전 1.0.0

Description

APIModule 의 모든 파라미터 객체는 이 함수 하나로 만들어요. kind 에 지정한 값에 대응하는 객체를 생성해 IModuleTypeBase* 로 돌려주며, 게임은 이를 원하는 파라미터 타입으로 캐스팅해 값을 채운 뒤 API 에 넘겨요.