面向 GDK 的 Unity C# API 包装器

​

访问 Microsoft Game Development Kit(GDK)API

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 名称在可行的情况下与对应的 GDK 保持一致。
• 不使用异常。错误通过 HRESULT 反馈。
• API 表面扁平,没有面向对象封装。
• 用 out 参数返回结果的 API。
• 异步方法使用回调。详情参见下一节。

​

异步编程模型

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())。因此务必 频繁调用 dispatch,理想情况下在游戏的 update 循环中调用。
• 结果回调运行在调用 dispatch 的线程上。

​

原生 API 与托管包装器的差异示例

​

XUserAddAsync 示例

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

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

public static void XGamingRuntime.SDK.XUserAddAsync(
    XUserAddOptions options,
    XUserAddCompleted completionRoutine
);

public delegate void XUserAddCompleted(Int32 hresult, XUserHandle userHandle);

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

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

XAsyncBlock xAsyncBlock = new XAsyncBlock(queue, (_async) =>
{
    XUserHandle userHandle;
    int hr = SDK.XUserAddResult(_async, out userHandle);

    if (hr >= 0)
    {
        this.userHandle = userHandle;
        // Sign-in succeeded.
    }
    else
    {
        // Sign-in failed.
    }
}, IntPtr.Zero);

SDK.XUserAddAsync(XUserAddOptions.AddDefaultUserAllowingUI, xAsyncBlock);

​

XblAchievementsUpdateAchievementAsync 示例

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

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

public delegate void XblAchievementsUpdateAchievementResult(Int32 hresult);

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

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)

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

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

​

托管包装器中包含的 Microsoft Game Development Kit(GDK)API 列表

• XAccessibility
  • XClosedCaptionGetProperties
  • XClosedCaptionSetEnabled
  • XHighContrastGetMode
  • XSpeechToTextSendString
  • XSpeechToTextSetPositionHint
  • XSpeechToTextBeginHypothesisString
  • XSpeechToTextUpdateHypothesisString
  • XSpeechToTextFinalizeHypothesisString
  • XSpeechToTextCancelHypothesisString
• XAppCapture
  • XAppBroadcastGetStatus
  • XAppBroadcastIsAppBroadcasting
  • XAppBroadcastShowUI
  • XAppBroadcastRegisterIsAppBroadcastingChanged
  • XAppCaptureCloseLocalStream
  • XAppCaptureCloseScreenshotStream
  • XAppCaptureEnableRecord
  • XAppCaptureDisableRecord
  • XAppBroadcastUnregisterIsAppBroadcastingChanged
  • XAppCaptureMetadataAddStringEvent
  • XAppCaptureMetadataAddInt32Event
  • XAppCaptureMetadataAddDoubleEvent
  • XAppCaptureMetadataStartStringState
  • XAppCaptureMetadataStartInt32State
  • XAppCaptureMetadataStartDoubleState
  • XAppCaptureMetadataStopState
  • XAppCaptureMetadataStopAllStates
  • XAppCaptureMetadataRemainingStorageBytesAvailable
  • XAppCaptureOpenScreenshotStream
  • XAppCaptureReadScreenshotStream
  • XAppCaptureRecordDiagnosticClip
  • XAppCaptureTakeDiagnosticScreenshot
  • XAppCaptureTakeScreenshot
  • XAppCaptureRegisterMetadataPurged
  • XAppCaptureUnRegisterMetadataPurged
  • XAppCaptureReadLocalStream
  • XAppCaptureRecordTimespan
  • XAppCaptureGetVideoCaptureSettings
• XAsync
  • XAsyncGetStatus
  • XAsyncGetResultSize
  • XAsyncCancel
  • XAsyncRun
• XDisplay
  • XDisplayTryEnableHdrMode
  • XDisplayAcquireTimeoutDeferral
  • XDisplayCloseTimeoutDeferralHandle
• XError
  • XErrorSetCallback
  • XErrorSetOptions
• XGameEvent
  • XGameEventWrite
