구 C++ API에서 신규 C API로 옮기기

3.4.x 이전의 C++ API(Stove::PCSDK 네임스페이스, Base_* · IAP_* · View_* 계열)로 이미 연동을 마친 게임이 3.5.0 신규 C API(Stove_* 계열)로 코드를 옮길 때 참고하는 문서예요.

신규 API로 반드시 옮겨야 하는 것은 아니에요. 3.4.x API는 계속 제공되므로, 기존 연동 코드를 그대로 두고 배포 파일만 3.5.0으로 교체해도 돼요. 이 문서는 신규 API로 코드를 변경하기로 결정한 경우에만 필요해요.

다음 순서로 읽으시면 돼요.

1. 신규 API의 기본 구조를 먼저 확인해요. (1장)
2. 현재 사용 중인 함수와 구조체가 무엇으로 바뀌는지 확인해요. (2장 · 3장)
3. 신규 API에 없는 기능을 사용하고 있는지 확인해요. (4장)
4. 코드를 변경할 때 호출 형태가 달라지는 부분을 확인해요. (5장)

1. 신규 API 기본 구조

신규 인터페이스의 규칙은 레퍼런스가이드 맨 앞의 기본 연동 안내에 정리되어 있어요. 이 장에서는 코드를 옮길 때 알아야 하는 내용만 간략하게 정리해요.

배포 파일이 하나로 줄어들어요

신규 API를 사용하면 게임과 함께 배포해야 하는 파일은 BaseSDK.dll 하나예요. 모듈마다 배포하던 IAPSDK.dll · ViewSDK.dll · PCBangSDK.dll 같은 파일은 더 이상 포함하지 않아도 돼요. 모든 기능이 하나의 바이너리에 통합되었기 때문이에요.

기존 3.4.x API로 연동한 게임은 배포 구성을 그대로 유지하세요. 바이너리가 통합된 것과 관계없이 지금까지 배포하던 모듈별 파일을 계속 포함해야 해요. 배포 파일이 하나로 줄어드는 것은 신규 API로 옮긴 경우에만 해당해요.

모듈 구분이 없어졌어요

모듈마다 초기화하던 절차가 사라졌어요. Stove_Initialize 를 한 번 호출하면 결제 · 팝업 · PC방 · 로그 기능을 모두 사용할 수 있고, 종료할 때도 Stove_Uninitialize 하나만 호출해요.

함수 이름에서도 모듈 이름이 제거되었어요. 접두사는 Stove_ 하나로 통일되었어요.

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

구조체 대신 인터페이스 포인터를 사용해요

구 API는 값 구조체(StovePCUser 등)를 직접 선언해서 주고받았어요. 신규 API는 모든 객체를 IStove* 포인터로 다루고, 값은 접근자로 조회해요.

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

신규 API의 접근자는 C 함수와 C++ 메서드 두 가지 형태로 제공되며, 두 형태의 동작은 완전히 같아요. 프로젝트 환경에 맞는 형태를 선택하시면 돼요.

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

C 함수의 이름은 Stove_<인터페이스>_<멤버> 형태로 규칙이 일정해요. SDK 함수(Stove_GetUser 등)는 자유 함수이므로 두 형태에서 호출 방법이 같아요.

파라미터도 객체로 생성해요

호출에 전달하는 파라미터도 구조체를 선언하는 방식이 아니라 팩토리 패턴으로 생성해요. 어떤 파라미터를 생성할지는 EStove<모듈>TypeKind 값으로 지정해요.

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

전달받은 객체는 해제해야 해요

SDK가 생성한 객체는 사용을 마친 뒤에 해제해요. 해제해야 하는 객체인지는 ShouldDestroy 로 판단해요.

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

구 API에는 없던 규칙이므로 코드를 옮길 때 가장 자주 누락되는 부분이에요. 자세한 내용은 5장에서 설명해요.

C와 C++ 두 형태로 제공해요

헤더는 모듈마다 네 가지로 나뉘며, 전체를 한 줄로 포함할 수 있는 stove_api.h 도 함께 제공돼요. 단일 바이너리라서 모든 모듈의 헤더가 BaseSDK/Public/C/ 한 폴더에 함께 들어 있어요.

배포 패키지에는 파트너스 게임에서 쓸 수 없는 모듈의 헤더도 함께 들어 있어요. 소유권(ownership_*)과 통계·업적(game_support_*)은 스토어인디 게임 전용이에요. stove_api.h 로 한 번에 포함하면 이 헤더들도 따라 들어오지만, 파트너스 게임에서는 제공되지 않는 기능이니 호출하지 마세요. 헤더가 있다고 해서 쓸 수 있는 기능은 아니에요.

2. 함수 대응

초기화와 종료

모듈별 초기화 · 종료 · 버전 조회 함수는 신규 API에 없어요. 세 개의 함수로 통합되었어요.

사용자 정보와 환경

규제 대응 알림

결제

팝업

PC방

로그

3. 구조체와 열거형 대응

공통

사용자 정보와 환경

규제 대응 알림

결제

팝업

PC방과 로그

4. 신규 API에 없는 기능

