> ## 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 Provider 핸들을 제공하고 초기화합니다.

## 구문

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

### 매개 변수

*requestingUser*   \_In\_\
형식: XUserHandle

XBOX Live 사용자에 대한 핸들입니다.

*configurationId*   \_In\_z\_\
형식: char\*

서비스 구성 ID(SCID)입니다.

*syncOnDemand*   \_In\_\
형식: bool

true인 경우 syncOnDemand는 필요한 경우에만 서비스에서 데이터를 다운로드합니다. 장치가 오프라인 상태이면 작동하지 않습니다.
true로 설정하면 동기화 진행률 UI가 표시될 수 있습니다.

*provider*   \_Outptr\_result\_nullonfailure\_\
형식: XGameSaveProviderHandle\*

만들어질 XGameSave Provider에 대한 핸들입니다.

### 반환값

형식: 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](/reference/system/xgamesave/functions/xgamesaveinitializeproviderasync) 호출을 고려하세요.

<Note>XGameSave API가 작동하려면 타이틀에 타이틀 ID와 서비스 구성 ID(SCID)가</Note>
올바르게 구성되어 있어야 합니다. 필수 ID에 대한 자세한 내용은 [XBOX Live 개발을 위한
샌드박스 설정](/services/xbox-services/fundamentals/sandboxes/live-setting-up-sandboxes)을 참조하세요. 게임은 파트너 센터에서 XBOX Live에 대해 활성화되어 있어야 합니다.

SCID와 타이틀 ID를 올바르게 구성하지 않으면 XSaveGame API 호출은 다음 오류 코드와 함께 실패합니다.

E\_GS\_NO\_ACCESS - 0x80830002 - 타이틀이 컨테이너 저장소 공간에 액세스할 수 없어 작업이 실패했습니다.

이 API를 *syncOnDemand* 를 true로 설정하여 호출하면 호출자 관점에서는 동일하게 동작하지만,
API의 나머지 부분에서는 몇 가지 동작 차이가 발생합니다. *SyncOnDemand* **XGameSaveProvider** 는
필요한 경우에만 서비스에서 데이터를 다운로드하지만, 이 경우 컨테이너 작업이 지연될 수 있고
이 지연으로 인해 사용자에게 동기화 진행 UX가 표시될 수 있다는 단점도 있습니다. 다음 메서드 중 어느 것이든
사용하면 동기화가 강제로 수행될 수 있습니다.

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

또 다른 단점은 장치가 오프라인 상태이거나 연결 문제가 있는 경우 컨테이너에
액세스할 수 없다는 것입니다. 이 함수에는
[XGameSaveInitializeProviderAsync](/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 콘솔

## 개념 설명서

* [게임 저장 도구](/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](/reference/system/xgamesave/xgamesave_members)\
[XGameSaveInitializeProviderAsync](/reference/system/xgamesave/functions/xgamesaveinitializeproviderasync)\
[게임 저장 디버깅](/build/core-features/common/game-save/game-saves-debugging)


## Related topics

- [XGameSaveInitializeProviderAsync](/ko/reference/system/xgamesave/functions/xgamesaveinitializeproviderasync.md)
- [XGameSaveCloseProvider](/ko/reference/system/xgamesave/functions/xgamesavecloseprovider.md)
- [게임 저장 도구](/ko/build/core-features/common/game-save/game-saves-tools.md)
- [XGameSave API 개요](/ko/build/core-features/common/game-save/xgamesave.md)
- [게임 저장 워크스루 및 샘플](/ko/build/core-features/common/game-save/game-saves-walkthroughs-and-samples.md)