• XGame
  • XGameGetXboxTitleId
  • XLaunchNewGame
  • XLaunchRestartOnCrash
• XGameInvite
  • XGameInviteRegisterForEvent
  • XGameInviteUnregisterForEvent
• XGameProtocol
  • XGameProtocolRegisterForActivation
  • XGameProtocolUnregisterForActivation
• XGameRuntimeFeature
  • XGameRuntimeIsFeatureAvailable
• XGameRuntimeInit
  • XGameRuntimeInitialize
  • XGameRuntimeUninitialize
• XGameSave
  • XGameSaveInitializeProvider
  • XGameSaveInitializeProviderAsync
  • XGameSaveInitializeProviderResult
  • XGameSaveCloseProvider
  • XGameSaveGetRemainingQuota
  • XGameSaveGetRemainingQuotaAsync
  • XGameSaveGetRemainingQuotaResult
  • XGameSaveDeleteContainer
  • XGameSaveDeleteContainerAsync
  • XGameSaveDeleteContainerResult
  • XGameSaveCreateContainer
  • XGameSaveCloseContainer
  • XGameSaveGetContainerInfo
  • XGameSaveEnumerateContainerInfo
  • XGameSaveEnumerateContainerInfoByName
  • XGameSaveEnumerateBlobInfo
  • XGameSaveEnumerateBlobInfoByName
  • XGameSaveReadBlobData
  • XGameSaveReadBlobDataAsync
  • XGameSaveReadBlobDataResult
  • XGameSaveCreateUpdate
  • XGameSaveCloseUpdateHandle
  • XGameSaveSubmitBlobWrite
  • XGameSaveSubmitBlobDelete
  • XGameSaveSubmitUpdate
  • XGameSaveSubmitUpdateAsync
  • XGameSaveSubmitUpdateResult
• XGameSaveFiles
  • XGameSaveFilesGetFolderWithUiAsync
  • XGameSaveFilesGetFolderWithUiResult
  • XGameSaveFilesGetRemainingQuota
• XGameStreaming
  • XGameStreamingInitialize
  • XGameStreamingUninitialize
  • XGameStreamingIsStreaming
  • XGameStreamingGetClientCount
  • XGameStreamingGetClients
  • XGameStreamingGetConnectionState
  • XGameStreamingRegisterConnectionStateChanged
  • XGameStreamingUnregisterConnectionStateChanged
  • XGameStreamingHideTouchControls
  • XGameStreamingHideTouchControlsOnClient
  • XGameStreamingShowTouchControlLayout
  • XGameStreamingShowTouchControlLayoutOnClient
  • XGameStreamingRegisterClientPropertiesChanged
  • XGameStreamingUnregisterClientPropertiesChanged
  • XGameStreamingGetStreamPhysicalDimensions
  • XGameStreamingGetStreamAddedLatency
  • XGameStreamingGetServerLocationNameSize
  • XGameStreamingGetServerLocationName
  • XGameStreamingIsTouchInputEnabled
  • XGameStreamingGetLastFrameDisplayed
  • XGameStreamingUpdateTouchControlsState
  • XGameStreamingUpdateTouchControlsStateOnClient
  • XGameStreamingShowTouchControlsWithStateUpdate
  • XGameStreamingShowTouchControlsWithStateUpdateOnClient
  • XGameStreamingGetTouchBundleVersionNameSize
  • XGameStreamingGetTouchBundleVersion
  • XGameStreamingGetClientIPAddress
  • XGameStreamingGetSessionId
  • XGameStreamingGetDisplayDetails
  • XGameStreamingSetResolution
