Unity 프로젝트에서 GDK API에 C# 래퍼 사용

아티클
05/10/2023

API 래퍼를 사용하여 관리 코드에서 Microsoft GDK(게임 개발 키트) 및 Xbox 서비스 API를 올바르게 호출하는 방법을 이해하려면 이 항목을 사용하세요.

Microsoft GDK(게임 개발 키트) API에 액세스

GDK Unity 패키지를 가져온 후에는 XGamingRuntime 네임스페이스에서 해당 기능을 사용할 수 있습니다. SDK 클래스의 정적 메서드를 통해 모든 게임 런타임 API를 사용할 수 있습니다. 모든 Xbox 서비스 API는 SDK.XBL 클래스의 정적 메서드를 통해 사용할 수 있습니다. 다음 예에서는 이러한 가용성을 보여 줍니다.

using System;
 
// The namespace under which the "GDK" functionality is available.
using XGamingRuntime;
 
namespace TestGame
{
    static class Program
    {
        static void Main()
        {
            // All APIs are accessed through static methods on the SDK class.
            Int32 hr = SDK.XGameRuntimeInitialize();

            // All Xbox services APIs are accessed through static methods on the SDK.XBL class.
            Int32 hr = SDK.XBL.XblInitialize(SCID);
            ...
        }
    }
}

API 적용 범위 및 규칙

참고 항목

모든 API가 패키지를 통해 사용할 수 있는 것은 아닙니다. 이러한 API의 전체 목록은 이 항목 뒷부분에 나오는 Microsoft GDK(게임 개발 키트) 및 Xbox 서비스 API 목록을 참조하세요.

규칙:

API 이름은 가급적 해당하는 GDK와 일치합니다.
예외는 없습니다. 오류는 Hresult를 통해 전달됩니다.
개체 지향 캡슐화가 없는 플랫 API 표면입니다.
out 매개 변수는 매개 변수를 설정하는 API에서 사용됩니다.
비동기식 메서드는 callbacks을(를) 사용합니다. 자세한 내용은 다음 섹션을 참조하세요.

비동기식 프로그래밍 모델

모든 비동기 API는 callback을(를) 마지막 매개 변수로 사용합니다. 예는 다음과 같습니다.

using System;
using XGamingRuntime;
 
class SignInManager
{
    public void AddUser()
    {
        SDK.XUserAddAsync(XUserAddOptions.None, this.OnUserAddComplete);
    }
 
    private void OnUserAddComplete(Int32 hresult, XUserHandle userHandle)
    {
        // Check the result, and then do something with the handle.
    }
}

스레드 모델에 대한 정보는 다음과 같습니다.

비동기 메소드는 즉시 실행되며 스레드 풀의 사용 가능한 스레드에서 작업이 수행됩니다.
- 스레드 풀은 SDK.XGameRuntimeInitialize()에 호출이 이루어진 후 내부적으로 초기화됩니다.
- 스레드 풀 구성 옵션은 노출되지 않습니다.
dispatch이(가) 호출된 후 결과 callback이(가) 호출됩니다(즉, SDK.XTaskQueueDispatch()). 결과적으로 이상적으로는 게임의 업데이트 루프 동안 dispatch을(를) 자주 호출하는 것이 중요합니다.
callback 결과는 dispatch을(를) 호출한 스레드에서 실행됩니다.

기본 API와 관리되는 래퍼의 차이점 예제

기본 API와 관리되는 래퍼에는 최소의 차이가 있습니다. 참고로 다음 두 예제는 관리 코드와 기본 코드에서 XUserAddAsync 및 XblAchievementsUpdateAchievementAsync의 서명 및 호출 기능을 보여 줍니다.

XUserAddAsync 예제

XUserAddAsync의 기본 서명은 다음과 같습니다.

STDAPI XUserAddAsync(
    _In_ XUserAddOptions options,
    _Inout_ XAsyncBlock* async
    ) noexcept;

