Пользовательские каналы данных с голографическим удаленным взаимодействием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 файлах самплеремотемаин. h/самплеплайермаин. 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. Как Ремотеконтекст, так и Плайерконтекст предоставляют 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. Допустимые приоритеты: Low , Medium или 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.

Чтобы зарегистрировать прослушиватель для 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. Второй параметр указывает, куда следует повторно отправить данные, пока другая сторона не подтвердит получение.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