XGameSaveInitializeProvider

XGameSave 제공자 핸들을 제공하고 초기화합니다.

구문

HRESULT XGameSaveInitializeProvider(  
         XUserHandle requestingUser,  
         const char* configurationId,  
         bool syncOnDemand,  
         XGameSaveProviderHandle* provider  
)  

매개 변수

requestingUser _In_
형식: XUserHandle

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

configurationId _In_z_
형식: char*

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

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입니다.

비고

참고 항목

이 함수는 시간에 민감한 스레드에서 호출하는 것이 안전하지 않습니다. 자세한 내용은 시간에 민감한 스레드를 참조하세요.

이 함수는 다른 XGameSave API가 사용되기 전에 성공적으로 호출되어야 합니다. 이 함수는 플레이어의 게임 저장을 동기화할 때 사용자 UI를 차단하고 잠재적으로 표시할 수 있으므로 게임의 UI 스레드에서 호출되어서는 안 됩니다. UI 스레드에서 초기화해야 하는 경우 XGameSaveInitializeProviderAsync를 호출하는 것이 좋습니다.

참고 항목

XGameSave API를 사용하려면 타이틀 ID 및 SCID(서비스 구성 ID)가 올바르게 구성되어 있어야 합니다. 이러한 필수 ID에 대한 자세한 내용은 Xbox Live 개발을 위한 샌드박스 설정을 참조하세요. 게임이 파트너 센터에서 Xbox Live에 대해 활성화되어 있어야 합니다.

SCID 및 타이틀 ID를 올바르게 구성하지 않으면 XSaveGame API 호출이 실패하고 다음 오류 코드가 표시됩니다.

E_GS_NO_ACCESS - 0x80830002 - 타이틀에 컨테이너 저장소 공간에 대한 액세스 권한이 없기 때문에 작업이 실패했습니다.

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

• XGameSaveCreateUpdate
• XGameSaveEnumeratorBlobInfo
• XGameSaveEnumerateBlobInfoByName
• XGameSaveEnumerateContainerInfo
• XGameSaveEnumerateContainerInfoByName

장치가 오프라인이거나 연결 문제가 있으면 컨테이너 액세스가 불가능하다는 또 다른 단점도 있습니다. 이 함수에는 XGameSaveInitializeProviderAsync라는 비동기 버전이 있습니다.

// 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 콘솔

참고 항목

XGameSave
XGameSaveInitializeProviderAsync
게임 저장 오류