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

# XGameSaveEnumerateContainerInfoByName

> XGameSaveEnumerateContainerInfoByName

# XGameSaveEnumerateContainerInfoByName

检索 **XGameSaveProvider** 的容器信息。提供前缀将导致该函数仅返回具有相同前缀的名称。

## Syntax

```cpp theme={null}
HRESULT XGameSaveEnumerateContainerInfoByName(  
         XGameSaveProviderHandle provider,  
         const char* containerNamePrefix,  
         void* context,  
         XGameSaveContainerInfoCallback* callback  
)  
```

### Parameters

*provider*   \_In\_\
类型：XGameSaveProviderHandle

包含 [XGameSaveContainerInfo](/reference/system/xgamesave/structs/xgamesavecontainerinfo) 的 **XGameSaveProvider**。

*containerNamePrefix*   \_In\_opt\_z\_\
类型：char\*

将用于在容器列表中搜索匹配容器名称的前缀。

*context*   \_In\_opt\_\
类型：void\*

将传递给回调函数的指针。

*callback*   \_In\_\
类型：XGameSaveContainerInfoCallback\*

要为每个与前缀匹配的容器运行的回调函数，返回 false 以停止枚举。使用此函数收集 [XGameSaveContainerInfo](/reference/system/xgamesave/structs/xgamesavecontainerinfo)。

### Return value

类型：HRESULT

函数结果。

## Remarks

使用此函数检查有哪些容器可用于某个用户。这可能包括需要在 UX 中显示的数据。枚举此集不会导致 SyncOnDemand 提供程序进行同步，并将允许调用方通过 [XGameSaveContainerInfo](/reference/system/xgamesave/structs/xgamesavecontainerinfo) 的 needsSync 字段实际检查同步状态。对 *needsSync* 设置为 true 的容器执行的任何 Blob 数据读取或对更新上下文的使用将强制同步，并可能返回各种同步错误。如果不需要为要枚举的容器指定前缀，则可以使用 [XGameSaveEnumerateContainerInfo](/reference/system/xgamesave/functions/xgamesaveenumeratecontainerinfo)。[XGameSaveEnumerateContainerInfo](/reference/system/xgamesave/functions/xgamesaveenumeratecontainerinfo) 将返回所有可用容器的完整列表。

```cpp theme={null}
// Enumerate Container List by prefix, if no prefix is supplied it is 
// the same as calling XGameSaveEnumerateContainerInfo. 
// NOTE: this should be safe to call from a time critical thread 
// but the we are at the mercy of the callback. 
void Sample::_EnumerateContainerInfoByName(const char* prefix) 
{ 
    HRESULT hr = XGameSaveEnumerateContainerInfoByName(_provider, prefix, this, 
        [](const XGameSaveContainerInfo* container, void* context) 
    { 
        auto self = reinterpret_cast<Sample*>(context); 
        self->_UpdateContainerList(container); 
        return true; 
    }); 
    if (FAILED(hr)) 
    { 
        _HandleContainerErrors(prefix, hr); 
    } 
  
} 
```

## Requirements

**头文件：** XGameSave.h

**库：** xgameruntime.lib

**受支持的平台：** Windows、XBOX One 系列主机和 XBOX Series 主机

## Conceptual documentation

* [时间敏感型线程](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## See also

[XGameSave](/reference/system/xgamesave/xgamesave_members)\
[XGameSaveEnumerateContainerInfo](/reference/system/xgamesave/functions/xgamesaveenumeratecontainerinfo)\
[调试游戏保存](/build/core-features/common/game-save/game-saves-debugging)


## Related topics

- [XGameSaveEnumerateContainerInfo](/zh-CN/reference/system/xgamesave/functions/xgamesaveenumeratecontainerinfo.md)
- [XGameSaveContainerInfoCallback](/zh-CN/reference/system/xgamesave/functions/xgamesavecontainerinfocallback.md)
- [XGameSaveContainerInfo](/zh-CN/reference/system/xgamesave/structs/xgamesavecontainerinfo.md)
- [XGameSaveGetContainerInfo](/zh-CN/reference/system/xgamesave/functions/xgamesavegetcontainerinfo.md)
- [XGameSave API 概述](/zh-CN/build/core-features/common/game-save/xgamesave.md)