Skip to main content

XGameSaveInitializeProviderAsync

以非同步方式提供並初始化 XGameSave 提供者控制代碼。

語法

參數

requestingUser   _In_
類型:XUserHandle
XBOX Live 使用者的控制代碼。 configurationId   _In_z_
類型:char*
服務設定識別碼 (SCID)。 syncOnDemand   _In_
類型:bool
為 true 時,syncOnDemand 只會在需要時從服務下載資料。裝置離線時無法運作。 設定為 true 可能會導致顯示同步進度 UI。 async   _In_
類型:XAsyncBlock*
包含非同步呼叫的資訊。這包括呼叫內容,以及對 XGameSaveInitializeProviderResult 函式的呼叫。

傳回值

類型:HRESULT 函式結果。

備註

必須先成功呼叫此函式,才能使用其他 XGameSave API。
XGameSave API 需要您的遊戲正確設定其遊戲識別碼和服務設定識別碼 (SCID)
才能運作。如需這些必要識別碼的詳細資訊,請參閱設定 XBOX Live 開發的沙箱。您的遊戲必須在 Partner Center 中啟用 XBOX Live。
如果您未正確設定 SCID 和遊戲識別碼,您的 XSaveGame API 呼叫將會失敗並傳回下列錯誤碼: E_GS_NO_ACCESS - 0x80830002 - 作業失敗,因為遊戲沒有容器儲存空間的存取權。 產生的 XGameSaveProviderHandle 可從 XGameSaveInitializeProviderResult 函式取得。這是您用來 存取 XGameSaveProvider 的控制代碼。 以 syncOnDemand 設為 true 呼叫此 API 時,從呼叫端的角度來看行為相同,但會造成 API 其餘部分的一些行為差異。SyncOnDemand XGameSaveProvider 只會在需要時從服務下載資料, 但這也伴隨著缺點:在此情況下任何容器作業都可能延遲, 而此延遲可能會導致向使用者顯示同步進度的 UX。使用下列任何方法都可能 強制同步: 另一個缺點是,如果裝置離線或有連線問題,就無法存取容器。 ##範例
遊戲無法混合使用 XGameSaveFiles 與 XGameSave。遊戲必須選擇要使用哪一個雲端存檔系統。 如果遊戲使用 XGameSaveFiles,之後又呼叫 XGameSaveInitializeProvider,將會發生錯誤並傳回 E_GS_PROVIDER_MISMATCH。同樣地,如果遊戲使用 XGameSave,之後又呼叫 XGameSaveFilesGetFolderWithUiAsync, 也會發生錯誤並傳回 E_GS_PROVIDER_MISMATCH。

需求

標頭: XGameSave.h 程式庫: xgameruntime.lib 支援的平台: Windows、XBOX One 系列主機和 XBOX Series 主機

概念文件

另請參閱

XGameSave
XGameSaveInitializeProviderResult
XGameSaveInitializeProvider
偵錯遊戲存檔
Last modified on October 6, 2026