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

# XGameStreamingRegisterConnectionStateChanged

> XGameStreamingRegisterConnectionStateChanged

# XGameStreamingRegisterConnectionStateChanged

註冊在串流用戶端裝置的連線狀態變更時要叫用的回呼。註冊時，將會針對所有已連線的串流用戶端裝置叫用回呼。

## 語法

```cpp theme={null}
HRESULT XGameStreamingRegisterConnectionStateChanged(  
         XTaskQueueHandle queue,  
         void* context,  
         XGameStreamingConnectionStateChangedCallback* callback,  
         XTaskQueueRegistrationToken* token  
)  
```

### 參數

*queue*   \_In\_opt\_\
類型：XTaskQueueHandle

要放置變更回呼之非同步佇列的控制代碼。

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

傳遞給回呼函式之內容的選擇性指標。

*callback*   \_In\_\
類型：XGameStreamingConnectionStateChangedCallback\*

任何串流用戶端裝置的連線狀態變更時將叫用的回呼函式。

*token*   \_Out\_\
類型：XTaskQueueRegistrationToken\*

註冊權杖的指標，可用來取消註冊事件。

### 傳回值

類型：HRESULT

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

#### 可能的錯誤

| 錯誤碼 | 錯誤值 | 錯誤原因 |
| - | - | - |
| E\_GAMESTREAMING\_NOT\_INITIALIZED | 0x89245400 | XGameStreaming 執行階段尚未初始化。請先呼叫 [XGameStreamingInitialize](/zh-TW/reference/system/xgamestreaming/functions/xgamestreaminginitialize)，再呼叫其他 API。 |

如需錯誤碼清單，請參閱[錯誤碼](/zh-TW/reference/errorcodes)。

## 備註

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

建議使用此 API 讓遊戲針對每個串流用戶端裝置進行自訂，並維護狀態，讓遊戲能根據是否有任何裝置連線來最佳化體驗。

<Note>註冊時，將會針對目前已連線的所有串流用戶端裝置叫用回呼。</Note>

## 範例

```cpp theme={null}
    // Called during game startup to hook into any game streaming start/stop events
    void SetupStreamAware()
    {
        // Register a callback for client connections and disconnections. Note that the connection callback
        // will fire for any already connected clients, so do all of our per-client setup in that callback.      
        XGameStreamingConnectionStateChangedRegistrationToken stateChangeToken = {0};
        XGameStreamingRegisterConnectionStateChanged(
            m_taskQueue, this, ConnectionStateChangedCallback, &stateChangeToken);
    }

    static void ConnectionStateChangedCallback(void* context, XGameStreamingClientId client, XGameStreamingConnectionState state)
    {
        static_cast<Game*>(context)->OnConnectionStateChanged(client, state);
    }

    void OnConnectionStateChanged(XGameStreamingClientId client, XGameStreamingConnectionState state)
    {
        switch (state)
        {
        case XGameStreamingConnectionState::Connected: 
            OnClientConnected(client); 
            break;
        case XGameStreamingConnectionState::Disconnected: 
            OnClientDisconnected(client); 
            break;
        default: 
            break;
        }
    }


    void OnClientConnected(XGameStreamingClientId client)
    {
        // Update list of connected clients
        m_streamingClients.push_back(client);

        // Do per-client initialization
        // ...
    }

    void OnClientDisconnected(XGameStreamingClientId client)
    {
        // Release our reference on the client that is no longer streaming the game
        std::remove(m_streamingClients.begin(), m_streamingClients.end(), client);

        // Do per-client cleanup
        // ...
    }



```

## 需求

**標頭：** xgamestreaming.h

**程式庫：** xgameruntime.lib

**支援的平台：** Windows、XBOX One 系列主機和 XBOX Series 主機

## 概念文件

* [雲端感知 API 呼叫](/zh-TW/build/core-features/common/game-streaming/game-streaming-am-i-streaming)
* [時間敏感的執行緒](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## 另請參閱

[XGameStreamingConnectionState](/zh-TW/reference/system/xgamestreaming/enums/xgamestreamingconnectionstate)\
[XGameStreamingConnectionStateChangedCallback](/zh-TW/reference/system/xgamestreaming/functions/xgamestreamingconnectionstatechangedcallback)\
[XGameStreamingUnregisterConnectionStateChanged](/zh-TW/reference/system/xgamestreaming/functions/xgamestreamingunregisterconnectionstatechanged)\
[XGameStreaming](/zh-TW/reference/system/xgamestreaming/xgamestreaming_members)


## Related topics

- [XGameStreamingUnregisterConnectionStateChanged](/zh-TW/reference/system/xgamestreaming/functions/xgamestreamingunregisterconnectionstatechanged.md)
- [XGameStreamingConnectionStateChangedCallback](/zh-TW/reference/system/xgamestreaming/functions/xgamestreamingconnectionstatechangedcallback.md)
- [XGameStreamingConnectionState](/zh-TW/reference/system/xgamestreaming/enums/xgamestreamingconnectionstate.md)
- [XGameStreamingIsStreaming](/zh-TW/reference/system/xgamestreaming/functions/xgamestreamingisstreaming.md)
- [XGameStreamingGetConnectionState](/zh-TW/reference/system/xgamestreaming/functions/xgamestreaminggetconnectionstate.md)