Class DataChannel

Encapsulates a data channel of a peer connection.

A data channel is a "pipe" allowing to send and receive arbitrary data to the remote peer. Data channels are based on DTLS-SRTP, and are therefore secure (encrypted). Exact security guarantees are provided by the underlying WebRTC core implementation and the WebRTC standard itself.

https://tools.ietf.org/wg/rtcweb/ https://www.w3.org/TR/webrtc/

An instance of DataChannel is created either by manually calling or one of its variants, or automatically by the implementation when a new data channel is created in-band by the remote peer (DataChannelAdded). DataChannel cannot be instantiated directly.

Inheritance

Object

DataChannel

Namespace: Microsoft.MixedReality.WebRTC

Assembly: Microsoft.MixedReality.WebRTC.dll

Syntax

public class DataChannel : object

Properties

ID

The unique identifier of the data channel in the current connection.

Declaration

public int ID { get; }

Property Value

Type	Description
Int32

Label

The data channel name in the current connection.

Declaration

public string Label { get; }

Property Value

Type	Description
String

Ordered

Indicates whether the data channel messages are ordered or not. Ordered messages are delivered in the order they are sent, at the cost of delaying later messages delivery to the application (via MessageReceived) when internally arriving out of order.

Declaration

public bool Ordered { get; }

Property Value

Type	Description
Boolean	true if messages are ordered.

See Also

Reliable

PeerConnection

The PeerConnection object this data channel was created from and is attached to.

Declaration

public PeerConnection PeerConnection { get; }

Property Value

Type	Description
PeerConnection

Reliable

Indicates whether the data channel messages are reliably delivered. Reliable messages are guaranteed to be delivered as long as the connection is not dropped. Unreliable messages may be silently dropped for whatever reason, and the implementation will not try to detect this nor resend them.

Declaration

public bool Reliable { get; }

Property Value

Type	Description
Boolean	true if messages are reliable.

See Also

Ordered

State

The channel connection state represents the connection status. Changes to this state are notified via the StateChanged event.

Declaration

public DataChannel.ChannelState State { get; }

Property Value

Type	Description
DataChannel.ChannelState	The channel connection state.

Remarks

The code handling this event should unwind the stack before using any other MR-WebRTC APIs; re-entrancy is not supported.

See Also

StateChanged

Methods

SendMessage(IntPtr, UInt64)

Send a message through the data channel. If the message cannot be sent, for example because of congestion control, it is buffered internally. If this buffer gets full, an exception is thrown and this call is aborted. The internal buffering is monitored via the BufferingChanged event.

Declaration

public void SendMessage(IntPtr message, ulong size)

Parameters

Type	Name	Description
IntPtr	message	The message to send to the remote peer.
UInt64	size	The size of the message to send in octects.

See Also

InitializeAsync(PeerConnectionConfiguration, CancellationToken)

BufferingChanged

SendMessage(Byte[])

Send a message through the data channel. If the message cannot be sent, for example because of congestion control, it is buffered internally. If this buffer gets full, an exception is thrown and this call is aborted. The internal buffering is monitored via the BufferingChanged event.

Declaration

public void SendMessage(byte[] message)

Parameters

Type	Name	Description
Byte[]	message	The message to send to the remote peer.

Exceptions

Type	Condition
DataChannelNotOpenException	The data channel is not open yet.

See Also

InitializeAsync(PeerConnectionConfiguration, CancellationToken)

BufferingChanged

SendMessageEx(DataChannel.MessageKind, IntPtr, UInt64)

Send a message through the data channel with the specified kind. If the message cannot be sent, for example because of congestion control, it is buffered internally. If this buffer gets full, an exception is thrown and this call is aborted. The internal buffering is monitored via the BufferingChanged event.

Declaration

public void SendMessageEx(DataChannel.MessageKind messageKind, IntPtr message, ulong size)

Parameters

Type	Name	Description
DataChannel.MessageKind	messageKind	The kind of message to send to the remote peer.
IntPtr	message	The message to send to the remote peer.
UInt64	size	The size of the message to send in octects.

Exceptions

Type	Condition
DataChannelNotOpenException	The data channel is not open yet.

See Also

InitializeAsync(PeerConnectionConfiguration, CancellationToken)

BufferingChanged

Events

BufferingChanged

Event triggered when the data channel buffering changes. Users should monitor this to ensure calls to SendMessage(Byte[]) do not fail. Internally the data channel contains a buffer of messages to send that could not be sent immediately, for example due to congestion control. Once this buffer is full, any further call to SendMessage(Byte[]) will fail until some messages are processed and removed to make space.

Declaration

public event DataChannel.BufferingChangedDelegate BufferingChanged

Event Type

Type	Description
DataChannel.BufferingChangedDelegate

Remarks

The code handling this event should unwind the stack before using any other MR-WebRTC APIs; re-entrancy is not supported.

See Also

SendMessage(Byte[])

MessageReceived

Event triggered when a message is received through the data channel.

Declaration

public event Action<byte[]> MessageReceived

Event Type

Type	Description
Action<Byte[]>

See Also

SendMessage(Byte[])

MessageReceivedEx

Event triggered when a message is received through the data channel, includes information if the message is binary or text.

Declaration

public event Action<DataChannel.MessageKind, byte[]> MessageReceivedEx

Event Type

Type	Description
Action<DataChannel.MessageKind, Byte[]>

See Also

SendMessage(Byte[])

MessageReceivedUnsafe

Event fires when a message is received through the data channel.

Declaration

public event Action<IntPtr, ulong> MessageReceivedUnsafe

Event Type

Type	Description
Action<IntPtr, UInt64>

See Also

SendMessage(IntPtr, UInt64)

StateChanged

Event triggered when the data channel state changes. The new state is available in State.

Declaration

public event Action StateChanged

Event Type

Type	Description
Action

Remarks

The code handling this event should unwind the stack before using any other MR-WebRTC APIs; re-entrancy is not supported.

See Also

State

See Also

DataChannelAdded