• XGameUI
  • XGameUIShowAchievementsAsync
  • XGameUIShowAchievementsResult
  • XGameUIShowMessageDialogAsync
  • XGameUIShowMessageDialogResult
  • XGameUIShowErrorDialogAsync
  • XGameUIShowErrorDialogResult
  • XGameUIShowTextEntryAsync
  • XGameUIShowTextEntryResultSize
  • XGameUIShowTextEntryResult
  • XGameUITextEntryClose
  • XGameUITextEntryGetExtents
  • XGameUITextEntryOpen
  • XGameUITextEntryGetState
  • XGameUITextEntryUpdatePositionHint
  • XGameUITextEntryUpdateVisibility
  • XGameUISetNotificationPositionHint
  • XGameUIShowSendGameInviteAsync
  • XGameUIShowSendGameInviteResult
  • XGameUIShowMultiplayerActivityGameInviteAsync
  • XGameUIShowMultiplayerActivityGameInviteResult
  • XGameUIShowWebAuthenticationAsync
  • XGameUIShowWebAuthenticationResult
  • XGameUIShowWebAuthenticationWithOptionsAsync
  • XGameUIShowWebAuthenticationResultSize
  • XGameUIShowPlayerProfileCardAsync
  • XGameUIShowPlayerProfileCardResult
  • XGameUIShowPlayerPickerAsync
  • XGameUIShowPlayerPickerResultCount
  • XGameUIShowPlayerPickerResult
• XLauncher
  • XLaunchUri
• XNetworking
  • XNetworkingGetConnectivityHint
  • XNetworkingQueryConfigurationSetting
  • XNetworkingQueryPreferredLocalUdpMultiplayerPort
  • XNetworkingQueryPreferredLocalUdpMultiplayerPortAsync
  • XNetworkingQueryPreferredLocalUdpMultiplayerPortAsyncResult
  • XNetworkingQuerySecurityInformationForUrlAsync
  • XNetworkingQuerySecurityInformationForUrlAsyncResultSize
  • XNetworkingQuerySecurityInformationForUrlAsyncResult
  • XNetworkingQuerySecurityInformationForUrlUtf16Async
  • XNetworkingQuerySecurityInformationForUrlUtf16AsyncResultSize
  • XNetworkingQuerySecurityInformationForUrlUtf16AsyncResult
  • XNetworkingQueryStatistics
  • XNetworkingRegisterConnectivityHintChanged
  • XNetworkingUnregisterConnectivityHintChanged
  • XNetworkingRegisterPreferredLocalUdpMultiplayerPortChanged
  • XNetworkingUnregisterPreferredLocalUdpMultiplayerPortChanged
  • XNetworkingVerifyServerCertificate
• XPackage
  • XPackageGetCurrentProcessPackageIdentifier
  • XPackageIsPackagedProcess
  • XPackageGetUserLocale
  • XPackageEnumeratePackages
  • XPackageFindChunkAvailability
  • XPackageChangeChunkInstallOrder
  • XPackageInstallChunks
  • XPackageUninstallChunks
  • XPackageInstallChunksAsync
  • XPackageInstallChunksResult
  • XPackageRegisterPackageInstalled
  • XPackageUnregisterPackageInstalled
  • XPackageEnumerateFeatures
  • XPackageEnumerateChunkAvailability
  • XPackageMount
  • XPackageMountWithUiAsync
  • XPackageMountWithUiResult
  • XPackageGetMountPath
  • XPackageGetMountPathSize
  • XPackageCloseMountHandle
  • XPackageCreateInstallationMonitor
  • XPackageCloseInstallationMonitorHandle
  • XPackageGetInstallationProgress
  • XPackageUpdateInstallationMonitor
  • XPackageRegisterInstallationProgressChanged
  • XPackageUnregisterInstallationProgressChanged
  • XPackageEstimateDownloadSize
  • XPackageGetWriteStats
  • XPackageUninstallUWPInstance
  • XPackageUninstallPackage
• XPersistentLocalStorage
  • XPersistentLocalStorageGetPathSize
  • XPersistentLocalStorageGetPath
  • XPersistentLocalStorageGetSpaceInfo
  • XPersistentLocalStoragePromptUserForSpaceAsync
  • XPersistentLocalStoragePromptUserForSpaceResult