STDAPI XUserAddResult(
    _Inout_ XAsyncBlock* async,
    _Out_ XUserHandle* newUser
    ) noexcept;

XUserAddAsync의 관리 서명 위치:

public static void XGamingRuntime.SDK.XUserAddAsync(
    XUserAddOptions options, 
    XUserAddCompleted completionRoutine
);
public delegate void XUserAddCompleted(Int32 hresult, XUserHandle userHandle);

XUserAddAsync의 함수를 기본 코드로 호출하는 방법의 예는 다음과 같습니다.

auto asyncBlock = std::make_unique<XAsyncBlock>();
ZeroMemory(asyncBlock.get(), sizeof(*asyncBlock));
asyncBlock->queue = _queue;
asyncBlock->context = this;
asyncBlock->callback = [](XAsyncBlock* ab)
{
    auto asyncBlock = std::unique_ptr<XAsyncBlock>(ab);
    XUserHandle user;
    RETURN_IF_FAILED(XUserAddResult(ab, &user));
};

if (SUCCEEDED_LOG(XUserAddAsync(
    XUserAddOptions::AddDefaultUserAllowingUI,
    asyncBlock.get())))
{
    // The call succeeded, so release the std::unique_ptr ownership of XAsyncBlock* because the callback will take over ownership.
    // If the call fails, the std::unique_ptr will keep ownership and delete the XAsyncBlock*
    asyncBlock.release();
}

XUserAddAsync 함수를 호출하는 관리되는 예제는 다음과 같습니다.

Managed add user
SDK.XUserAddAsync(
    XUserAddOptions.AddDefaultUserAllowingUI, 
    (hr, userHandle) =>
    {
        LOG("XUserAddAsync", hr);
        if (hr >= 0)
        {
            this.userHandle = userHandle;
            // Sign-in succeeded.
        }
        else
        {
            // Sign-in failed.
        }
    }
);

XblAccessUpdateAccessIvementAsync 예제

XblAchievementsUpdateAchievementAsync의 기본 서명은 다음과 같습니다.

STDAPI XblAchievementsUpdateAchievementAsync(
    _In_ XblContextHandle xboxLiveContext,
    _In_ uint64_t xboxUserId,
    _In_z_ const char* achievementId,
    _In_ uint32_t percentComplete,
    _In_ XAsyncBlock* async
) XBL_NOEXCEPT;

XblAchievementsUpdateAchievementAsync의 관리 서명 위치:

public static void XGamingRuntime.SDK.XBL.XblAchievementsUpdateAchievementAsync(
    XblContextHandle xboxLiveContext,
    UInt64 xboxUserId,
    string achievementId,
    UInt32 percentComplete,
    XblAchievementsUpdateAchievementResult completionRoutine);
public delegate void XblAchievementsUpdateAchievementResult(Int32 hresult);

XblAchievementsUpdateAchievementAsync의 함수를 기본 코드로 호출하는 방법의 예는 다음과 같습니다.

auto asyncBlock = std::make_unique<XAsyncBlock>();
asyncBlock->queue = Data()->queue;
asyncBlock->context = nullptr;
asyncBlock->callback = [](XAsyncBlock* asyncBlock)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ asyncBlock }; // Take over ownership of the XAsyncBlock*
    auto result = XAsyncGetStatus(asyncBlock, false);
    if (SUCCEEDED(result))
    {
        // Achievement updated.
    }
    else if (result == HTTP_E_STATUS_NOT_MODIFIED)
    {
        // Achievement isn't modified.
    }
    else
    {
        // Achievement failed to update.
    }
};

HRESULT hr = XblAchievementsUpdateAchievementAsync(
    Data()->xboxLiveContext,
    Data()->xboxUserId,
    achievementId.c_str(),
    percentComplete,
    asyncBlock.get()
);
if (SUCCEEDED(hr))
{
    // The call succeeded, so release the std::unique_ptr ownership of XAsyncBlock* because the callback will take over ownership.
    // If the call fails, the std::unique_ptr will keep ownership and delete the XAsyn-cBlock*
    asyncBlock.release();
}

