> ## 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.

# XGameSaveCreateUpdate

> XGameSaveCreateUpdate

# XGameSaveCreateUpdate

Cria uma atualização que será enviada posteriormente chamando [XGameSaveSubmitUpdate](/pt-BR/reference/system/xgamesave/functions/xgamesavesubmitupdate).

## Sintaxe

```cpp theme={null}
HRESULT XGameSaveCreateUpdate(  
         XGameSaveContainerHandle container,  
         const char* containerDisplayName,  
         XGameSaveUpdateHandle* updateContext  
)  
```

### Parâmetros

*container*   \_In\_\
Tipo: XGameSaveContainerHandle

Identificador do XGameSaveContainer a ser atualizado.

*containerDisplayName*   \_In\_z\_\
Tipo: char\*

Nome de exibição do contêiner a ser atualizado.

*updateContext*   \_Outptr\_result\_nullonfailure\_\
Tipo: XGameSaveUpdateHandle\*

Identificador do XGameSaveUpdate a ser criado.

### Valor retornado

Tipo: HRESULT

Resultado da função.

## Comentários

<Note>Não é seguro chamar esta função em um thread sensível ao tempo. Para obter mais informações, consulte [Threads sensíveis ao tempo](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads).</Note>

A parte de armazenamento desta API foi projetada para transferir facilmente dados do jogo para o armazenamento persistente de maneira segura, confiável e transacional. Queremos garantir que os dados subjacentes de um contêiner estejam sempre consistentes e, por isso, queremos que toda a operação seja bem-sucedida ou falhe de forma atômica. Não queremos uma atualização parcial em que alguns dados de blob fiquem inconsistentes com outros dados dentro do contêiner. Para isso, fornecemos um contexto de atualização ao qual as gravações e exclusões de blob são enviadas e, quando ele estiver pronto, todo o contexto é enviado. Na prática, fica assim:

Um **XGameSaveUpdate** será preenchido com ações de gravação e exclusão a serem executadas em blobs dentro do contêiner por meio de [XGameSaveSubmitBlobWrite](/pt-BR/reference/system/xgamesave/functions/xgamesavesubmitblobwrite) e [XGameSaveSubmitBlobDelete](/pt-BR/reference/system/xgamesave/functions/xgamesavesubmitblobdelete). Uma atualização é concluída chamando [XGameSaveSubmitUpdate](/pt-BR/reference/system/xgamesave/functions/xgamesavesubmitupdate).

Quando terminar de usar um **XGameSaveUpdate**, feche-o com [XGameSaveCloseUpdate](/pt-BR/reference/system/xgamesave/functions/xgamesavecloseupdate).

O exemplo em C++ a seguir demonstra uma atualização síncrona de XGameSave.

<a id="example" />

```cpp theme={null}
// SYNC Write - should not be called on a time sensitive thread 
//              as this will block until the operation is complete 
void Sample::_SaveDataSync(const char* containerName, const char* containerDisplayName) 
{ 
    HRESULT hr; 
    XGameSaveContainerHandle containerContext; 
    XGameSaveUpdateHandle updateContext; 
  
    hr = XGameSaveCreateContainer(_provider, containerName, &containerContext); 
    if (SUCCEEDED(hr)) 
    { 
        hr = XGameSaveCreateUpdate(containerContext, containerDisplayName, &updateContext); 
    } 
    if (SUCCEEDED(hr)) 
    { 
        hr = XGameSaveSubmitBlobWrite(updateContext, "WorldState", _worldState.data(), _worldState.size()); 
    } 
    if (SUCCEEDED(hr)) 
    { 
        hr = XGameSaveSubmitBlobWrite(updateContext, "PlayerState", _playerState.data(), _playerState.size()); 
    } 
    if (SUCCEEDED(hr)) 
    { 
        hr = XGameSaveSubmitBlobWrite(updateContext, "PlayerInventory", _playerInventory.data(), _playerInventory.size()); 
    } 
    if (SUCCEEDED(hr)) 
    { 
        if (_clearLevelProgress) 
        { 
            hr = XGameSaveSubmitBlobDelete(updateContext, "LevelProgress"); 
        } 
    } 
  
    if (SUCCEEDED(hr)) 
    { 
        hr = XGameSaveSubmitUpdate(updateContext); 
    } 
  
    if (updateContext) 
    { 
        XGameSaveCloseUpdate(updateContext); 
    } 
    if (containerContext) 
    { 
        XGameSaveCloseContainer(containerContext); 
    } 
  
    _HandleContainerUpdateErrors(hr); 
} 
  
  
void Sample::_HandleContainerUpdateErrors(HRESULT hr) 
{ 
    switch (hr) 
    { 
    case E_GS_INVALID_CONTAINER_NAME: 
        // tried to access a container with an invalid name 
        break; 
    case E_GS_OUT_OF_LOCAL_STORAGE: 
        // storage location is full, let the user know that saves won't work till this is fixed 
        break; 
    case E_GS_UPDATE_TOO_BIG: 
        // the blob that we provided was too big, can't be larger than GS_MAX_BLOB_SIZE 
        break; 
    case E_GS_QUOTA_EXCEEDED: 
        // the update we did was larger than our overall quota, need to track that! (see XGameSaveQueryRemainingQuota & XGameSaveQueryRemainingQuotaAsync) 
        break; 
    case E_GS_CONTAINER_NOT_IN_SYNC: 
    case E_GS_CONTAINER_SYNC_FAILED: 
        // need to sync and we are offline ? 
        break; 
    case E_GS_HANDLE_EXPIRED: 
        // need to re-initialize since another device has taken 
        // ownership while we were suspended and/or busy 
        break; 
    } 
}
```