• XSpeechSynthesizer
  • XSpeechSynthesizerEnumerateInstalledVoices
  • XSpeechSynthesizerCreate
  • XSpeechSynthesizerCloseHandle
  • XSpeechSynthesizerSetDefaultVoice
  • XSpeechSynthesizerSetCustomVoice
  • XSpeechSynthesizerCreateStreamFromText
  • XSpeechSynthesizerCreateStreamFromSsml
  • XSpeechSynthesizerCloseStreamHandle
  • XSpeechSynthesizerGetStreamDataSize
  • XSpeechSynthesizerGetStreamData
• XStore
  • XStoreCreateContext
  • XStoreCloseContextHandle
  • XStoreIsAvailabilityPurchasable
  • XStoreAcquireLicenseForPackageAsync
  • XStoreAcquireLicenseForPackageResult
  • XStoreCanAcquireLicenseForPackageAsync
  • XStoreCanAcquireLicenseForPackageResult
  • XStoreCanAcquireLicenseForStoreIdAsync
  • XStoreCanAcquireLicenseForStoreIdResult
  • XStoreCloseLicenseHandle
  • XStoreIsLicenseValid
  • XStoreQueryAddOnLicensesAsync
  • XStoreQueryAddOnLicensesResultCount
  • XStoreQueryAddOnLicensesResult
  • XStoreQueryGameLicenseAsync
  • XStoreQueryGameLicenseResult
  • XStoreQueryLicenseTokenAsync
  • XStoreQueryLicenseTokenResultSize
  • XStoreQueryLicenseTokenResult
  • XStoreRegisterGameLicenseChanged
  • XStoreUnregisterGameLicenseChanged
  • XStoreRegisterPackageLicenseLost
  • XStoreUnregisterGameLicenseChanged
  • XStoreUnregisterPackageLicenseLost
  • XStoreAcquireLicenseForDurablesAsync
  • XStoreQueryGameAndDlcPackageUpdatesAsync
  • XStoreQueryGameAndDlcPackageUpdatesResultCount
  • XStoreQueryGameAndDlcPackageUpdatesResult
  • XStoreDownloadAndInstallPackagesAsync
  • XStoreDownloadAndInstallPackagesResultCount
  • XStoreDownloadAndInstallPackagesResult
  • XStoreDownloadAndInstallPackageUpdatesAsync
  • XStoreDownloadAndInstallPackageUpdatesResult
  • XStoreDownloadPackageUpdatesAsync
  • XStoreDownloadPackageUpdatesResult
  • XStoreQueryPackageIdentifier
  • XStoreShowRedeemTokenUIAsync
  • XStoreShowRedeemTokenUIResult
  • XStoreShowRateAndReviewUIAsync
  • XStoreShowRateAndReviewUIResult
  • XStoreShowPurchaseUIAsync
  • XStoreShowPurchaseUIResult
  • XStoreQueryConsumableBalanceRemainingAsync
  • XStoreQueryConsumableBalanceRemainingResult
  • XStoreReportConsumableFulfillmentAsync
  • XStoreReportConsumableFulfillmentResult
  • XStoreGetUserCollectionsIdAsync
  • XStoreGetUserCollectionsIdResultSize
  • XStoreGetUserCollectionsIdResult
  • XStoreGetUserPurchaseIdAsync
  • XStoreGetUserPurchaseIdResultSize
  • XStoreGetUserPurchaseIdResult
  • XStoreQueryAssociatedProductsAsync
  • XStoreQueryAssociatedProductsResult
  • XStoreQueryEntitledProductsAsync
  • XStoreQueryEntitledProductsResult
  • XStoreQueryProductForCurrentGameAsync
  • XStoreQueryProductForCurrentGameResult
  • XStoreQueryProductForPackageAsync
  • XStoreQueryProductForPackageResult
  • XStoreQueryProductsAsync
  • XStoreQueryProductsResult
  • XStoreProductsQueryNextPageAsync
  • XStoreCloseProductsQueryHandle
  • XStoreAcquireLicenseForDurablesResult
  • XStoreEnumerateProductsQuery
  • XStoreProductsQueryHasMorePages
  • XStoreProductsQueryNextPageResult
  • XStoreShowAssociatedProductsUIAsync
  • XStoreShowAssociatedProductsUIResult
  • XStoreShowProductPageUIAsync
  • XStoreShowProductPageUIResult