XblAchievementsUpdateAchievementAsync 함수를 호출하는 관리 예제는 다음과 같습니다.

SDK.XBL.XblAchievementsUpdateAchievementAsync(
    xblContextHandle, 
    xboxUserId, 
    achievementId,
    percentComplete
    (achievementUpdateResult) => {
        LOG("XblAchievementsUpdateAchievementAsync result", achievementUpdateResult);
        if (achievementUpdateResult == 0)
        {
       	 	//  Achievement updated.
       	}
        else if (achievementUpdateResult == HTTP_E_STATUS_NOT_MODIFIED) //  0x80190130
        {
       		//  Achievement isn't modified.
       	}
        else
        {
       		//  Achievement failed to update.
       	}
    }
);

관리 코드에서 Xbox Services API(XSAPI) 초기화

참고로, 다음은 관리 코드에서 XS API의 초기화 작업입니다. 관리 코드의 XSAPI 서명입니다.

public static Int32 XGamingRuntime.SDK.XBL.XblInitialize(string scid)

다음은 관리 코드에서 XSAPI 호출 패턴의 예입니다.

Int32 hresult = SDK.XBL.XblInitialize(SCID);

관리되는 래퍼의 Microsoft GDK(게임 개발 키트) API 목록

다음 Microsoft GDK(게임 개발 키트) API는 GDK Unity 패키지 내의 관리되는 래퍼에 포함되어 있습니다. Microsoft GDK(게임 개발 키트) API에 대한 자세한 내용은 시스템 API 참조를 참조하세요.

