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

# XGameStreamingUpdateTouchControlsState

> XGameStreamingUpdateTouchControlsState

# XGameStreamingUpdateTouchControlsState

在所有串流用戶端上更新觸控配置可用來改變其行為的狀態。目前顯示的觸控控制項組合的任何視覺變更，都會在「所有」變數更新之後才進行。

## 語法

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

### 參數

*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) 中指定的資料類型不符 |

## 備註

串流用戶端使用的觸控配置可以相依於狀態，而狀態的初始值內嵌於觸控配置套件組合中。遊戲可以更新狀態，進而使目前向玩家顯示的配置產生變更。

遊戲可以使用 `XGameStreamingUpdateTouchControlsState` 更新所有已連線用戶端的狀態，或使用 [XGameStreamingUpdateTouchControlsStateOnClient](/zh-TW/reference/system/xgamestreaming/functions/xgamestreamingupdatetouchcontrolsstateonclient) 更新特定已連線用戶端的狀態。

如果遊戲需要同時更新狀態「並」變更配置，可以使用 [XGameStreamingShowTouchControlsWithStateUpdate](/zh-TW/reference/system/xgamestreaming/functions/xgamestreamingshowtouchcontrolswithstateupdate) 或 [XGameStreamingShowTouchControlsWithStateUpdateOnClient](/zh-TW/reference/system/xgamestreaming/functions/xgamestreamingshowtouchcontrolswithstateupdateonclient)。

## 範例

```C++ theme={null}
// In this example, after the player has switched their active weapon - update the image of the fire
// button to match the current weapon and set the enabled state of reload based on whether the player has
// extra magazines.  
// 
// Assumes passing in game structure that includes the active weapon with appropriate state.  
//
// Assumes a game speciic GetImageName function which returns a constant string for the specified weapoon


void GameStreamingClientManager::UpdateStateAfterWeaponChange(const playerWeapon& playerWeapon)
{
    // create an update for the active weapon's image
    XGameStreamingTouchControlsStateOperation weaponImage;
    weaponImage.operationKind = XGameStreamingTouchControlsStateOperationKind::Replace;
    weaponImage.path = "/ActiveWeaponImage";
    weaponImage.value.valueKind = XGameStreamingTouchControlsStateValueKind::String;
    weaponImage.value.stringValue = GetImageName(playerWeapon.activeWeapon.id);

    // create an update for whether the reload button should be enabled
    XGameStreamingTouchControlsStateOperation reloadEnabled;
    reloadEnabled.operationKind = XGameStreamingTouchControlsStateOperationKind::Replace;
    reloadEnabled.path = "/ReloadEnabled";
    reloadEnabled.valueKind = XGameStreamingTouchControlsStateValueKind::Bool;
    reloadEnabled.booleanValue = playerWeapon.activeWeapon.reloadClips > 0;

    // combine all the updates into the update state call and make the call
    XGameStreamingTouchControlsStateOperation[2] updateOperations = {weaponImage, reloadEnabled};
    
    XGameStreamingUpdateTouchControlsState(updateOperations, _countof(updateOperations));
}
```

```c++ theme={null}
// In this example, after the player has gone to their inventory screen and had the ability to apply items
// to two active slots. Update the state for layouts to have layouts match the player's current
// loaded items from inventory (may or may not be the current layout being displayed).
// 
// Assumes passing in game structure that includes the player's active inventory


void GameStreamingClientManager::AfterInventoryScreen(const PlayerInventory& playerInventory)
{
    std::vector<XGameStreamingTouchControlsStateOperation> updateOperations;
    
    // check the first inventory slots, if empty hide that button from the layout
    // if item is placed in that slot, update the image to match the inventory items
    
    XGameStreamingTouchControlsStateOperation slot1Visible;
    slot1Visible.operationKind = XGameStreamingTouchControlsStateOperationKind::Replace;
    slot1Visible.path = "/Slot1IsVisible";
    slot1Visible.valueKind = XGameStreamingTouchControlsStateValueKind::Boolean;
    slot1Visible.boolValue =  playerInventory.slot1 != nullptr;
    
    updateOperations.push_back(slot1Visible);

    if (playerInventory.slot1 != nullptr) 
    {
        // create an update for the active weapon's image
        XGameStreamingTouchControlsStateOperation slot1Image;
        slot1Image.operationKind = XGameStreamingTouchControlsStateOperationKind::Replace;
        slot1Image.path = "/Slot1Image";
        slot1Image.value.valueKind = XGameStreamingTouchControlsStateValueKind::String;
        slot1Image.value.stringValue = GetImageName(playerInventory.slot1.id);        
        updateOperations.pushBack(slot1Image);
    }
    

    // ... 
    // do the same for the second inventory spot
    // ...

    // Update the state so that layouts will be updated correctly
    XGameStreamingUpdateTouchControlsState(updateOperations.data(), updateOperations.size());
}

```

## 需求

**標頭：** 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)\
[XGameStreamingShowTouchControlsWithStateUpdate](/zh-TW/reference/system/xgamestreaming/functions/xgamestreamingshowtouchcontrolswithstateupdate)\
[XGameStreamingShowTouchControlsWithStateUpdateOnClient](/zh-TW/reference/system/xgamestreaming/functions/xgamestreamingshowtouchcontrolswithstateupdateonclient)\
[XGameStreamingUpdateTouchControlsStateOnClient](/zh-TW/reference/system/xgamestreaming/functions/xgamestreamingupdatetouchcontrolsstateonclient)


## Related topics

- [XGameStreamingUpdateTouchControlsState](/ko/reference/system/xgamestreaming/functions/xgamestreamingupdatetouchcontrolsstate.md)
- [XGameStreamingUpdateTouchControlsStateOnClient](/ko/reference/system/xgamestreaming/functions/xgamestreamingupdatetouchcontrolsstateonclient.md)