• XSystem
  • XSystemGetAnalyticsInfo
  • XSystemGetAppSpecificDeviceId
  • XSystemGetConsoleId
  • XSystemGetDeviceType
  • XSystemGetXboxLiveSandboxId
  • XSystemGetRuntimeInfo
  • XSystemIsHandleValid
  • XSystemHandleTrack
• XTaskQueue
  • XTaskQueueCloseHandle
  • XTaskQueueCreate
  • XTaskQueueCreateComposite
  • XTaskQueueDispatch
  • XTaskQueueDuplicateHandle
  • XTaskQueueGetCurrentProcessTaskQueue
  • XTaskQueueGetPort
  • XTaskQueueRegisterMonitor
  • XTaskQueueRegisterWaiter
  • XTaskQueueSetCurrentProcessTaskQueue
  • XTaskQueueSubmitCallback
  • XTaskQueueSubmitDelayedCallback
  • XTaskQueueTerminate
  • XTaskQueueUnregisterMonitor
  • XTaskQueueUnregisterWaiter
• XThread
  • XThreadIsTimeSensitive
  • XThreadSetTimeSensitive
  • XThreadAssertNotTimeSensitive
• XUser
  • XUserDuplicateHandle
  • XUserCloseHandle
  • XUserCompare
  • XUserGetMaxUsers
  • XUserAddAsync
  • XUserAddResult
  • XUserAddByIdWithUiAsync
  • XUserAddByIdWithUiResult
  • XUserGetId
  • XUserFindUserById
  • XUserGetLocalId
  • XUserFindUserByLocalId
  • XUserGetIsGuest
  • XUserGetState
  • XUserGetGamertag
  • XUserGetGamerPictureAsync
  • XUserGetAgeGroup
  • XUserCheckPrivilege
  • XUserResolvePrivilegeWithUiAsync
  • XUserResolvePrivilegeWithUiResult
  • XUserGetTokenAndSignatureUtf16Async
  • XUserResolveIssueWithUiUtf16Async
  • XUserResolveIssueWithUiUtf16Result
  • XUserRegisterForChangeEvent
  • XUserUnregisterForChangeEvent
  • XUserCloseSignOutDeferralHandle
  • XUserFindControllerForUserWithUiAsync
  • XUserFindControllerForUserWithUiResult
  • XUserFindForDevice
  • XUserGetDefaultAudioEndpointUtf16
  • XUserGetGamerPictureResultSize
  • XUserGetGamerPictureResult
  • XUserGetSignOutDeferral
  • XUserGetTokenAndSignatureAsync
  • XUserGetTokenAndSignatureResultSize
  • XUserGetTokenAndSignatureResult
  • XUserGetTokenAndSignatureUtf16ResultSize
  • XUserGetTokenAndSignatureUtf16Result
  • XUserIsStoreUser
  • XUserRegisterForDefaultAudioEndpointUtf16Changed
  • XUserRegisterForDeviceAssociationChanged
  • XUserResolveIssueWithUiAsync
  • XUserResolveIssueWithUiResult
  • XUserUnregisterForDefaultAudioEndpointUtf16Changed
  • XUserUnregisterForDeviceAssociationChanged

​

托管包装器中包含的 XBOX 服务 API 列表

• XblContext
• XblAchievements
• XblEvents
• XblLeaderboard
• XblPresence
• XblPrivacy
• XblSocialManager
• XblUserStatistics
• XblHttpCall
• XblGetErrorCondition
• XblMultiplayer
• XblMultiplayerManager
• XblMultiplayerActivity
• XblMatchmaking
• XblProfile
• XblRealTimeActivity
• XblTitleManagedStats
• XblSocial
• XblTitleStorage
• XblUserStatics

​

参考 API 文档

• XStore(API 内容)
• XPackage(API 内容)

​

参见