O exemplo em C++ a seguir demonstra uma atualização assíncrona de XGameSave.

```cpp theme={null}
// ASYNC Write - can be kicked off from a time sensitive thread 
//               actual work and completion will be scheduled base upon 
//               the configuration of the async_queue tied to the XAsyncBlock. 
void Sample::_SaveDataAsync(const char* containerName, const char* containerDisplayName) 
{ 
    struct SaveContext 
    { 
        SaveContext(Sample* s) : self(s), containerContext(nullptr), updateContext(nullptr) {} 
        ~SaveContext() 
        { 
            if (updateContext) 
            { 
                XGameSaveCloseUpdate(updateContext); 
            } 
            if (containerContext) 
            { 
                XGameSaveCloseContainer(containerContext); 
            } 
        } 
  
        XAsyncBlock async; 
        XGameSaveContainerHandle containerContext; 
        XGameSaveUpdateHandle updateContext; 
        Sample* self; 
    }; 
  
    HRESULT hr; 
    SaveContext* saveContext = new SaveContext(this); 
    if (saveContext == nullptr) 
    { 
        hr = E_OUTOFMEMORY; 
    } 
    if (SUCCEEDED(hr)) 
    { 
        saveContext->async.context = saveContext; 
        saveContext->async.callback = [](XAsyncBlock* async) 
        { 
            auto ctx = reinterpret_cast<SaveContext*>(async->context); 
            auto self = ctx->self; 
            HRESULT hr = XGameSaveSubmitUpdateResult(async); 
            self->_HandleContainerUpdateErrors(hr); 
            delete ctx; 
        }; 
    } 
  
    if (SUCCEEDED(hr)) 
    { 
        hr = XGameSaveCreateContainer(_provider, containerName, &saveContext->containerContext); 
    } 
    if (SUCCEEDED(hr)) 
    { 
        hr = XGameSaveCreateUpdate(saveContext->containerContext, containerDisplayName, &saveContext->updateContext); 
    } 
  
    if (SUCCEEDED(hr)) 
    { 
        hr = XGameSaveSubmitBlobWrite(saveContext->updateContext, "WorldState", _worldState.data(), _worldState.size()); 
    } 
    if (SUCCEEDED(hr)) 
    { 
        hr = XGameSaveSubmitBlobWrite(saveContext->updateContext, "PlayerState", _playerState.data(), _playerState.size()); 
    } 
    if (SUCCEEDED(hr)) 
    { 
        hr = XGameSaveSubmitBlobWrite(saveContext->updateContext, "PlayerInventory", _playerInventory.data(), _playerInventory.size()); 
    } 
    if (SUCCEEDED(hr)) 
    { 
        if (_clearLevelProgress) 
        { 
            hr = XGameSaveSubmitBlobDelete(saveContext->updateContext, "LevelProgress"); 
        } 
    } 
    if (SUCCEEDED(hr)) 
    { 
        hr = XGameSaveSubmitUpdateAsync(saveContext->updateContext, &saveContext->async); 
    } 
    if (SUCCEEDED(hr)) 
    { 
        // context is now owned by the async 
        saveContext = nullptr; 
    } 
  
    // if there was any error we need to cleanup the saveContext 
    if (saveContext) 
    { 
        delete saveContext; 
    } 
  
} 
```

## 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

* [Threads sensíveis ao tempo](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## Confira também

[XGameSave](/pt-BR/reference/system/xgamesave/xgamesave_members)\
[XGameSaveSubmitBlobWrite](/pt-BR/reference/system/xgamesave/functions/xgamesavesubmitblobwrite)\
[XGameSaveSubmitBlobDelete](/pt-BR/reference/system/xgamesave/functions/xgamesavesubmitblobdelete)\
[XGameSaveSubmitUpdate](/pt-BR/reference/system/xgamesave/functions/xgamesavesubmitupdate)\
[XGameSaveCloseUpdate](/pt-BR/reference/system/xgamesave/functions/xgamesavecloseupdate)
[Depuração de salvamentos de jogos](/pt-BR/build/core-features/common/game-save/game-saves-debugging)


## Related topics

- [XGameSaveCreateUpdate](/zh-CN/reference/system/xgamesave/functions/xgamesavecreateupdate.md)
- [XGameSaveCloseUpdate](/reference/system/xgamesave/functions/xgamesavecloseupdate.md)