다음 항목은 신규 C API에 대응하는 함수와 구조체가 없어요. 해당 기능을 사용하고 있다면 코드를 옮기기 전에 대체 방법을 먼저 결정해야 해요.

함수

구조체와 열거형

배포에는 들어 있지만 파트너스 게임에서 쓸 수 없는 함수

아래 함수는 신규 API에 있고 헤더에도 선언되어 있지만 스토어인디 게임 전용이에요. 파트너스 게임에는 제공되지 않으니 코드를 옮길 때 그냥 넘어가세요. 구 API에서도 이 기능은 파트너스 게임에 제공되지 않았어요.

stove_api.h 로 헤더를 한 번에 포함하면 위 함수의 선언도 따라 들어와요. 편집기 자동 완성 목록에 보이더라도 호출하지 마세요.

없어진 방식

• Ex · Ex2 확장 함수: 신규 API는 확장 함수를 별도로 제공하지 않아요. 기존 Ex 계열이 담당하던 기능, 즉 팝업이 닫힐 때 호출되는 콜백과 추가된 응답 필드, 확장된 파라미터는 모두 기본 함수 하나에 포함되어 있어요.
• 모듈별 초기화: 결제나 팝업 기능을 사용하기 위해 모듈을 개별적으로 초기화하던 절차가 없어졌어요.
• 모듈별 결과 코드: 모듈마다 존재하던 SDKResultCode 가 공통 코드와 기능별 코드 두 가지로 정리되었어요.

5. 코드를 변경할 때 달라지는 부분

이름만 바꾸면 빌드되지 않아요. 호출 형태가 함께 바뀌기 때문이에요. 다음 여섯 가지가 실제로 코드를 수정해야 하는 부분이에요.

5.1 동기 함수는 결과를 포인터로 반환해요

구 API는 Result 값을 반환했고, 결과 구조체는 호출하는 쪽에서 선언하여 주소를 전달했어요. 신규 API는 IStoveResult* 를 반환하고, 결과 객체는 이중 포인터로 전달받아요.

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

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

• 성공 여부는 IsSuccessful() 로 확인해요. try-catch 는 사용하지 않아요.
• 결과 코드는 GetResultCode() 로 확인하고, 어느 함수가 생성한 결과인지는 GetMethodCode() 로 확인해요.

5.2 전달받은 객체는 해제해요

구 API의 값 구조체는 범위를 벗어나면 자동으로 정리되었어요. 신규 API에서 SDK가 생성한 객체는 호출하는 쪽에서 해제해야 해요.

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

• 반환받은 IStoveResult* 는 해제해요.
• Stove_CreateParam() 으로 생성한 파라미터도 호출이 끝나면 해제해요.
• 콜백으로 전달받은 객체는 각 문서의 메모리 관리 표를 확인하세요. SDK가 소유하고 있어서 해제하면 안 되는 객체도 있어요.
• 문서에서 확인하기 어렵다면 위와 같이 ShouldDestroy 로 판단할 수 있어요.

5.3 파라미터는 팩토리 패턴으로 생성해요

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

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

IStoveResult* result = Stove_Initialize(initParam);
// 결과를 확인합니다.

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

Stove_CreateParam() 에 전달하는 값은 생성하려는 파라미터의 TypeKind 이에요. 어떤 값을 전달해야 하는지는 각 파라미터 문서에 기재되어 있어요.

5.4 초기화 흐름이 짧아져요

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

신규 C : Stove_RestartAppIfNecessary -> Stove_Initialize

• 모듈별 초기화 호출을 모두 제거해요. 남겨 두면 빌드되지 않아요.
• 종료할 때도 Stove_Uninitialize 를 한 번만 호출해요. 표기가 UnInitialize 에서 Uninitialize 로 바뀐 점에 주의하세요.
• Stove_Initialize 는 동기 함수예요. 완료 콜백을 기다리지 않고 반환값으로 성공 여부를 바로 확인해요.

5.5 콜백에 사용자 데이터 인자를 함께 넘겨요

비동기 함수는 콜백과 함께 void* userData 를 전달받아요. 콜백에서 게임 쪽 객체를 다시 찾아야 할 때 전역 변수 대신 이 값을 사용할 수 있어요.

구 C++ API(IAP_* · View_* 계열)에는 이 인자가 없어요. 다만 그보다 앞선 StoveAPI_* 벌에는 같은 방식이 있었으므로, StoveAPI_StartPurchaseEx 처럼 userData 를 넘기던 코드에서 옮겨 온다면 새로운 방식이 아니에요.

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

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

• SDK 함수는 자유 함수이므로 C 환경과 C++ 환경에서 선언이 같아요.
• 팝업을 여는 함수는 완료 콜백과 팝업이 닫힐 때 호출되는 콜백을 함께 전달받아요. 구 API에서 Ex 함수를 사용하던 부분이 여기에 해당해요.
• 닫힘 콜백이 필요하지 않으면 nullptr 을 전달해요.
• 콜백이 실행되는 시점은 이전과 같아요. Stove_RunCallback() 을 호출한 스레드에서 실행되므로 게임 루프에서 계속 호출해야 해요.

