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

WorkQueue.IsMainAppThread

WorkQueue.EnsureIsMainAppThread()

WorkQueue.InvokeOnAppThread(Action)

WorkQueue.Update()

Namespace: Microsoft.MixedReality.WebRTC.Unity

Assembly: cs.temp.dll.dll

Syntax

public class PeerConnection : WorkQueue, ISerializationCallbackReceiver

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

WorkQueue.Awake()

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 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()

Implements

ISerializationCallbackReceiver