XGameSaveSubmitUpdate

将更新提交到 XGameSave 服务。 更新容器内的 blob。

语法

HRESULT XGameSaveSubmitUpdate(  
         XGameSaveUpdateHandle updateContext  
)  

参数

updateContext _In_
类型：XGameSaveUpdateHandle

要更新的 XGameSaveUpdate 的句柄。

返回值

类型：HRESULT

函数结果。

常见错误

• E_GS_INVALID_CONTAINER_NAME
• E_GS_OUT_OF_LOCAL_STORAGE
• E_GS_UPDATE_TOO_BIG
• E_GS_QUOTA_EXCEEDED
• E_GS_CONTAINER_NOT_IN_SYNC
• E_GS_CONTAINER_SYNC_FAILED
• E_GS_HANDLE_EXPIRED

备注

注意

在时间敏感线程上调用此函数是不安全的。 有关详细信息，请参阅时间敏感线程。

在进行此调用前，您将需要成功调用 XGameSaveCreateUpdate。

此 API 的存储部分旨在轻松地以安全、可靠和事务性的方式将数据从游戏传输到永久性存储器中。 我们希望确保容器的备份数据始终一致，因此我们希望整个操作自动成功或失败。 我们不希望容器内某些 blob 数据与其他数据不一致的情况下进行部分更新。 为了执行此操作，我们提供 blob 写入和删除提交到的更新上下文，并且在其就绪时提交整个上下文。 在实践中，这类似于以下内容：

XGameSaveUpdate 将用写入和删除操作填充，以便通过 XGameSaveSubmitBlobWrite 和 XGameSaveSubmitBlobDelete 对容器内的 blob 执行。 通过调用 XGameSaveSubmitUpdate 完成更新。

在您使用 XGameSaveUpdate 完成后，使用 XGameSaveCloseUpdate 方法关闭它。

下面的 C++ 示例演示了同步 XGameSave 更新。

// 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; 
    } 
} 

要求

头文件：XGameSave.h

库：xgameruntime.lib

支持平台：Windows、Xbox One 系列主机和 Xbox Series 主机

另请参阅

XGameSave
XGameSaveCreateUpdate
XGameSaveSubmitBlobWrite
XGameSaveSubmitBlobDelete
XGameSaveCloseUpdate游戏保存错误