5.6 결과 코드 체계가 바뀌었어요

구 API는 모듈마다 SDKResultCode 를 별도로 두었어요. 신규 API는 두 가지로 정리되었어요.

• 값을 숫자로 비교하는 코드가 있다면 새 열거형과 하나씩 대조하세요. 같은 숫자가 다른 의미일 수 있어요.
• 열거형 값의 이름은 k_E<열거형><값> 형태예요. 성공은 k_EStoveCommonResultCode_Success 이에요.
• 사용자에게 안내 화면을 표시해야 하는 코드인지는 각 결과 코드 문서의 표에서 확인할 수 있어요.

6. 옮기는 순서

한 번에 전부 변경하기보다 다음 순서로 나누어 진행하면 중간에 동작을 확인하기 쉽어요.

1. 헤더와 링커 설정을 먼저 교체해요. 구 API 헤더를 제거하고 신규 API 헤더로 바꾸는 작업이며, 6.1절에서 자세히 설명해요.
2. 초기화와 종료를 변경해요. 모듈별 초기화를 제거하고 Stove_Initialize · Stove_Uninitialize 로 정리한 뒤에 게임이 실행되는지 확인해요.
3. 동기 조회 함수를 변경해요. Stove_GetUser · Stove_GetGds 처럼 값을 바로 반환받는 함수부터 옮기면서 객체를 해제하는 규칙에 익숙해져요.
4. 비동기 함수를 변경해요. 결제 · 팝업 · PC방처럼 콜백을 사용하는 기능을 옮겨요. Ex 함수를 사용하던 부분은 닫힘 콜백 인자로 정리해요.
5. 결과 코드 분기를 점검해요. 숫자로 비교하던 부분과 모듈별 코드를 사용하던 부분을 새 열거형으로 변경해요.
6. 배포 구성을 정리해요. 모듈별 파일을 제외하고 BaseSDK.dll 하나만 포함하도록 변경해요.
7. 4장을 다시 확인해요. 대체 방법이 필요한 기능이 남아 있는지 마지막으로 점검해요.

6.1 헤더 교체와 include 문 변경

구 API의 헤더는 배포 패키지의 Include 폴더에 모듈마다 하나씩 들어 있고, 열거형과 구조체, 콜백 선언은 Include/Misc 폴더에 들어 있어요. 신규 API의 헤더는 BaseSDK/Public/C 한 폴더에 모듈마다 네 종류씩 들어 있어요.

프로젝트 설정에서 구 API의 헤더 경로를 제거하고 신규 API의 헤더 경로를 포함 디렉터리에 추가한 뒤에, 소스의 include 문을 바꿔요.

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

가장 간단한 방법은 통합 헤더 한 줄로 바꾸는 것이에요. 모든 모듈의 네 종류 헤더가 함께 포함되므로 C 접근자도 바로 사용할 수 있어요.

// 신규: 통합 헤더 한 줄로 모든 모듈을 포함합니다.
#include "stove_api.h"

필요한 모듈만 선택해서 포함할 수도 있어요. 이때 C 환경에서 인터페이스 멤버에 접근하려면 <module>_flat_api.h 를 함께 포함해야 해요.

// 신규: 모듈을 선택해서 포함하는 경우
#include "base_api.h"
#include "base_flat_api.h"
#include "iap_api.h"
#include "iap_flat_api.h"
#include "view_api.h"
#include "view_flat_api.h"

• <module>_api.h 는 <module>_types.h 를, <module>_types.h 는 <module>_misc.h 를 포함해요. 따라서 열거형과 구조체 헤더를 따로 추가하지 않아도 돼요.
• C++ 메서드 형태만 사용한다면 <module>_flat_api.h 는 포함하지 않아도 돼요.
• 구 API의 Include/Misc 아래 헤더를 직접 포함하던 코드가 있다면 함께 제거해요. 신규 API에는 같은 이름의 헤더가 없어요.
• 링커의 추가 종속성에 모듈별 lib 파일을 나열해 두었다면 배포 패키지의 Lib 폴더 구성에 맞추어 정리해요. 게임과 함께 배포하는 바이너리는 BaseSDK.dll 하나예요.

부록. 결과 코드 대응표

구 API는 모듈마다 결과 코드를 따로 두어서 같은 번호가 모듈에 따라 다른 뜻이었어요. 예를 들어 80 은 공통 기능에서는 언어 미설정, 결제와 팝업에서는 UI 미초기화, 로그에서는 작업 디렉터리 생성 실패였어요. 신규 API는 번호 하나가 한 가지 뜻만 가지도록 정리했어요.

번호가 그대로인 코드

아래 코드는 번호가 바뀌지 않았어요. 이름 표기만 대문자 밑줄에서 파스칼 표기로 달라졌어요.

번호가 바뀐 코드

공통 기능(Base)

결제(IAP)

팝업(View)

로그(Log)

신규 API에는 반영되지 않은 구 API 코드

결과 코드는 IsSuccessful() 로 성공 여부를 먼저 확인하고, 실패일 때만 코드를 확인하세요. 번호를 그대로 비교하던 코드가 있다면 위 표로 하나씩 대조해야 해요.