> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XGameSaveInitializeProvider

> XGameSaveInitializeProvider

# XGameSaveInitializeProvider

提供並初始化 XGameSave 提供者控制代碼。

## 語法

```cpp theme={null}
HRESULT XGameSaveInitializeProvider(  
         XUserHandle requestingUser,  
         const char* configurationId,  
         bool syncOnDemand,  
         XGameSaveProviderHandle* provider  
)  
```

### 參數

*requestingUser*   \_In\_\
類型：XUserHandle

XBOX Live 使用者的控制代碼。

*configurationId*   \_In\_z\_\
類型：char\*

服務設定識別碼 (SCID)。

*syncOnDemand*   \_In\_\
類型：bool

為 true 時，syncOnDemand 只會在需要時從服務下載資料。裝置離線時無法運作。
設定為 true 可能會導致顯示同步進度 UI。

*provider*   \_Outptr\_result\_nullonfailure\_\
類型：XGameSaveProviderHandle\*

要建立之 XGameSave 提供者的控制代碼。

### 傳回值

類型：HRESULT

函式結果。

#### 常見錯誤

* E\_GS\_USER\_CANCELED
* E\_GS\_USER\_NOT\_REGISTERED\_IN\_SERVICE
* E\_GS\_NO\_ACCESS
* E\_GS\_NO\_SERVICE\_CONFIGURATION

最常傳回的錯誤為 E\_OUTOFMEMORY、E\_INVALIDARG、

## 備註

<Note>在時間敏感執行緒上呼叫此函式並不安全。如需詳細資訊，請參閱[時間敏感執行緒](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)。</Note>

必須先成功呼叫此函式，才能使用其他 XGameSave API。不應在遊戲的 UI 執行緒上呼叫此函式，
因為它在同步處理玩家的遊戲存檔時可能會封鎖，並可能向使用者顯示 UI。
如果您需要從 UI 執行緒初始化，請考慮呼叫
[XGameSaveInitializeProviderAsync](/zh-TW/reference/system/xgamesave/functions/xgamesaveinitializeproviderasync)。

<Note>XGameSave API 需要您的遊戲正確設定其遊戲識別碼和服務設定識別碼 (SCID)</Note>
才能運作。如需這些必要識別碼的詳細資訊，請參閱[設定 XBOX
Live 開發的沙箱](/zh-TW/services/xbox-services/fundamentals/sandboxes/live-setting-up-sandboxes)。您的遊戲必須在 Partner Center 中啟用 XBOX Live。

如果您未正確設定 SCID 和遊戲識別碼，您的 XSaveGame API 呼叫將會失敗並傳回下列錯誤碼：

E\_GS\_NO\_ACCESS - 0x80830002 - 作業失敗，因為遊戲沒有容器儲存空間的存取權。

以 *syncOnDemand* 設為 true 呼叫此 API 時，從呼叫端的角度來看行為相同，但會造成
API 其餘部分的一些行為差異。*SyncOnDemand* **XGameSaveProvider** 只會在需要時從服務下載資料，
但這也伴隨著缺點：在此情況下任何容器作業都可能延遲，
而此延遲可能會導致向使用者顯示同步進度的 UX。使用下列任何方法都可能
強制同步：

* [XGameSaveCreateUpdate](/zh-TW/reference/system/xgamesave/functions/xgamesavecreateupdate)
* [XGameSaveEnumeratorBlobInfo](/zh-TW/reference/system/xgamesave/functions/xgamesaveenumerateblobinfo)
* [XGameSaveEnumerateBlobInfoByName](/zh-TW/reference/system/xgamesave/functions/xgamesaveenumerateblobinfobyname)
* [XGameSaveEnumerateContainerInfo](/zh-TW/reference/system/xgamesave/functions/xgamesaveenumeratecontainerinfo)
* [XGameSaveEnumerateContainerInfoByName](/zh-TW/reference/system/xgamesave/functions/xgamesaveenumeratecontainerinfobyname)

另一個缺點是，如果裝置離線或有連線問題，就無法存取容器。
此函式有一個非同步版本，稱為
[XGameSaveInitializeProviderAsync](/zh-TW/reference/system/xgamesave/functions/xgamesaveinitializeproviderasync)

```cpp theme={null}
// SYNC Init - should not be called on time sensitive thread 
//             as this will block until the operation is complete 
void Sample::_InitializeSync() 
{ 
    HRESULT hr; 
    XGameSaveProviderHandle provider = nullptr; 
    hr = XGameSaveInitializeProvider(this->_xalUser, "SERVICE_CONFIG_ID-DEADBEEF0123", false, &provider); 
    if (SUCCEEDED(hr)) 
    { 
        this->_provider = provider; 
    } 
    else 
    { 
        _HandleInitializeErrors(this->_xalUser, hr); 
    } 
} 
 
// handle initialization errors  
void Sample::_HandleInitializeErrors(XUserHandle userContext, HRESULT hr) 
{ 
    switch (hr) 
    { 
    case E_GS_USER_CANCELED: 
        printf("User %p canceled initialization hr=0x%08x\n", userContext, hr); 
        break; 
    case E_GS_USER_NOT_REGISTERED_IN_SERVICE: 
        printf("User %p has no service registration\n", userContext); 
        break; 
    /* NOTE These should only be seen if there is a configuration issue */ 
    case E_GS_NO_ACCESS: 
    case E_GS_NO_SERVICE_CONFIGURATION: 
        printf("Problems with Service Configuration registration\n"); 
        break; 
    case S_OK: 
        break; 
    default: 
        printf("Unknown initialization error for User %p hr=0x%08X\n", userContext, hr); 
    } 
} 
```

遊戲無法混合使用 XGameSaveFiles 與 XGameSave。遊戲必須選擇要使用哪一個雲端存檔系統。
如果遊戲使用 XGameSaveFiles，之後又呼叫 XGameSaveInitializeProvider，將會發生錯誤並傳回
E\_GS\_PROVIDER\_MISMATCH。同樣地，如果遊戲使用 XGameSave，之後又呼叫 XGameSaveFilesGetFolderWithUiAsync，
也會發生錯誤並傳回 E\_GS\_PROVIDER\_MISMATCH。

## 需求

**標頭：** XGameSave.h

**程式庫：** xgameruntime.lib

**支援的平台：** Windows、XBOX One 系列主機和 XBOX Series 主機

## 概念文件

* [遊戲存檔工具](/zh-TW/build/core-features/common/game-save/game-saves-tools)
* [時間敏感執行緒](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## 另請參閱

[XGameSave](/zh-TW/reference/system/xgamesave/xgamesave_members)\
[XGameSaveInitializeProviderAsync](/zh-TW/reference/system/xgamesave/functions/xgamesaveinitializeproviderasync)\
[偵錯遊戲存檔](/zh-TW/build/core-features/common/game-save/game-saves-debugging)


## Related topics

- [XGameSaveInitializeProvider](/reference/system/xgamesave/functions/xgamesaveinitializeprovider.md)
- [XGameSaveInitializeProviderAsync](/reference/system/xgamesave/functions/xgamesaveinitializeproviderasync.md)