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

# XGameSaveReadBlobData

> XGameSaveReadBlobData

# XGameSaveReadBlobData

讀取容器的 Blob 資料。

## 語法

```cpp theme={null}
HRESULT XGameSaveReadBlobData(  
         XGameSaveContainerHandle container,  
         const char** blobNames,  
         uint32_t* countOfBlobs,  
         size_t blobsSize,  
         XGameSaveBlob* blobData  
)  
```

### 參數

*container*   \_In\_\
類型：XGameSaveContainerHandle

包含 XGameSaveBlob 資料的 **XGameSaveContainer** 控制代碼。

*blobNames*   \_In\_opt\_z\_count\_(*countOfBlobs)\
類型：char*\*

指向代表 [XGameSaveBlob](/zh-TW/reference/system/xgamesave/structs/xgamesaveblob) 名稱之字串陣列的指標。

*countOfBlobs*   \_Inout\_\
類型：uint32\_t\*

要讀取的 Blob 數目。

*blobsSize*   \_In\_\
類型：size\_t

已配置之 Blob 資料的大小，可從讀取 Blob 中繼資料推斷。

*blobData*   \_Out\_writes\_bytes\_(blobsSize)\
類型：[XGameSaveBlob\*](/zh-TW/reference/system/xgamesave/structs/xgamesaveblob)

用來包含 Blob 資料的 [XGameSaveBlob](/zh-TW/reference/system/xgamesave/structs/xgamesaveblob) 指標。必須已配置記憶體，以儲存從容器要求的所有 Blob。

### 傳回值

類型：HRESULT

函式結果。

#### 常見錯誤

* E\_GS\_INVALID\_CONTAINER\_NAME
* E\_GS\_PROVIDED\_BUFFER\_TOO\_SMALL
* E\_GS\_BLOB\_NOT\_FOUND
* E\_GS\_CONTAINER\_NOT\_IN\_SYNC
* E\_GS\_CONTAINER\_SYNC\_FAILED
* E\_GS\_HANDLE\_EXPIRED

## 備註

<Note>在時間敏感執行緒上呼叫此函式並不安全。如需詳細資訊，請參閱[時間敏感執行緒](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)。</Note>

使用此函式讀取遊戲存檔 Blob 中的資料。此函式會傳回 Blob 的數目以及 Blob 容器內的資料。您可以使用這些值逐一查看容器中的 Blob，以讀取適當的資訊。此函式有一個非同步版本，稱為 [XGameSaveReadBlobDataAsync](/zh-TW/reference/system/xgamesave/functions/xgamesavereadblobdataasync)。

```cpp theme={null}
// SYNC Read - should not be called on time sensitive thread 
//             as this will block until the operation is complete 
void Sample::_ReadContainerBlobsSync(const XGameSaveContainerInfo* container) 
{ 
    const char* blobNames[] = { 
        "WorldState", 
        "PlayerState", 
        "PlayerInventory" 
    }; 
  
    XGameSaveContainerHandle containerContext = nullptr; 
    size_t allocSize; 
    uint32_t countOfBlobs = _countof(blobNames); 
    XGameSaveBlob* blobs = nullptr; 
    HRESULT hr = XGameSaveCreateContainer(_provider, container->name, &containerContext); 
  
    if (SUCCEEDED(hr)) 
    { 
        // this method finds the size for only the blobs in the container 
        // that we are requesting to read right now 
        hr = _GetContainerBlobsDataSize(container, blobNames, _countof(blobNames), &allocSize); 
    } 
    if (SUCCEEDED(hr)) 
    { 
        blobs = reinterpret_cast<XGameSaveBlob*>(malloc(allocSize)); 
        if (blobs == nullptr) 
        { 
            hr = E_OUTOFMEMORY; 
        } 
    } 
    if (SUCCEEDED(hr)) 
    { 
        hr = XGameSaveReadBlobData(containerContext, blobNames, &countOfBlobs, allocSize, blobs); 
    } 
    if (SUCCEEDED(hr)) 
    { 
        if (countOfBlobs == _countof(blobNames)) 
        { 
            for (uint32_t i = 0; i < countOfBlobs; i++) 
            { 
                XGameSaveBlob* currentBlob = blobs + i; 
                if (strcmp(currentBlob->info.name, "WorldState") == 0) 
                { 
                    hr = _LoadSaveBlob(currentBlob, _worldState); 
                } 
                else if (strcmp(currentBlob->info.name, "PlayerState") == 0) 
                { 
                    hr = _LoadSaveBlob(currentBlob, _playerState); 
                } 
                else if (strcmp(currentBlob->info.name, "PlayerInventory") == 0) 
                { 
                    hr = _LoadSaveBlob(currentBlob, _playerInventory); 
                } 
                if (FAILED(hr)) 
                { 
                    break; 
                } 
            } 
        } 
        else 
        { 
            hr = E_UNEXPECTED; 
        } 
    } 
  
    _HandleContainerBlobErrors(hr); 
  
    if (blobs != nullptr) 
    { 
        free(blobs); 
    } 
    if (containerContext != nullptr) 
    { 
        XGameSaveCloseContainer(containerContext); 
    } 
} 
  
  
void Sample::_HandleContainerBlobErrors(HRESULT hr) 
{ 
    // set some state 
    switch (hr) 
    { 
    case E_GS_INVALID_CONTAINER_NAME: 
        // tried to access a container with an invalid name 
        break; 
    case E_GS_PROVIDED_BUFFER_TOO_SMALL: 
        // shouldn't ever happen unless our math is wrong!! 
        break; 
    case E_GS_BLOB_NOT_FOUND: 
        // we asked for a blob that isn't in the container 
        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 主機

## 概念文件

* [時間敏感執行緒](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## 另請參閱

[XGameSave](/zh-TW/reference/system/xgamesave/xgamesave_members)\
[XGameSaveBlobInfo](/zh-TW/reference/system/xgamesave/structs/xgamesaveblobinfo)\
[XGameSaveReadBlobDataAsync](/zh-TW/reference/system/xgamesave/functions/xgamesavereadblobdataasync)\
[偵錯遊戲存檔](/zh-TW/build/core-features/common/game-save/game-saves-debugging)


## Related topics

- [XGameSaveReadBlobData](/ko/reference/system/xgamesave/functions/xgamesavereadblobdata.md)
- [XGameSaveReadBlobDataAsync](/reference/system/xgamesave/functions/xgamesavereadblobdataasync.md)