次の方法で共有

Unity プロジェクトで GDK API の C# ラッパーを使用する

  • [アーティクル]

このトピックでは、API ラッパーを使用して、マネージド コードから Microsoft Game Development Kit (GDK) および Xbox サービス API を適切に呼び出す方法を理解します。

Microsoft Game Development Kit (GDK) API へのアクセス

GDK Unity パッケージをインポートすると、その機能が XGamingRuntime 名前空間で使用可能になります。 すべてのゲーム ランタイム API は、SDK クラスの静的メソッドを介して使用可能です。 すべての 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 Game Development Kit (GDK) と Xbox サービス API のリストを参照してください。

表記規則:

  • API 名は、可能な限り、それに相当する GDK に一致します。
  • 例外はありません。 エラーは、HRESULT 経由で伝達されます。
  • オブジェクト指向のカプセル化が適用されていないフラットな API サーフェス。
  • out パラメーターは、パラメーターを設定する API で使用されます。
  • Async メソッドでは、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 が呼び出された後 (つまり、SDK.XTaskQueueDispatch()) に、結果 callback が呼び出されます。 そのため、dispatch が 頻繁に呼び出される ことが重要です。理想的には、ゲームの更新ループ中に呼び出されます。
  • 結果 callback は、呼び出したスレッドdispatchで実行されます。

ネイティブ API とマネージド ラッパーの違いの例

ネイティブ API とマネージド ラッパーには、ごくわずかな違いがあります。 参照のため、次の 2 つの例で、マネージド コードとネイティブ コードで 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.
        }
    }
);

XblAchievementsUpdateAchievementAsync の例

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 サービス API (XSAPI) の初期化

参照のため、マネージド コードでの XSAPI の初期化を次に示します。 これはマネージド コードでの XSAPI 署名です。

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

マネージド コードでの XSAPI 呼び出しパターンの例を次に示します。

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

マネージド ラッパーの Microsoft Game Development Kit (GDK) API のリスト

GDK Unity パッケージ内のマネージド ラッパーには、次の Microsoft Game Development Kit (GDK) API が含まれます。 Microsoft Game Development Kit (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 のリスト

GDK Unity パッケージ内のマネージド ラッパーには、次の Xbox サービス API が含まれます。 Xbox サービス API の詳細については、「Xbox Live API リファレンス」を参照してください。

関連項目

PC 開発用に Unity で始める