> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XGameStreamingShowTouchControlsWithStateUpdate

> XGameStreamingShowTouchControlsWithStateUpdate

# XGameStreamingShowTouchControlsWithStateUpdate

请求所有已连接的流式处理客户端设备更新其触摸控件状态并显示指定的触摸布局。所有状态更新都会在显示新的触摸布局之前进行。

## 语法

```cpp theme={null}
HRESULT XGameStreamingShowTouchControlsWithStateUpdate(  
         const char* layout,  
         size_t operationCount,  
         const XGameStreamingTouchControlsStateOperation* operations  
)  
```

### 参数

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

要显示的触摸控件布局的名称，或 `nullptr` 以显示标准布局。

*operationCount*   \_In\_\
类型：size\_t

所传递的操作数组的大小。

*operations*   \_In\_reads\_opt\_(operationCount)\
类型：[XGameStreamingTouchControlsStateOperation\*](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/structs/xgamestreamingtouchcontrolsstateoperation.md)

所请求的所有状态变量更新的数组。

### 返回值

类型：HRESULT

如果成功，则返回 **S\_OK**；否则返回错误代码。

#### 潜在错误

| 错误代码 | 错误值 | 错误原因 |
| - | - | - |
| E\_GAMESTREAMING\_NOT\_INITIALIZED | 0x89245400 | XGameStreaming 运行时尚未初始化。在调用其他 API 之前，请先调用 [XGameStreamingInitialize](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/functions/xgamestreaminginitialize.md)。 |
| E\_INVALIDARG | 0x80070057 | 指定的操作没有与操作 [XGameStreamingTouchControlsStateValueKind](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/enums/xgamestreamingtouchcontrolsstatevaluekind.md) 中指定的数据类型匹配的数据 |

## 备注

当游戏需要显示某个触摸布局，同时又需要一些可能影响其呈现的状态更新时，应使用此 API。如果你希望同时更新新触摸布局中引用的变量的状态并在所有已连接的流式处理客户端设备上切换到该触摸布局，请使用此 API。此 API 可确保在显示新布局之前完成所有状态更新。

如果只想影响特定客户端，请使用 [XGameStreamingShowTouchControlsWithStateUpdateOnClient](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/functions/xgamestreamingshowtouchcontrolswithstateupdateonclient.md)。

如果游戏只想更改布局，则应改用 [XGameStreamingShowTouchControlLayout](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/functions/xgamestreamingshowtouchcontrollayout.md)。

如果状态更新可能会影响当前布局或其他布局，并且无论是否发生特定的触摸布局更改，都应进行更新，则游戏应改用 [XGameStreamingUpdateTouchControlsState](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/functions/xgamestreamingupdatetouchcontrolsstate.md)。

## 示例

```c++ theme={null}
// In this example, the player has just selected a specific building in an strategy game 
// and the game wants to populate the two building specific action slots with the appropriate imagery
// before selecting the layouts
//
// Assumes passing in game structure that refers to the selected building and a game function to get the image
// assets for a particular building capability.


void GameStreamingClientManager::UpdateBuildingStateAndControls(const BuildingProperties& building)
{
    
    

    std::vector<XGameStreamingTouchControlsStateOperation> updateOperations;
    
    // update the image for the first two building slots   
    XGameStreamingTouchControlsStateOperation buildingCapability1Image;
    buildingCapability1Image.operationKind = XGameStreamingTouchControlsStateOperationKind::Replace;
    buildingCapability1Image.path = "/buildingCapability1Image";
    buildingCapability1Image.valueKind = XGameStreamingTouchControlsStateValueKind::String;
    buildingCapability1Image.stringValue =  GetImageName(building.capability[0].id);        
    updateOperations.push_back(buildingCapability1Image);

    XGameStreamingTouchControlsStateOperation buildingCapability2Image;
    buildingCapability2Image.operationKind = XGameStreamingTouchControlsStateOperationKind::Replace;
    buildingCapability2Image.path = "/buildingCapability2Image";
    buildingCapability2Image.valueKind = XGameStreamingTouchControlsStateValueKind::String;
    buildingCapability2Image.stringValue =  GetImageName(building.capability[1].id);        
    updateOperations.push_back(buildingCapability2Image);
    
    // enable the second slot if the building is of level 3 or above, otherwise the third slot will be disabled
    XGameStreamingTouchControlsStateOperation buildingCapability2Enabled;
    buildingCapability2Enabled.operationKind = XGameStreamingTouchControlsStateOperationKind::Replace;
    buildingCapability2Enabled.path = "/buildingCapability2IsEnabled";
    buildingCapability2Enabled.valueKind = XGameStreamingTouchControlsStateValueKind::Boolean;
    buildingCapability2Enabled.booleanValue =  building.level >= 3;
    updateOperations.push_back(buildingCapability2Enabled);
  
    // Switch to the building layout with the state update being sent as well
    XGameStreamingShowTouchControlsWithStateUpdate("building", updateOperations.size(), updateOperations.data());
}

```

## 要求

**标头：** XGameStreaming.h

**库：** xgameruntime.lib\
**支持的平台**：Windows、XBOX One 系列主机和 XBOX Series 主机

## 另请参阅

[XGameStreaming](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/xgamestreaming_members.md#TouchAdaptation)\
[XGameStreamingTouchControlsStateOperationKind](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/enums/xgamestreamingtouchcontrolsstateoperationkind.md)\
[XGameStreamingTouchControlsStateOperation](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/structs/xgamestreamingtouchcontrolsstateoperation.md)\
[XGameStreamingTouchControlsStateValue](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/structs/xgamestreamingtouchcontrolsstatevalue.md)\
[XGameStreamingShowTouchControlsWithStateUpdateOnClient](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/functions/xgamestreamingshowtouchcontrolswithstateupdateonclient.md)\
[XGameStreamingUpdateTouchControlsState](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/functions/xgamestreamingupdatetouchcontrolsstate.md)\
[XGameStreamingUpdateTouchControlsStateOnClient](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/functions/xgamestreamingupdatetouchcontrolsstateonclient.md)


## Related topics

- [XGameStreamingShowTouchControlsWithStateUpdateOnClient](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/functions/xgamestreamingshowtouchcontrolswithstateupdateonclient.md)
- [XGameStreamingUpdateTouchControlsState](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/functions/xgamestreamingupdatetouchcontrolsstate.md)
- [XGameStreamingTouchControlsStateOperation](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/structs/xgamestreamingtouchcontrolsstateoperation.md)
- [XGameStreamingTouchControlsStateValue](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/structs/xgamestreamingtouchcontrolsstatevalue.md)
- [XGameStreamingTouchControlsStateOperationKind](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/enums/xgamestreamingtouchcontrolsstateoperationkind.md)