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

# 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\*](/zh-TW/reference/system/xgamestreaming/structs/xgamestreamingtouchcontrolsstateoperation)

所有要求之狀態變數更新的陣列

### 傳回值

類型：HRESULT

如果成功，則傳回 **S\_OK**；否則傳回錯誤碼。

#### 可能的錯誤

| 錯誤碼 | 錯誤值 | 錯誤原因 |
| - | - | - |
| E\_GAMESTREAMING\_NOT\_INITIALIZED | 0x89245400 | XGameStreaming 執行階段尚未初始化。請先呼叫 [XGameStreamingInitialize](/zh-TW/reference/system/xgamestreaming/functions/xgamestreaminginitialize)，再呼叫其他 API。 |
| E\_INVALIDARG | 0x80070057 | 指定的作業所包含的資料，與作業的 [XGameStreamingTouchControlsStateValueKind](/zh-TW/reference/system/xgamestreaming/enums/xgamestreamingtouchcontrolsstatevaluekind) 中指定的資料類型不符 |

## 備註

當遊戲需要顯示特定的觸控配置，而該配置也需要某些可能影響其轉譯的狀態更新時，應使用此 API。如果您想要同時更新新觸控配置中所參考之變數的狀態，並在所有已連線的串流用戶端裝置上切換至該觸控配置，請使用此 API。此 API 可確保所有狀態更新都在顯示新配置之前完成。

如果您只想影響特定用戶端，請使用 [XGameStreamingShowTouchControlsWithStateUpdateOnClient](/zh-TW/reference/system/xgamestreaming/functions/xgamestreamingshowtouchcontrolswithstateupdateonclient)。

如果遊戲只想變更配置，則應改用 [XGameStreamingShowTouchControlLayout](/zh-TW/reference/system/xgamestreaming/functions/xgamestreamingshowtouchcontrollayout)。

如果狀態更新可能會影響目前的配置或其他配置，而且無論是否有特定的觸控配置變更都應進行更新，則遊戲應改用 [XGameStreamingUpdateTouchControlsState](/zh-TW/reference/system/xgamestreaming/functions/xgamestreamingupdatetouchcontrolsstate)。

## 範例

```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](/zh-TW/reference/system/xgamestreaming/xgamestreaming_members#TouchAdaptation)\
[XGameStreamingTouchControlsStateOperationKind](/zh-TW/reference/system/xgamestreaming/enums/xgamestreamingtouchcontrolsstateoperationkind)\
[XGameStreamingTouchControlsStateOperation](/zh-TW/reference/system/xgamestreaming/structs/xgamestreamingtouchcontrolsstateoperation)\
[XGameStreamingTouchControlsStateValue](/zh-TW/reference/system/xgamestreaming/structs/xgamestreamingtouchcontrolsstatevalue)\
[XGameStreamingShowTouchControlsWithStateUpdateOnClient](/zh-TW/reference/system/xgamestreaming/functions/xgamestreamingshowtouchcontrolswithstateupdateonclient)\
[XGameStreamingUpdateTouchControlsState](/zh-TW/reference/system/xgamestreaming/functions/xgamestreamingupdatetouchcontrolsstate)\
[XGameStreamingUpdateTouchControlsStateOnClient](/zh-TW/reference/system/xgamestreaming/functions/xgamestreamingupdatetouchcontrolsstateonclient)


## Related topics

- [XGameStreamingShowTouchControlsWithStateUpdate](/reference/system/xgamestreaming/functions/xgamestreamingshowtouchcontrolswithstateupdate.md)
- [XGameStreamingShowTouchControlsWithStateUpdateOnClient](/reference/system/xgamestreaming/functions/xgamestreamingshowtouchcontrolswithstateupdateonclient.md)