Class Transceiver

Transceiver of a peer connection.

A transceiver is a media "pipe" connecting the local and remote peers, and used to transmit media data (audio or video) between the peers. The transceiver has a media flow direction indicating whether it is sending and/or receiving any media, or is inactive. When sending some media, the transceiver's local track is used as the source of that media. Conversely, when receiving some media, that media is delivered to the remote media track of the transceiver. As a convenience, the local track can be null if the local peer does not have anything to send. In that case some empty media is automatically sent instead (black frames for video, silence for audio) at very reduced rate. To completely stop sending, the media direction must be changed instead.

Transceivers are owned by the peer connection which creates them, and cannot be destroyed nor removed from the peer connection. They become invalid when the peer connection is closed, and should not be used after that.

Inheritance

Object

Transceiver

Namespace: Microsoft.MixedReality.WebRTC

Assembly: Microsoft.MixedReality.WebRTC.dll

Syntax

public class Transceiver : object

Remarks

This object corresponds roughly to the same-named notion in the WebRTC 1.0 standard when using the Unified Plan SDP semantic.

For Plan B semantic, where RTP transceivers are not available, this wrapper tries to emulate the transceiver concept of the Unified Plan semantic, and is therefore providing an abstraction over the WebRTC concept of transceivers.

Fields

_desiredDirection

Backing field for DesiredDirection.

Declaration

protected Transceiver.Direction _desiredDirection

Field Value

Type	Description
Transceiver.Direction

See Also

DesiredDirection

Properties

DesiredDirection

Transceiver direction desired by the user.

Once changed by the user, this value is the next direction that will be negotiated when calling CreateOffer() or CreateAnswer().

After the negotiation is completed, this is generally equal to NegotiatedDirection, unless the offer was partially rejected, for example if the local peer offered to send and receive some media but the remote peer only accepted to receive.

Changing the value of this property triggers a RenegotiationNeeded event.

Declaration

public Transceiver.Direction DesiredDirection { get; set; }

Property Value

Type	Description
Transceiver.Direction

See Also

NegotiatedDirection

LocalAudioTrack

Local audio track attached to the transceiver, if MediaKind is Audio.

The property has two uses:

• as a convenience getter to retrieve LocalTrack already cast to a LocalAudioTrack type, or null if the transceiver media kind is Video.
• to attach a new local audio track if the transceiver is an audio transceiver; otherwise this throws a .

Declaration

public LocalAudioTrack LocalAudioTrack { get; set; }

Property Value

Type	Description
LocalAudioTrack

LocalTrack

Local track attached to the transceiver, which is used to send data to the remote peer if NegotiatedDirection includes sending. This cannot be assigned directly; instead use LocalAudioTrack or LocalVideoTrack depending on the media kind of the transceiver.

Declaration

public LocalMediaTrack LocalTrack { get; }

Property Value

Type	Description
LocalMediaTrack

See Also

LocalAudioTrack

LocalVideoTrack

LocalVideoTrack

Local video track attached to the transceiver, if MediaKind is Video.

The property has two uses:

• as a convenience getter to retrieve LocalTrack already cast to a LocalVideoTrack type, or null if the transceiver media kind is Audio.
• to attach a new local video track if the transceiver is a video transceiver; otherwise this throws a .

Declaration

public LocalVideoTrack LocalVideoTrack { get; set; }

Property Value

Type	Description
LocalVideoTrack

MediaKind

Type of media carried by the transceiver, and by extension type of media of its tracks.

Declaration

public MediaKind MediaKind { get; }

Property Value

Type	Description
MediaKind

MlineIndex

Index of the media line in the SDP protocol for this transceiver. If the transceiver is not yet associated with a media line, this index has a negative value (invalid). Transceivers are associated when an offer, local or remote, is applied to the local peer connection. Consequently, transceivers created as a result of applying a remote offer are created in an associated state, with a media line index already valid, while transceivers created locally by the peer connection have an invalid index until the next offer.

Declaration

public int MlineIndex { get; }

Property Value

Type	Description
Int32

Remarks

For Plan B semantic (PlanB), the media line index is not present in the SDP protocol. Instead it is simulated by the implementation, which attempts to emulate the behavior of the Unified Plan semantic over an actual Plan B protocol.

See Also

Associated

Name

A name for the transceiver, used for logging and debugging only. This can be set on construction if the transceiver is created by the local peer using AddTransceiver(MediaKind, TransceiverInitSettings), or will be generated by the implementation otherwise. There is no guarantee of unicity; this name is only informational.

Declaration

public string Name { get; }

Property Value

Type	Description
String

