Skip to main content

XGameSaveInitializeProvider

Fornece e inicializa um identificador de XGameSave Provider.

Sintaxe

Parâmetros

requestingUser   _In_
Tipo: XUserHandle
Identificador para um usuário do XBOX Live. configurationId   _In_z_
Tipo: char*
ID de configuração de serviço (SCID). syncOnDemand   _In_
Tipo: bool
Quando true, syncOnDemand só baixa dados do serviço se necessário. Não funciona se o dispositivo estiver offline. Defini-lo como true pode fazer com que a interface do usuário de progresso da sincronização seja mostrada. provider   _Outptr_result_nullonfailure_
Tipo: XGameSaveProviderHandle*
Um identificador para o XGameSave Provider a ser criado.

Valor retornado

Tipo: HRESULT Resultado da função.

Erros comuns

  • E_GS_USER_CANCELED
  • E_GS_USER_NOT_REGISTERED_IN_SERVICE
  • E_GS_NO_ACCESS
  • E_GS_NO_SERVICE_CONFIGURATION
Os erros retornados com mais frequência são E_OUTOFMEMORY, E_INVALIDARG,

Comentários

Não é seguro chamar esta função em uma thread sensível ao tempo. Para obter mais informações, consulte Threads sensíveis ao tempo.
Esta função deve ser chamada com êxito antes que outras APIs XGameSave sejam usadas. Esta função não deve ser chamada na thread de interface do usuário do jogo, pois ela pode bloquear e potencialmente mostrar a interface do usuário ao usuário enquanto sincroniza os salvamentos de jogos do jogador. Se você precisar inicializá-la a partir da thread de interface do usuário, considere chamar XGameSaveInitializeProviderAsync.
A API XGameSave exige que seu título tenha a ID do título e a ID de configuração de serviço (SCID)
configuradas corretamente para funcionar. Para obter mais informações sobre essas IDs obrigatórias, consulte Configurando sandboxes para o desenvolvimento no XBOX Live. Seu jogo deve estar habilitado para XBOX Live no Partner Center.
Se você não configurar a SCID e a ID do título corretamente, suas chamadas à API XSaveGame falharão com o seguinte código de erro: E_GS_NO_ACCESS - 0x80830002 - A operação falhou porque o título não tem acesso aos espaços de armazenamento do contêiner. Quando esta API é chamada com syncOnDemand definido como true, ela se comporta da mesma forma da perspectiva do chamador, mas causa algumas diferenças de comportamento no restante da API. O XGameSaveProvider SyncOnDemand só baixará dados do serviço se necessário, mas isso também tem a desvantagem de que qualquer operação de contêiner pode ser atrasada nesse caso e esse atraso pode fazer com que alguma UX seja mostrada ao usuário para o progresso da sincronização. Usar qualquer um dos seguintes métodos pode forçar uma sincronização: Outra desvantagem é que, se o dispositivo estiver offline ou tiver problemas de conectividade, o acesso ao contêiner será impossível. Há uma versão assíncrona desta função chamada XGameSaveInitializeProviderAsync
Os jogos não podem misturar o uso de XGameSaveFiles com o uso de XGameSave. Os jogos devem escolher qual sistema de salvamento na nuvem desejam usar. Se o jogo estiver usando XGameSaveFiles e depois chamar XGameSaveInitializeProvider, ocorrerá o erro E_GS_PROVIDER_MISMATCH. Da mesma forma, se o jogo estava usando XGameSave e depois chamar XGameSaveFilesGetFolderWithUiAsync, também ocorrerá o erro E_GS_PROVIDER_MISMATCH.

Requisitos

Cabeçalho: XGameSave.h Biblioteca: xgameruntime.lib Plataformas com suporte: Windows, consoles da família XBOX One e consoles XBOX Series

Documentação conceitual

Confira também

XGameSave
XGameSaveInitializeProviderAsync
Depuração de salvamentos de jogos
Last modified on October 6, 2026