カスタムの Holographic Remoting データ チャネルCustom Holographic Remoting data channels

注意

このガイダンスは、HoloLens 2 の Holographic リモート処理に固有のものです。This guidance is specific to Holographic Remoting on HoloLens 2.

カスタムデータチャネルを使用して、確立されたリモート処理接続を介してカスタムデータを送信します。Use custom data channels to send custom data over an established remoting connection.

重要

カスタムデータチャネルでは、カスタムのリモートアプリとカスタムプレーヤーアプリが必要です。これは、2つのカスタムアプリ間の通信を可能にするためです。Custom data channels require a custom remote app and a custom player app, as it allows for communication between the two custom apps.

ヒント

単純なピンポン方の例については、 Holographic リモート処理サンプル github リポジトリ内の remote および player サンプルを参照してください。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_SAMPLESampleRemoteMain/SamplePlayerMain ファイル内のコメントを解除して、サンプルコードを有効にします。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 was successfully established, the creation of new data channels can be initiated from either the remote side and/or the player side. RemoteContext と PlayerContext はどちらも、 CreateDataChannel() これを行うための方法を提供します。Both the RemoteContext and the PlayerContext provide a CreateDataChannel() method to do this. 最初のパラメーターはチャネル ID で、後続の操作でデータチャネルを識別するために使用されます。The first parameter is the channel ID which is used to identify the data channel in subsequent operations. 2番目のパラメーターは、このチャネルのデータを相手側に転送する優先度を指定する優先順位です。The second parameter is the priority which specifies the priority with which data of this channel is transferred to the other side. チャネル Id の有効な範囲は、リモート64側の場合は63、プレーヤー側の場合は127を含む0になります。The valid range for channel IDs is 0 up to and including 63 for the remote side and 64 up to and including 127 for the player side. 有効な優先順位は Low 、、 Medium または High (両側) です。Valid priorities are Low, Medium or High (on both sides).

リモート 側でデータチャネルの作成を開始するには、次のようにします。To initiate 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 initiate 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);

注意

新しいカスタムデータチャネルを作成するには、1つの側 (リモートまたはプレーヤー) だけがメソッドを呼び出す必要があり 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.

イベントにリスナーを登録するには、次のようにし OnDataChannelCreated ます。To 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...
    });

データを受信したときに通知を受け取るには、 OnDataReceived IDataChannel ハンドラーによって提供されるオブジェクトのイベントに登録し OnDataChannelCreated ます。To 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. 2番目のパラメーターは、もう一方の側が受信を承認するまで、データを再送信する場所を指定します。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