XGameSaveSubmitBlobWrite

Article
06/22/2023

Adds a write action to a XGameSaveUpdate.

Syntax

HRESULT XGameSaveSubmitBlobWrite(  
         XGameSaveUpdateHandle updateContext,  
         const char* blobName,  
         const uint8_t* data,  
         size_t byteCount  
)

Parameters

updateContext _In_
Type: XGameSaveUpdateHandle

Handle to the XGameSaveUpdate the blob will be written to.

blobName _In_z_
Type: char*

Name of the blob to be written. The size of the blob name should not be greater than GS_MAX_BLOB_NAME_SIZE, in bytes.

data _In_reads_bytes_(byteCount)
Type: uint8_t*

Data to be written to the blob.

byteCount _In_
Type: size_t

Size of the data to be written to the blob. The size of the blob data should not be greater than GS_MAX_BLOB_SIZE, in bytes.

Note

While the size of the blob data is limited to GS_MAX_BLOB_SIZE, the entire update is also limited to GS_MAX_BLOB_SIZE. If an update contains a blob of GS_MAX_BLOB_SIZE, additional updates must be made in separate update requests.

Return value

Type: HRESULT

Function result.

Remarks

Note

This function isn't safe to call on a time-sensitive thread. For more information, see Time-sensitive threads.

You need to successfully call XGameSaveCreateUpdate before making this call.

The storage portion of this API is designed to easily transfer data from the game to persisted storage in a safe, reliable and transactional manner. We want to make sure the backing data for a container is always consistent and as such we want the whole operation to succeed or fail atomically. We don't want to have a partial update where some blob data is inconsistent with other data within the container. In order to do this we provide an update context that blob writes and deletes are submitted to and when that is ready the whole context is submitted. Note that you can only write one modification/deletion per blob in an update context. In practice this looks like the following:

An XGameSaveUpdate will be filled with Write and Delete actions to be carried out on blobs within the container by way of XGameSaveSubmitBlobWrite and XGameSaveSubmitBlobDelete. An update is completed by calling XGameSaveSubmitUpdate.

See the XGameSaveCreateUpdate examples for usage.

Requirements

Header: XGameSave.h

Library: xgameruntime.lib

Supported platforms: Windows, Xbox One family consoles and Xbox Series consoles