XAccessibility
- XClosedCaptionGetProperties
- XClosedCaptionSetEnabled
- XHighContrastGetMode
- XSpeechToTextSendString
- XSpeechToTextSetPositionHint
- XSpeechToTextBeginHypothesisString
- XSpeechToTextUpdateHypothesisString
- XSpeechToTextFinalizeHypothesisString
- XSpeechToTextCancelHypothesisString
XGame
- XGameGetXboxTitleId
XGameInvite
- XGameInviteRegisterForEvent
- XGameInviteUnregisterForEvent
XGameSave
- XGameSaveInitializeProvider
- XGameSaveInitializeProviderAsync
- XGameSaveCloseProvider
- XGameSaveGetRemainingQuota
- XGameSaveGetRemainingQuotaAsync
- XGameSaveDeleteContainer
- XGameSaveDeleteContainerAsync
- XGameSaveCreateContainer
- XGameSaveCloseContainer
- XGameSaveGetContainerInfo
- XGameSaveEnumerateContainerInfo
- XGameSaveEnumerateContainerInfoByName
- XGameSaveEnumerateBlobInfo
- XGameSaveEnumerateBlobInfoByName
- XGameSaveReadBlobData
- XGameSaveReadBlobDataAsync
- XGameSaveCreateUpdate
- XGameSaveCloseUpdateHandle
- XGameSaveSubmitBlobWrite
- XGameSaveSubmitBlobDelete
- XGameSaveSubmitUpdate
- XGameSaveSubmitUpdateAsync
XGameUI
- XGameUiShowAchievementsAsync
- XGameUiShowMessageDialogAsync
- XGameUiShowErrorDialogAsync
- XGameUiShowTextEntryAsync
- XGameUiSetNotificationPositionHint
- XGameUiShowSendGameInviteAsync
- XGameUIShowWebAuthenticationAsync
- XGameUiShowPlayerProfileCardAsync
- XGameUiShowPlayerPickerAsync
XLauncher
- XLaunchUri
XPackage
- XPackageGetCurrentProcessPackageIdentifier
- XPackageIsPackagedProcess
- XPackageGetUserLocale
- XPackageEnumeratePackages
- XPackageRegisterPackageInstalled
- XPackageUnregisterPackageInstalled
- XPackageEnumerateFeatures
- XPackageMount
- XPackageGetMountPath
- XPackageCloseMountHandle
- XPackageCreateInstallationMonitor
- XPackageCloseInstallationMonitorHandle
- XPackageGetInstallationProgress
- XPackageUpdateInstallationMonitor
- XPackageRegisterInstallationProgressChanged
- XPackageUnregisterInstallationProgressChanged
- XPackageEstimateDownloadSize
- XPackageGetWriteStats
- XPackageUninstallUWPInstance
XStore
- XStoreCreateContext
- XStoreCloseContextHandle
- XStoreIsAvailabilityPurchasable
- XStoreAcquireLicenseForPackageAsync
- XStoreCanAcquireLicenseForPackageAsync
- XStoreCanAcquireLicenseForStoreIdAsync
- XStoreCloseLicenseHandle
- XStoreIsLicenseValid
- XStoreQueryAddOnLicensesAsync
- XStoreQueryGameLicenseAsync
- XStoreQueryLicenseTokenAsync
- XStoreRegisterGameLicenseChanged
- XStoreRegisterPackageLicenseLost
- XStoreUnregisterGameLicenseChanged
- XStoreUnregisterPackageLicenseLost
- XStoreAcquireLicenseForDurablesAsync
- XStoreQueryGameAndDlcPackageUpdatesAsync
- XStoreDownloadAndInstallPackagesAsync
- XStoreDownloadAndInstallPackageUpdatesAsync
- XStoreDownloadPackageUpdatesAsync
- XStoreQueryPackageIdentifier
- XStoreShowRedeemTokenUIAsync
- XStoreShowRateAndReviewUIAsync
- XStoreShowPurchaseUIAsync
- XStoreQueryConsumableBalanceRemainingAsync
- XStoreReportConsumableFulfillmentAsync
- XStoreGetUserCollectionsIdAsync
- XStoreGetUserPurchaseIdAsync
- XStoreQueryAssociatedProductsAsync
- XStoreQueryEntitledProductsAsync
- XStoreQueryProductForCurrentGameAsync
- XStoreQueryProductForPackageAsync
- XStoreQueryProductsAsync
- XStoreProductsQueryNextPageAsync
- XStoreCloseProductsQueryHandle
XThread
- XThreadIsTimeSensitive
- XThreadSetTimeSensitive
- XThreadAssertNotTimeSensitive
XUser
- XUserDuplicateHandle
- XUserCloseHandle
- XUserCompare
- XUserGetMaxUsers
- XUserAddAsync
- XUserGetId
- XUserFindUserById
- XUserGetLocalId
- XUserFindUserByLocalId
- XUserGetIsGuest
- XUserGetState
- XUserGetGamertag
- XUserGetGamerPictureAsync
- XUserGetAgeGroup
- XUserCheckPrivilege
- XUserResolvePrivilegeWithUiAsync
- XUserGetTokenAndSignatureUtf16Async
- XUserResolveIssueWithUiUtf16Async
- XUserRegisterForChangeEvent
- XUserUnregisterForChangeEvent
- XUserCloseSignOutDeferralHandle

관리되는 래퍼의 Xbox 서비스 API 목록

다음 Xbox 서비스 API는 GDK Unity 패키지 내의 관리되는 래퍼에 포함되어 있습니다. Xbox 서비스 API에 대한 자세한 내용은 Xbox Live API 참조를 참조하세요.

참고 항목

PC 개발용 Unity 시작하기

다음을 통해 공유

Unity 프로젝트에서 GDK API에 C# 래퍼 사용

Microsoft GDK(게임 개발 키트) API에 액세스

API 적용 범위 및 규칙

비동기식 프로그래밍 모델

기본 API와 관리되는 래퍼의 차이점 예제

XUserAddAsync 예제

XblAccessUpdateAccessIvementAsync 예제

관리 코드에서 Xbox Services API(XSAPI) 초기화

관리되는 래퍼의 Microsoft GDK(게임 개발 키트) API 목록

관리되는 래퍼의 Xbox 서비스 API 목록

참고 항목

추가 리소스