NegotiatedDirection

Last negotiated transceiver direction. This is constant when changing DesiredDirection, and is only udpated after an SDP session negotiation. This might be different from the desired direction if for example the local peer asked to receive but the remote peer refused. This is the actual direction the media is effectively transported in at any point in time.

Declaration

public Transceiver.Direction? NegotiatedDirection { get; protected set; }

Property Value

Type	Description
Nullable<Transceiver.Direction>

See Also

DesiredDirection

PeerConnection

Peer connection this transceiver is part of.

Declaration

public PeerConnection PeerConnection { get; }

Property Value

Type	Description
PeerConnection

See Also

PeerConnection

RemoteAudioTrack

Remote audio track attached to the transceiver, if MediaKind is Audio. This is equivalent to RemoteTrack for audio transceivers, and null otherwise.

Declaration

public RemoteAudioTrack RemoteAudioTrack { get; }

Property Value

Type	Description
RemoteAudioTrack

RemoteTrack

Remote track attached to the transceiver, which is used to receive data from the remote peer if NegotiatedDirection includes receiving. This cannot be assigned. This is updated automatically when the remote track is created or destroyed as part of a renegotiation.

Declaration

public MediaTrack RemoteTrack { get; }

Property Value

Type	Description
MediaTrack

See Also

RemoteAudioTrack

RemoteVideoTrack

RemoteVideoTrack

Remote video track attached to the transceiver, if MediaKind is Video. This is equivalent to RemoteTrack for video transceivers, and null otherwise.

Declaration

public RemoteVideoTrack RemoteVideoTrack { get; }

Property Value

Type	Description
RemoteVideoTrack

StreamIDs

List of stream IDs associated with the transceiver.

Declaration

public string[] StreamIDs { get; }

Property Value

Type	Description
String[]

Methods

DirectionFromSendRecv(Boolean, Boolean)

Compute a transceiver direction from some send/receive booleans.

Declaration

public static Transceiver.Direction DirectionFromSendRecv(bool hasSend, bool hasRecv)

Parameters

Type	Name	Description
Boolean	hasSend	Does the direction includes sending?
Boolean	hasRecv	Does the direction includes receiving?

Returns

Type	Description
Transceiver.Direction	The computed transceiver direction.

HasRecv(Transceiver.Direction)

Check whether the given direction includes receiving.

Declaration

public static bool HasRecv(Transceiver.Direction dir)

Parameters

Type	Name	Description
Transceiver.Direction	dir	The direction to check.

Returns

Type	Description
Boolean	true if direction is ReceiveOnly or SendReceive.

HasRecv(Nullable<Transceiver.Direction>)

Check whether the given direction includes receiving.

Declaration

public static bool HasRecv(Transceiver.Direction? dir)

Parameters

Type	Name	Description
Nullable<Transceiver.Direction>	dir	The direction to check.

Returns

Type	Description
Boolean	true if direction is ReceiveOnly or SendReceive.

HasSend(Transceiver.Direction)

Check whether the given direction includes sending.

Declaration

public static bool HasSend(Transceiver.Direction dir)

Parameters

Type	Name	Description
Transceiver.Direction	dir	The direction to check.

Returns

Type	Description
Boolean	true if direction is SendOnly or SendReceive.

HasSend(Nullable<Transceiver.Direction>)

Check whether the given direction includes sending.

Declaration

public static bool HasSend(Transceiver.Direction? dir)

Parameters

Type	Name	Description
Nullable<Transceiver.Direction>	dir	The direction to check.

Returns

Type	Description
Boolean	true if direction is SendOnly or SendReceive.

Events

Associated

Event raised when the transceiver is associated with a media line, which therefore makes the MlineIndex property take a valid positive value.

Declaration

public event TransceiverAssociatedDelegate Associated

Event Type

Type	Description
TransceiverAssociatedDelegate

Remarks

The event is not raised if the transceiver is created in an associated state, that is if the transceiver is already associated when TransceiverAdded is raised to signal it was added. This happens when the transceiver is created as part of applying a remote offer. In short, this event is raised only for transceivers created locally with AddTransceiver(MediaKind, TransceiverInitSettings).

See Also

MlineIndex

DirectionChanged

Event raised when the NegotiatedDirection changed, which occurs after applying a local or remote description. This is a convenience event raised only when the direction effectively changed, to avoid having to parse all transceivers for change after each description was applied.

Declaration

public event TransceiverDirectionChangedDelegate DirectionChanged

Event Type

Type	Description
TransceiverDirectionChangedDelegate

See Also

AddTransceiver(MediaKind, TransceiverInitSettings)

Close()