自訂全像攝影遠端資料通道Custom Holographic Remoting data channels

注意

本指南專為 HoloLens 2 上的全像攝影遠端所特有。This guidance is specific to Holographic Remoting on HoloLens 2.

使用自訂資料通道,透過已建立的遠端連線來傳送自訂資料。Use custom data channels to send custom data over an established remoting connection.

重要

自訂資料通道需要自訂遠端應用程式和自訂播放機應用程式,因為它允許在兩個自訂應用程式之間進行通訊。Custom data channels require a custom remote app and a custom player app, as it allows for communication between the two custom apps.

提示

簡單的乒乓球範例可在「全像遠端」 範例 github 存放庫內的遠端和播放機範例中找到。A simple ping-pong example can be found in the remote and player samples inside the Holographic Remoting samples github repository. #define ENABLE_CUSTOM_DATA_CHANNEL_SAMPLE SampleRemoteMain .h/SamplePlayerMain .h 檔案內取消批註,以啟用範例程式碼。Uncomment #define ENABLE_CUSTOM_DATA_CHANNEL_SAMPLE inside the SampleRemoteMain.h / SamplePlayerMain.h files to enable the sample code.

建立自訂資料通道Create a custom data channel

若要建立自訂資料通道,需要下欄欄位:To create a custom data channel, the following fields are required:

std::recursive_mutex m_customDataChannelLock;
winrt::Microsoft::Holographic::AppRemoting::IDataChannel m_customDataChannel = nullptr;
winrt::Microsoft::Holographic::AppRemoting::IDataChannel::OnDataReceived_revoker m_customChannelDataReceivedEventRevoker;
winrt::Microsoft::Holographic::AppRemoting::IDataChannel::OnClosed_revoker m_customChannelClosedEventRevoker;

成功建立連接之後,您可以從遠端端、播放程式端或兩者建立新的資料通道。After a connection is successfully established, you can create new data channels from either the remote side, the player side, or both. RemoteCoNtext 和 PlayerCoNtext 都提供 CreateDataChannel() 建立資料通道的方法。Both the RemoteContext and the PlayerContext provide a CreateDataChannel() method for creating data channels. 第一個參數是通道識別碼,用來識別後續作業中的資料通道。The first parameter is the channel ID, which is used to identify the data channel in subsequent operations. 第二個參數是優先順序,可指定此通道的資料會傳送到另一端的優先順序。The second parameter is the priority, which specifies the priority with which data of this channel is transferred to the other side. 遠端端的有效通道識別碼是從0到(含)(包括63)和64(最高),並包含玩家端的127。Valid channel IDs on the remote side are from 0 up to and including 63, and 64 up to and including 127 for the player side. 有效的優先順序 LowMedium) 兩側的、或 High (。Valid priorities are Low, Medium, or High (on both sides).

若要開始在 遠端 建立資料通道:To start the creation of a data channel on the remote side:

// Valid channel ids for channels created on the remote side are 0 up to and including 63
m_remoteContext.CreateDataChannel(0, DataChannelPriority::Low);

若要開始在 播放 程式端建立資料通道:To start the creation of a data channel on the player side:

// Valid channel ids for channels created on the player side are 64 up to and including 127
m_playerContext.CreateDataChannel(64, DataChannelPriority::Low);

注意

若要建立新的自訂資料通道, (遠端或玩家) 只需要呼叫 CreateDataChannel 方法。To create a new custom data channel, only one side (either remote or player) needs to call the CreateDataChannel method.

處理自訂資料通道事件Handling custom data channel events

若要建立自訂資料通道, OnDataChannelCreated 必須在播放玩家和遠端端) (處理事件。To establish a custom data channel, the OnDataChannelCreated event needs to be handled (on both the player and the remote side). 它會在使用者資料通道由任一端建立時觸發,並提供 IDataChannel 可用於透過此通道傳送及接收資料的物件。It triggers when a user data channel has been created by either side and provides a IDataChannel object, which can be used to send and receive data over this channel.

若要在事件上註冊接聽程式 OnDataChannelCreatedTo register a listener on the OnDataChannelCreated event:

m_onDataChannelCreatedEventRevoker = m_remoteContext.OnDataChannelCreated(winrt::auto_revoke,
    [this](const IDataChannel& dataChannel, uint8_t channelId)
    {
        std::lock_guard lock(m_customDataChannelLock);
        m_customDataChannel = dataChannel;

        // Register to OnDataReceived and OnClosed event of the data channel here, see below...
    });

若要在收到資料時收到通知,請 OnDataReceivedIDataChannel 處理常式所提供的物件上註冊事件 OnDataChannelCreatedTo get notified when data is received, register to the OnDataReceived event on the IDataChannel object provided by the OnDataChannelCreated handler. 註冊至 OnClosed 事件,以在資料通道關閉時收到通知。Register to the OnClosed event, to get notified when the data channel has been closed.

m_customChannelDataReceivedEventRevoker = m_customDataChannel.OnDataReceived(winrt::auto_revoke, 
    [this]()
    {
        // React on data received via the custom data channel here.
    });

m_customChannelClosedEventRevoker = m_customDataChannel.OnClosed(winrt::auto_revoke,
    [this]()
    {
        // React on data channel closed here.

        std::lock_guard lock(m_customDataChannelLock);
        if (m_customDataChannel)
        {
            m_customDataChannel = nullptr;
        }
    });

傳送資料Sending data

若要透過自訂資料通道傳送資料,請使用 IDataChannel::SendData() 方法。To send data over a custom data channel, use the IDataChannel::SendData() method. 第一個參數是 winrt::array_view<const uint8_t> 應該傳送之資料的。The first parameter is a winrt::array_view<const uint8_t> to the data that should be send. 第二個參數會指定應重新傳送資料的位置,直到另一端認可接收為止。The second parameter specifies where the data should be resend, until the other side acknowledge the reception.

重要

如果網路狀況不佳,則相同的資料封包可能會抵達一次以上。In case of bad network conditions, the same data packet might arrive more than once. 接收端程式碼必須能夠處理這種情況。The receiving code must be able to handle this situation.

uint8_t data[] = {1};
m_customDataChannel.SendData(data, true);

關閉自訂資料通道Closing a custom data channel

若要關閉自訂資料通道,請使用 IDataChannel::Close() 方法。To close a custom data channel, use the IDataChannel::Close() method. OnClosed當自訂資料通道關閉之後,事件就會通知雙方。Both sides will be notified by the OnClosed event once the custom data channel has been closed.

m_customDataChannel.Close();

另請參閱See Also