Class PeerConnection

High-level wrapper for Unity WebRTC functionalities. This is the API entry point for establishing a connection with a remote peer.

Inheritance
Object
WorkQueue
PeerConnection
Implements
ISerializationCallbackReceiver
Inherited Members
Namespace: Microsoft.MixedReality.WebRTC.Unity
Assembly: cs.temp.dll.dll
Syntax
public class PeerConnection : WorkQueue
Remarks

The component initializes the underlying asynchronously when enabled, and closes it when disabled. The OnInitialized event is called when the connection object is ready to be used. Call StartConnection() to create an offer for a remote peer.

Fields

AutoCreateOfferOnRenegotiationNeeded

Automatically create a new offer whenever a renegotiation needed event is received.

Declaration
public bool AutoCreateOfferOnRenegotiationNeeded
Field Value
Type Description
Boolean
Remarks

Note that the renegotiation needed event may be dispatched asynchronously, so it is discourages to toggle this field ON and OFF. Instead, the user should choose an approach (manual or automatic) and stick to it.

In particular, temporarily setting this to false during a batch of changes and setting it back to true right after the last change may or may not produce an automatic offer, depending on whether the negotiated event was dispatched while the property was still false or not.

AutoLogErrorsToUnityConsole

Flag to log all errors to the Unity console automatically.

Declaration
public bool AutoLogErrorsToUnityConsole
Field Value
Type Description
Boolean

IceCredential

Optional credential for the ICE servers.

Declaration
public string IceCredential
Field Value
Type Description
String

IceServers

Set of ICE servers the WebRTC library will use to try to establish a connection.

Declaration
public List<ConfigurableIceServer> IceServers
Field Value
Type Description
List<ConfigurableIceServer>

IceUsername

Optional username for the ICE servers.

Declaration
public string IceUsername
Field Value
Type Description
String

OnError

Event that occurs when a WebRTC error occurs

Declaration
public WebRTCErrorEvent OnError
Field Value
Type Description
WebRTCErrorEvent

OnInitialized

Event fired after the peer connection is initialized and ready for use.

Declaration
public UnityEvent OnInitialized
Field Value
Type Description
UnityEvent

OnShutdown

Event fired after the peer connection is shut down and cannot be used anymore.

Declaration
public UnityEvent OnShutdown
Field Value
Type Description
UnityEvent

Properties

Peer

Retrieves the underlying peer connection object once initialized.

Declaration
public PeerConnection Peer { get; }
Property Value
Type Description
PeerConnection
Remarks

If OnInitialized has not fired, this will be null.

Methods

AddMediaLine(MediaKind)

Add a new media line of the given kind.

This method creates a media line, which expresses an intent from the user to get a transceiver. The actual object creation is delayed until a session negotiation is completed.

Once the media line is created, the user can then assign its Source and Receiver properties to express their intent to send and/or receive some media through the transceiver that will be associated with that media line once a session is negotiated. This information is used in subsequent negotiations to derive a to negotiate. Therefore users should avoid modifying the property manually when using the Unity library, and instead modify the Source and Receiver properties.

Declaration
public MediaLine AddMediaLine(MediaKind kind)
Parameters
Type Name Description
MediaKind kind

The kind of media (audio or video) for the transceiver.
Returns
Type Description
MediaLine

A newly created media line, which will be associated with a transceiver once the next session is negotiated.

Awake()

Declaration
protected override void Awake()
Overrides

GetVideoCaptureDevicesAsync()

Enumerate the video capture devices available as a WebRTC local video feed source.

Declaration
public static Task<IReadOnlyList<VideoCaptureDevice>> GetVideoCaptureDevicesAsync()
Returns
Type Description
Task<IReadOnlyList<VideoCaptureDevice>>

The list of local video capture devices available to WebRTC.

HandleConnectionMessageAsync(SdpMessage)

Pass the given SDP description received from the remote peer via signaling to the underlying WebRTC implementation, which will parse and use it.

This must be called by the signaler when receiving a message. Once this operation has completed, it is safe to call .

IMPORTANT

This method is very similar to the SetRemoteDescriptionAsync() method available in the underlying C# library, and actually calls it. However it also performs additional work in order to pair the transceivers of the local and remote peer. Therefore Unity applications must call this method instead of the C# library one to ensure transceiver pairing works as intended.

Declaration
public async Task HandleConnectionMessageAsync(SdpMessage message)
Parameters
Type Name Description
SdpMessage message

The SDP message to handle.
Returns
Type Description
Task

A task which completes once the remote description has been applied and transceivers have been updated.
Remarks

This method can only be called from the main Unity application thread, where Unity objects can be safely accessed.

OnAfterDeserialize()

Declaration
public void OnAfterDeserialize()

OnBeforeSerialize()

Declaration
public void OnBeforeSerialize()

StartConnection()

Create a new connection offer, either for a first connection to the remote peer, or for renegotiating some new or removed transceivers.

This method submits an internal task to create an SDP offer message. Once the message is created, the implementation raises the event to allow the user to send the message via the chosen signaling solution to the remote peer.

IMPORTANT

This method is very similar to the CreateOffer() method available in the underlying C# library, and actually calls it. However it also performs additional work in order to pair the transceivers of the local and remote peer. Therefore Unity applications must call this method instead of the C# library one to ensure transceiver pairing works as intended.

Declaration
public bool StartConnection()
Returns
Type Description
Boolean

true if the offer creation task was submitted successfully, and false otherwise. The offer SDP message is always created asynchronously.
Remarks

This method can only be called from the main Unity application thread, where Unity objects can be safely accessed.

StartConnectionIgnoreError()

Call StartConnection() and discard the result. Can be wired to a .

Declaration
public void StartConnectionIgnoreError()

Update()

Declaration
protected override void Update()
Overrides

Implements

ISerializationCallbackReceiver