Class RTCPeerConnection

Namespace

CSharpToJavaScript.APIs.JS

Assembly

CSharpToJavaScript.dll

The RTCPeerConnection interface represents a WebRTC connection between the local computer and a remote peer.
It provides methods to connect to a remote peer, maintain and monitor the connection, and close the connection once it's no longer needed.

[Value("RTCPeerConnection")]
public class RTCPeerConnection : EventTarget

Inheritance

object

EventTarget

RTCPeerConnection

Inherited Members

EventTarget.AddEventListener(string, Action, Union26)

EventTarget.AddEventListener(string, Action<MouseEvent>, Union26)

EventTarget.AddEventListener(string, Action<Event>, Union26)

EventTarget.RemoveEventListener(string, Action, Union27)

EventTarget.AddEventListener(string, EventListener, Union26)

EventTarget.RemoveEventListener(string, EventListener, Union27)

EventTarget.DispatchEvent(Event)

EventTarget.When(string, ObservableEventListenerOptions)

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

-https://github.com/jesup/nightly-gupshup/blob/master/static/js/chat.js
-Get started with WebRTC
-TutorRoom: Node.js HTML video capture, peer-to-peer video and file sharing application (source on GitHub)

See also on MDN

Constructors

RTCPeerConnection()

public RTCPeerConnection()

RTCPeerConnection(RTCConfiguration)

The RTCPeerConnection() constructor returns a newly-created RTCPeerConnection, which represents a connection between the local device and a remote peer.

public RTCPeerConnection(RTCConfiguration configuration = null)

Parameters

configuration RTCConfiguration

Remarks

-Signaling and video calling
-WebRTC architecture overview
-Lifetime of a WebRTC session
-RTCPeerConnection

See also on MDN

Properties

CanTrickleIceCandidates

The canTrickleIceCandidates read-only property of the RTCPeerConnection interface returns a boolean value which indicates whether or not the remote peer can accept trickled ICE candidates.

[Value("canTrickleIceCandidates")]
public bool? CanTrickleIceCandidates { get; }

Property Value

bool?

A boolean value that is true if the remote peer can accept trickled ICE candidates and false if it cannot.
If no remote peer has been established, this value is null.

NOTE

This property's value is determined once the local peer has called SetRemoteDescription(RTCSessionDescriptionInit);
the provided description is used by the ICE agent to determine whether or not the remote peer supports trickled ICE candidates.

Remarks

ICE trickling is the process of continuing to send candidates after the initial offer or answer has already been sent to the other peer.

This property is only set after having called SetRemoteDescription(RTCSessionDescriptionInit). Ideally, your signaling protocol provides a way to detect trickling support, so that you don't need to rely on this property.
A WebRTC browser will always support trickle ICE. If trickling isn't supported, or you aren't able to tell, you can check for a falsy value for this property and then wait until the value of IceGatheringState changes to "completed" before creating and sending the initial offer.
That way, the offer contains all of the candidates.

-WebRTC
-AddIceCandidate(RTCIceCandidateInit)
-Lifetime of a WebRTC session

See also on MDN

ConnectionState

The connectionState read-only property of the RTCPeerConnection interface indicates the current state of the peer connection by returning one of the following string values: new, connecting, connected, disconnected, failed, or closed.

[Value("connectionState")]
public RTCPeerConnectionState ConnectionState { get; }

Property Value

RTCPeerConnectionState

A string representing the current state of the connection.
This can take on of the following values:

Remarks

This state essentially represents the aggregate state of all ICE transports (which are of type RTCIceTransport or RTCDtlsTransport) being used by the connection.

When this property's value changes, a RTCPeerConnection.Connectionstatechange event is sent to the RTCPeerConnection instance.

-Lifetime of a WebRTC session
-RTCPeerConnection
-RTCPeerConnection.Connectionstatechange
-State
-WebRTC

See also on MDN

CurrentLocalDescription

The currentLocalDescription read-only property of the RTCPeerConnection interface returns an RTCSessionDescription object describing the local end of the connection as it was most recently successfully negotiated since the last time the RTCPeerConnection finished negotiating and connecting to a remote peer.
Also included is a list of any ICE candidates that may already have been generated by the ICE agent since the offer or answer represented by the description was first instantiated.

[Value("currentLocalDescription")]
public RTCSessionDescription? CurrentLocalDescription { get; }

Property Value

RTCSessionDescription

The current description of the local end of the connection, if one has been set.
If none has been successfully set, this value is null.

Remarks

To change the currentLocalDescription, call SetLocalDescription(RTCLocalSessionDescriptionInit), which triggers a series of events which leads to this value being set.
For details on what exactly happens and why the change isn&apos;t necessarily instantaneous, see Pending and current descriptions in the WebRTC Connectivity page.

NOTE

Unlike LocalDescription, this value represents the actual current state of the local end of the connection;
localDescription may specify a description which the connection is currently in the process of switching over to.

-SetLocalDescription(RTCLocalSessionDescriptionInit), PendingLocalDescription, LocalDescription
-SetRemoteDescription(RTCSessionDescriptionInit), RemoteDescription, PendingRemoteDescription, CurrentRemoteDescription
-WebRTC

See also on MDN

CurrentRemoteDescription

The currentRemoteDescription read-only property of the RTCPeerConnection interface returns an
RTCSessionDescription object describing the remote end of the connection as it was most recently successfully negotiated since the last time the RTCPeerConnection finished negotiating and connecting to a remote peer.
Also included is a list of any ICE candidates that may already have been generated by the ICE agent since the offer or answer represented by the description was first instantiated.

[Value("currentRemoteDescription")]
public RTCSessionDescription? CurrentRemoteDescription { get; }

Property Value

RTCSessionDescription

The current description of the remote end of the connection, if one has been set.
If none has been successfully set, this value is null.

Remarks

To change the currentRemoteDescription, call SetRemoteDescription(RTCSessionDescriptionInit), which triggers a series of events which leads to this value being set.
For details on what exactly happens and why the change isn&apos;t necessarily instantaneous, see Pending and current descriptions in the WebRTC Connectivity page.

NOTE

Unlike RemoteDescription, this value represents the actual current state of the local end of the connection;
remoteDescription may specify a description which the connection is currently in the process of switching over to.

-SetRemoteDescription(RTCSessionDescriptionInit), PendingRemoteDescription, RemoteDescription
-SetRemoteDescription(RTCSessionDescriptionInit), RemoteDescription, PendingRemoteDescription
-WebRTC

See also on MDN

IceConnectionState

The iceConnectionState read-only property of the RTCPeerConnection interface returns a string which state of the {{Glossary("ICE")}} agent associated with the RTCPeerConnection: new, checking, connected, completed, failed, disconnected, and closed.

[Value("iceConnectionState")]
public RTCIceConnectionState IceConnectionState { get; }

Property Value

RTCIceConnectionState

The current state of the ICE agent and its connection. The value is one of the following strings:

Remarks

It describes the current state of the ICE agent and its connection to the ICE server;
that is, the STUN or TURN server.

You can detect when this value has changed by watching for the RTCPeerConnection.Iceconnectionstatechange event.

-WebRTC API
-RTCPeerConnection.Iceconnectionstatechange
-RTCPeerConnection

See also on MDN

IceGatheringState

The iceGatheringState read-only property of the RTCPeerConnection interface returns a string that describes the overall ICE gathering state for this connection.
This lets you detect, for example, when collection of ICE candidates has finished.

[Value("iceGatheringState")]
public RTCIceGatheringState IceGatheringState { get; }

Property Value

RTCIceGatheringState

The possible values are:

Remarks

You can detect when the value of this property changes by watching for an event of type RTCPeerConnectionicegatheringstatechange.

Note that iceGatheringState represents the overall gathering state of the connection, including every RTCIceTransport used by every RTCRtpSender and every RTCRtpReceiver on the entire connection.
This contrasts with GatheringState, which represents the gathering state for a single transport.

-RTCPeerConnectionicegatheringstatechange
-WebRTC

See also on MDN

IdpErrorInfo

[Value("idpErrorInfo")]
public string? IdpErrorInfo { get; }

Property Value

string

IdpLoginUrl

[Value("idpLoginUrl")]
public string? IdpLoginUrl { get; }

Property Value

string

LocalDescription

The localDescription read-only property of the RTCPeerConnection interface returns an RTCSessionDescription describing the session for the local end of the connection.
If it has not yet been set, this is null.

[Value("localDescription")]
public RTCSessionDescription? LocalDescription { get; }

Property Value

RTCSessionDescription

On a more fundamental level, the returned value is the value of PendingLocalDescription if that property isn't null;
otherwise, the value of CurrentLocalDescription is returned.
See Pending and current descriptions in the WebRTC Connectivity page for details on this algorithm and why it&apos;s used.

Remarks

-SetLocalDescription(RTCLocalSessionDescriptionInit), PendingLocalDescription, CurrentLocalDescription
-SetRemoteDescription(RTCSessionDescriptionInit), RemoteDescription, PendingRemoteDescription, CurrentRemoteDescription
-WebRTC

See also on MDN

Onconnectionstatechange

[Value("onconnectionstatechange")]
public EventHandlerNonNull Onconnectionstatechange { get; set; }

Property Value

EventHandlerNonNull

Ondatachannel

[Value("ondatachannel")]
public EventHandlerNonNull Ondatachannel { get; set; }

Property Value

EventHandlerNonNull

Onicecandidate

[Value("onicecandidate")]
public EventHandlerNonNull Onicecandidate { get; set; }

Property Value

EventHandlerNonNull

Onicecandidateerror

[Value("onicecandidateerror")]
public EventHandlerNonNull Onicecandidateerror { get; set; }

Property Value

EventHandlerNonNull

Oniceconnectionstatechange

[Value("oniceconnectionstatechange")]
public EventHandlerNonNull Oniceconnectionstatechange { get; set; }

Property Value

EventHandlerNonNull

Onicegatheringstatechange

[Value("onicegatheringstatechange")]
public EventHandlerNonNull Onicegatheringstatechange { get; set; }

Property Value

EventHandlerNonNull

Onnegotiationneeded

[Value("onnegotiationneeded")]
public EventHandlerNonNull Onnegotiationneeded { get; set; }

Property Value

EventHandlerNonNull

Onsignalingstatechange

[Value("onsignalingstatechange")]
public EventHandlerNonNull Onsignalingstatechange { get; set; }

Property Value

EventHandlerNonNull

Ontrack

[Value("ontrack")]
public EventHandlerNonNull Ontrack { get; set; }

Property Value

EventHandlerNonNull

PeerIdentity

The peerIdentity read-only property of the RTCPeerConnection interface returns a JavaScript {{jsxref("Promise")}} that resolves to an RTCIdentityAssertion which contains a string identifying the remote peer.
Once this promise resolves successfully, the resulting identity is the target peer identity and cannot change for the duration of the connection.

[Value("peerIdentity")]
public Task<RTCIdentityAssertion> PeerIdentity { get; }

Property Value

Task<RTCIdentityAssertion>

A JavaScript {{jsxref("Promise")}} which resolves to an RTCIdentityAssertion that describes the remote peer's identity.If an error occurs while attempting to validate an incoming identity assertion (that is, the information describing a peer&apos;s identity), the promise is rejected.
If there isn&apos;t already a target peer identity, peerIdentity is set to a newly created promise and the process begins again, until the process succeeds or no further attempts to authenticate occur.

NOTE

The promise returned by SetRemoteDescription(RTCSessionDescriptionInit) cannot resolve until any target peer identity that's been set is validated.
If the identity hasn&apos;t been validated yet, the promise returned by setRemoteDescription() will be rejected.
If there&apos;s no target peer identity, setRemoteDescription() doesn&apos;t need to wait for validation to occur before it resolves.

Remarks

-WebRTC API

See also on MDN

PendingLocalDescription

The pendingLocalDescription read-only property of the RTCPeerConnection interface returns an RTCSessionDescription object describing a pending configuration change for the local end of the connection.

[Value("pendingLocalDescription")]
public RTCSessionDescription? PendingLocalDescription { get; }

Property Value

RTCSessionDescription

If a local description change is in progress, this is an RTCSessionDescription describing the proposed configuration.
Otherwise, this returns null.

Remarks

This does not describe the connection as it currently stands, but as it may exist in the near future.
Use CurrentLocalDescription or LocalDescription to get the current state of the endpoint.
For details on the difference, see Pending and current descriptions in the WebRTC Connectivity page.

-SetLocalDescription(RTCLocalSessionDescriptionInit), CurrentLocalDescription, LocalDescription
-SetRemoteDescription(RTCSessionDescriptionInit), RemoteDescription, PendingRemoteDescription, CurrentRemoteDescription
-WebRTC

See also on MDN

PendingRemoteDescription

The pendingRemoteDescription read-only property of the RTCPeerConnection interface returns an RTCSessionDescription object describing a pending configuration change for the remote end of the connection.

[Value("pendingRemoteDescription")]
public RTCSessionDescription? PendingRemoteDescription { get; }

Property Value

RTCSessionDescription

If a remote description change is in progress, this is an RTCSessionDescription describing the proposed configuration.
Otherwise, this returns null.

Remarks

This does not describe the connection as it currently stands, but as it may exist in the near future.
Use CurrentRemoteDescription or RemoteDescription to get the current session
description for the remote endpoint.
For details on the difference, see Pending and current descriptions in the WebRTC Connectivity page.

-SetRemoteDescription(RTCSessionDescriptionInit),
CurrentRemoteDescription,
RemoteDescription
-SetLocalDescription(RTCLocalSessionDescriptionInit),
LocalDescription,
PendingLocalDescription,
CurrentLocalDescription
-WebRTC

See also on MDN

RemoteDescription

The remoteDescription read-only property of the RTCPeerConnection interface returns a RTCSessionDescription describing the session (which includes configuration and media information) for the remote end of the connection.
If this hasn&apos;t been set yet, this is null.

[Value("remoteDescription")]
public RTCSessionDescription? RemoteDescription { get; }

Property Value

RTCSessionDescription

On a more fundamental level, the returned value is the value of PendingRemoteDescription if that property isn't
null;
otherwise, the value of CurrentRemoteDescription is returned.
See Pending and current descriptions in the WebRTC Connectivity page for details on this algorithm and why it&apos;s used.

Remarks

The returned value typically reflects a remote description which has been received over the signaling server (as either an offer or an answer) and then put into effect by your code calling SetRemoteDescription(RTCSessionDescriptionInit) in response.

-SetRemoteDescription(RTCSessionDescriptionInit), PendingRemoteDescription, CurrentRemoteDescription
-SetLocalDescription(RTCLocalSessionDescriptionInit), PendingLocalDescription, CurrentLocalDescription, LocalDescription
-WebRTC

See also on MDN

Sctp

The sctp read-only property of the RTCPeerConnection interface returns an RTCSctpTransport describing the {{Glossary("SCTP")}} transport over which SCTP data is being sent and received.
If SCTP hasn&apos;t been negotiated, this value is null.

[Value("sctp")]
public RTCSctpTransport? Sctp { get; }

Property Value

RTCSctpTransport

A RTCSctpTransport object describing the SCTP transport being used by the RTCPeerConnection for transmitting and receiving on its data channels, or null if SCTP negotiation hasn&apos;t happened.

Remarks

The SCTP transport is used for transmitting and receiving data for any and all RTCDataChannels on the peer connection.

-WebRTC
-RTCPeerConnection
-RTCDataChannel
-SCTP

See also on MDN

SignalingState

The signalingState read-only property of the RTCPeerConnection interface returns a string value describing the state of the signaling process on the local end of the connection while connecting or reconnecting to another peer.
See Signaling in our WebRTC session lifetime page.

[Value("signalingState")]
public RTCSignalingState SignalingState { get; }

Property Value

RTCSignalingState

The allowed string values are:

Remarks

Because the signaling process is a state machine, being able to verify that your code is in the expected state when messages arrive can help avoid unexpected and avoidable failures.
For example, if you receive an answer while the signalingState isn&apos;t "have-local-offer", you know that something is wrong, since you should only receive answers after creating an offer but before an answer has been received and passed into SetLocalDescription(RTCLocalSessionDescriptionInit). Your code will be more reliable if you watch for mismatched states like this and handle them gracefully.

This value may also be useful during debugging, for example.

In addition, when the value of this property changes, a RTCPeerConnectionsignalingstatechange event is sent to the RTCPeerConnection instance.

-Lifetime of a WebRTC session
-RTCPeerConnection
-RTCPeerConnectionsignalingstatechange
-WebRTC

See also on MDN

Methods

AddIceCandidate(RTCIceCandidateInit)

The addIceCandidate() method of the RTCPeerConnection interface adds a new remote candidate to the connection's remote description, which describes the state of the remote end of the connection.

[Value("addIceCandidate")]
public Task<GlobalObject.Undefined> AddIceCandidate(RTCIceCandidateInit candidate = null)

Parameters

candidate RTCIceCandidateInit

Returns

Task<GlobalObject.Undefined>

A Promise that is fulfilled when the candidate has been successfully added to the remote peer's description by the ICE agent.
The promise does not receive any input parameters.

Remarks

When a website or app using RTCPeerConnection receives a new ICE candidate from the remote peer over its signaling channel, it delivers the newly-received candidate to the browser's {{Glossary("ICE")}} agent by calling RTCPeerConnection.addIceCandidate().
This adds this new remote candidate to the RTCPeerConnection&apos;s remote description, which describes the state of the remote end of the connection.

If the candidate parameter is missing or a value of null is given when calling addIceCandidate(), the added ICE candidate is an &quot;end-of-candidates&quot; indicator.
The same is the case if the value of the specified object's Candidate is either missing or an empty string (""), it signals that all remote candidates have been delivered.

The end-of-candidates notification is transmitted to the remote peer using a candidate with an a-line value of end-of-candidates.

During negotiation, your app will likely receive many candidates which you&apos;ll deliver to the ICE agent in this way, allowing it to build up a list of potential connection methods.
This is covered in more detail in the articles WebRTC connectivity and
Signaling and video calling.

-WebRTC API
-Signaling and video calling
-Introduction to WebRTC protocols
-WebRTC connectivity
-Lifetime of a WebRTC session

See also on MDN

AddIceCandidate(RTCIceCandidateInit, VoidFunction, RTCPeerConnectionErrorCallback)

The addIceCandidate() method of the RTCPeerConnection interface adds a new remote candidate to the connection's remote description, which describes the state of the remote end of the connection.

[Value("addIceCandidate")]
public Task<GlobalObject.Undefined> AddIceCandidate(RTCIceCandidateInit candidate, VoidFunction successCallback, RTCPeerConnectionErrorCallback failureCallback)

Parameters

candidate RTCIceCandidateInit

successCallback VoidFunction

failureCallback RTCPeerConnectionErrorCallback

Returns

Task<GlobalObject.Undefined>

A Promise that is fulfilled when the candidate has been successfully added to the remote peer's description by the ICE agent.
The promise does not receive any input parameters.

Remarks

When a website or app using RTCPeerConnection receives a new ICE candidate from the remote peer over its signaling channel, it delivers the newly-received candidate to the browser's {{Glossary("ICE")}} agent by calling RTCPeerConnection.addIceCandidate().
This adds this new remote candidate to the RTCPeerConnection&apos;s remote description, which describes the state of the remote end of the connection.

If the candidate parameter is missing or a value of null is given when calling addIceCandidate(), the added ICE candidate is an &quot;end-of-candidates&quot; indicator.
The same is the case if the value of the specified object's Candidate is either missing or an empty string (""), it signals that all remote candidates have been delivered.

The end-of-candidates notification is transmitted to the remote peer using a candidate with an a-line value of end-of-candidates.

During negotiation, your app will likely receive many candidates which you&apos;ll deliver to the ICE agent in this way, allowing it to build up a list of potential connection methods.
This is covered in more detail in the articles WebRTC connectivity and
Signaling and video calling.

-WebRTC API
-Signaling and video calling
-Introduction to WebRTC protocols
-WebRTC connectivity
-Lifetime of a WebRTC session

See also on MDN

AddTrack(MediaStreamTrack, params MediaStream[])

The addTrack() method of the RTCPeerConnection interface adds a new media track to the set of tracks which will be transmitted to the other peer.

[Value("addTrack")]
public RTCRtpSender AddTrack(MediaStreamTrack track, params MediaStream[] streams)

Parameters

track MediaStreamTrack

streams MediaStream[]

Returns

RTCRtpSender

The RTCRtpSender object which will be used to transmit the media data.

NOTE

Every RTCRtpSender is paired with an RTCRtpReceiver to make up an RTCRtpTransceiver.
The associated receiver is muted (indicating that it is not able to deliver packets) until and unless one or more streams are added to the receiver by the remote peer.

Remarks

NOTE

Adding a track to a connection triggers renegotiation by firing a RTCPeerConnectionnegotiationneeded event.
See Starting negotiation for details.

-WebRTC
-Introduction to the Real-time Transport Protocol (RTP)
-RTCPeerConnectiontrack

See also on MDN

AddTransceiver(Union231, RTCRtpTransceiverInit)

The addTransceiver() method of the RTCPeerConnection interface creates a new RTCRtpTransceiver and adds it to the set of transceivers associated with the RTCPeerConnection.
Each transceiver represents a bidirectional stream, with both an RTCRtpSender and an RTCRtpReceiver associated with it.

[Value("addTransceiver")]
public RTCRtpTransceiver AddTransceiver(Union231 trackOrKind, RTCRtpTransceiverInit init = null)

Parameters

trackOrKind Union231

init RTCRtpTransceiverInit

Returns

RTCRtpTransceiver

The RTCRtpTransceiver object which will be used to exchange the media data.

Remarks

-WebRTC API
-Introduction to the Real-time Transport Protocol (RTP)
-AddTrack(MediaStreamTrack, params MediaStream[]) also creates transceivers
-RTCRtpReceiver and RTCRtpSender

See also on MDN

Close()

The close() method of the RTCPeerConnection interface closes the current peer connection.

[Value("close")]
public GlobalObject.Undefined Close()

Returns

GlobalObject.Undefined

None (undefined).

Remarks

Calling this method terminates the RTCPeerConnection&apos;s ICE agent, ending any ongoing ICE processing and any active streams.
This also releases any resources in use by the ICE agent, including TURN permissions.
All RTCRtpSender objects are considered to be stopped once this returns (they may still be in the process of stopping, but for all intents and purposes, they're stopped).

Once this method returns, the signaling state as returned by SignalingState is closed.

Make sure that you delete all references to the previous RTCPeerConnection before attempting to create a new one that connects to the same remote peer, as not doing so might result in some errors depending on the browser.

-WebRTC
-RTCPeerConnection
-SignalingState

See also on MDN

CreateAnswer(RTCAnswerOptions)

The createAnswer() method of the RTCPeerConnection interface creates an {{Glossary("SDP")}} answer to an offer received from a remote peer during the offer/answer negotiation of a WebRTC connection.

[Value("createAnswer")]
public Task<RTCSessionDescriptionInit> CreateAnswer(RTCAnswerOptions options = null)

Parameters

options RTCAnswerOptions

Returns

Task<RTCSessionDescriptionInit>

A {{jsxref("Promise")}} that fulfills with an object containing the same properties as an RTCSessionDescription objects:

Remarks

The answer contains information about any media already attached to the session, codecs and options supported by the browser, and any ICE candidates already gathered.
The answer is delivered to the returned Promise, and should then be sent to the source of the offer to continue the negotiation process.

See also on MDN

CreateAnswer(RTCSessionDescriptionCallback, RTCPeerConnectionErrorCallback)

The createAnswer() method of the RTCPeerConnection interface creates an {{Glossary("SDP")}} answer to an offer received from a remote peer during the offer/answer negotiation of a WebRTC connection.

[Value("createAnswer")]
public Task<GlobalObject.Undefined> CreateAnswer(RTCSessionDescriptionCallback successCallback, RTCPeerConnectionErrorCallback failureCallback)

Parameters

successCallback RTCSessionDescriptionCallback

failureCallback RTCPeerConnectionErrorCallback

Returns

Task<GlobalObject.Undefined>

A {{jsxref("Promise")}} that fulfills with an object containing the same properties as an RTCSessionDescription objects:

Remarks

The answer contains information about any media already attached to the session, codecs and options supported by the browser, and any ICE candidates already gathered.
The answer is delivered to the returned Promise, and should then be sent to the source of the offer to continue the negotiation process.

See also on MDN

CreateDataChannel(string, RTCDataChannelInit)

The createDataChannel() method of the RTCPeerConnection interface creates a new channel linked with the remote peer, over which any kind of data may be transmitted.
This can be useful for back-channel content, such as images, file transfer, text chat, game update packets, and so forth.

[Value("createDataChannel")]
public RTCDataChannel CreateDataChannel(string label, RTCDataChannelInit dataChannelDict = null)

Parameters

label string

dataChannelDict RTCDataChannelInit

Returns

RTCDataChannel

A new RTCDataChannel object with the specified label, configured using the options specified by options if that parameter is included; otherwise, the defaults listed above are established.

Remarks

If the new data channel is the first one added to the connection, renegotiation is started by delivering a RTCPeerConnectionnegotiationneeded event.

-RTCDataChannel
-A simple RTCDataChannel sample
-RTCPeerConnection

See also on MDN

CreateOffer(RTCOfferOptions)

The createOffer() method of the RTCPeerConnection interface initiates the creation of an {{Glossary("SDP")}} offer for the purpose of starting a new WebRTC connection to a remote peer.

[Value("createOffer")]
public Task<RTCSessionDescriptionInit> CreateOffer(RTCOfferOptions options = null)

Parameters

options RTCOfferOptions

Returns

Task<RTCSessionDescriptionInit>

A {{jsxref("Promise")}} that fulfills with an object containing the same properties as an RTCSessionDescription objects:

Remarks

The SDP offer includes information about any MediaStreamTrack objects already attached to the WebRTC session, codec, and options supported by the browser, and any candidates already gathered by the {{Glossary("ICE")}} agent, for the purpose of being sent over the signaling channel to a potential peer to request a connection or to update the configuration of an existing connection.

See also on MDN

CreateOffer(RTCSessionDescriptionCallback, RTCPeerConnectionErrorCallback, RTCOfferOptions)

The createOffer() method of the RTCPeerConnection interface initiates the creation of an {{Glossary("SDP")}} offer for the purpose of starting a new WebRTC connection to a remote peer.

[Value("createOffer")]
public Task<GlobalObject.Undefined> CreateOffer(RTCSessionDescriptionCallback successCallback, RTCPeerConnectionErrorCallback failureCallback, RTCOfferOptions options = null)

Parameters

successCallback RTCSessionDescriptionCallback

failureCallback RTCPeerConnectionErrorCallback

options RTCOfferOptions

Returns

Task<GlobalObject.Undefined>

A {{jsxref("Promise")}} that fulfills with an object containing the same properties as an RTCSessionDescription objects:

Remarks

The SDP offer includes information about any MediaStreamTrack objects already attached to the WebRTC session, codec, and options supported by the browser, and any candidates already gathered by the {{Glossary("ICE")}} agent, for the purpose of being sent over the signaling channel to a potential peer to request a connection or to update the configuration of an existing connection.

See also on MDN

GenerateCertificate(Union187)

The generateCertificate() static function of the RTCPeerConnection interface creates an X.509 certificate and corresponding private key, returning a promise that resolves with the new RTCCertificate once it's generated.

[Value("generateCertificate")]
public static Task<RTCCertificate> GenerateCertificate(Union187 keygenAlgorithm)

Parameters

keygenAlgorithm Union187

Returns

Task<RTCCertificate>

A promise which resolves to a new RTCCertificate object containing a new key based on the specified options.

Remarks

-WebRTC API
-Web Crypto API
-Website security
-Web security
-Symmetric-key cryptography
-Crypto

See also on MDN

GetConfiguration()

The getConfiguration() method of the RTCPeerConnection interface returns an object which indicates the current configuration of the RTCPeerConnection on which the method is called.

[Value("getConfiguration")]
public RTCConfiguration GetConfiguration()

Returns

RTCConfiguration

An object describing the RTCPeerConnection's current configuration.
See RTCPeerConnection() for more information on what options are allowed.

Remarks

The returned configuration is the last configuration applied via SetConfiguration(RTCConfiguration), or if
setConfiguration() hasn&apos;t been called, the configuration the RTCPeerConnection was constructed with.
The configuration includes a list of the ICE servers used by the connection, information about transport policies, and identity information.

-SetConfiguration(RTCConfiguration)
-RTCPeerConnection(RTCConfiguration)
-RTCPeerConnection

See also on MDN

GetIdentityAssertion()

The getIdentityAssertion() method of the RTCPeerConnection interface initiates the gathering of an identity assertion.
This has an effect only if the SignalingState is not "closed".

[Value("getIdentityAssertion")]
public Task<string> GetIdentityAssertion()

Returns

Task<string>

A Promise which resolves to an identity assertion encoded as a string.

Remarks

It is not expected for the application dealing with the RTCPeerConnection: this is automatically done; an explicit call only allows to anticipate the need.

-WebRTC

See also on MDN

GetReceivers()

The getReceivers() method of the RTCPeerConnection interface returns an array of RTCRtpReceiver objects, each of which represents one RTP receiver.
Each RTP receiver manages the reception and decoding of data for a MediaStreamTrack on an RTCPeerConnection.

[Value("getReceivers")]
public List<RTCRtpReceiver> GetReceivers()

Returns

List<RTCRtpReceiver>

An array of RTCRtpReceiver objects, one for each track on the connection.
The array is empty if there are no RTP receivers on the connection.The order of the returned RTCRtpReceiver instances is not defined by the specification, and may change from one call to getReceivers() to the next.The array does not include receivers associated with transceivers that have been stopped (following offer/answer).

Remarks

-WebRTC
-RTCRtpSender

See also on MDN

GetSenders()

The getSenders() method of the RTCPeerConnection interface returns an array of RTCRtpSender objects, each of which represents the RTP sender responsible for transmitting one track's data.
A sender object provides methods and properties for examining and controlling the encoding and transmission of the track&apos;s data.

[Value("getSenders")]
public List<RTCRtpSender> GetSenders()

Returns

List<RTCRtpSender>

An array of RTCRtpSender objects, one for each track on the connection.
The array is empty if there are no RTP senders on the connection.The order of the returned RTCRtpSender instances is not defined by the specification, and may change from one call to getSenders() to the next.The array does not include senders associated with transceivers that have been stopped (following offer/answer).

Remarks

-WebRTC
-RTCRtpSender

See also on MDN

GetStats(MediaStreamTrack?)

The getStats() method of the RTCPeerConnection interface returns a promise which resolves with data providing statistics about either the overall connection or about the specified MediaStreamTrack.

[Value("getStats")]
public Task<RTCStatsReport> GetStats(MediaStreamTrack? selector = null)

Parameters

selector MediaStreamTrack

Returns

Task<RTCStatsReport>

A {{jsxref("Promise")}} which resolves with an RTCStatsReport object providing connection statistics.
The report&apos;s contents depend on the selector and other details of the connection.

Remarks

See also on MDN

GetTransceivers()

The getTransceivers() method of the RTCPeerConnection interface returns a list of the RTCRtpTransceiver objects being used to send and receive data on the connection.

[Value("getTransceivers")]
public List<RTCRtpTransceiver> GetTransceivers()

Returns

List<RTCRtpTransceiver>

An array of the RTCRtpTransceiver objects representing the transceivers handling sending and receiving all media on the RTCPeerConnection.
The array is in the order in which the transceivers were added to the connection.
The array does not include transceivers that have already been stopped (following offer/answer).

Remarks

-WebRTC API
-Signaling and video calling
-AddTransceiver(Union231, RTCRtpTransceiverInit)
-ArrayForEach

See also on MDN

RemoveTrack(RTCRtpSender)

The removeTrack() method of the RTCPeerConnection interface tells the local end of the connection to stop sending media from the specified track, without actually removing the corresponding RTCRtpSender from the list of senders as reported by GetSenders().
If the track is already stopped, or is not in the connection&apos;s senders list, this method has no effect.

[Value("removeTrack")]
public GlobalObject.Undefined RemoveTrack(RTCRtpSender sender)

Parameters

sender RTCRtpSender

Returns

GlobalObject.Undefined

undefined.

Remarks

If the connection has already been negotiated (SignalingState is set to "stable"), it is marked as needing to be negotiated again; the remote peer won&apos;t experience the change until this negotiation occurs.
A RTCPeerConnectionnegotiationneeded event is sent to the RTCPeerConnection to let the local end know this negotiation must occur.

-WebRTC API

See also on MDN

RestartIce()

The restartIce() method of the RTCPeerConnection interface allows a web application to request that {{Glossary("ICE")}} candidate gathering be redone on both ends of the connection.
This simplifies the process by allowing the same method to be used by either the caller or the receiver to trigger an ICE restart.

[Value("restartIce")]
public GlobalObject.Undefined RestartIce()

Returns

GlobalObject.Undefined

None (GlobalObject.Undefined).

Remarks

After restartIce() returns, the offer returned by the next call to CreateOffer(RTCOfferOptions) is automatically configured to trigger ICE restart on both the local peer (once the local peer has been set) and on the remote peer, once the offer is sent across your signaling mechanism and the remote peer has set its description as well.

restartIce() causes the
RTCPeerConnection.Negotiationneeded event to be fired on the RTCPeerConnection to inform the application that it should perform negotiation using its signaling channel.

If negotiation fails to complete—either due to rollback or because incoming offers are in the process of being negotiated—the RTCPeerConnection will remember that you requested ICE restart.
The next time the connection's SignalingState changes to stable, the connection will fire the RTCPeerConnection.Negotiationneeded event.
This process continues until an ICE restart has been successfully completed.

-WebRTC API
-Lifetime of a WebRTC session
-Signaling and video calling

See also on MDN

SetConfiguration(RTCConfiguration)

The setConfiguration() method of the RTCPeerConnection interface sets the current configuration of the connection based on the values included in the specified object.
This lets you change the ICE servers used by the connection and which transport policies to use.

[Value("setConfiguration")]
public GlobalObject.Undefined SetConfiguration(RTCConfiguration configuration = null)

Parameters

configuration RTCConfiguration

Returns

GlobalObject.Undefined

None (GlobalObject.Undefined).

Remarks

The most common use case for this method (and even then, probably not a very common use case) is to replace the set of ICE servers to be used. Two potential scenarios in which this might be done:

NOTE

You cannot change the identity information for a connection once it&apos;s already been set.

-GetConfiguration()
-RTCPeerConnection(RTCConfiguration)
-RTCPeerConnection

See also on MDN

SetIdentityProvider(string, RTCIdentityProviderOptions)

The setIdentityProvider() method of the RTCPeerConnection interface sets the Identity Provider (IdP) to the triplet given in parameter: its name, the protocol used to communicate with it (optional) and an optional username.
The IdP will be used only when an assertion is needed.

[Value("setIdentityProvider")]
public GlobalObject.Undefined SetIdentityProvider(string provider, RTCIdentityProviderOptions options = null)

Parameters

provider string

options RTCIdentityProviderOptions

Returns

GlobalObject.Undefined

None (GlobalObject.Undefined).

Remarks

If the SignalingState is set to "closed", an InvalidStateError is raised.

-WebRTC

See also on MDN

SetLocalDescription(RTCLocalSessionDescriptionInit)

The setLocalDescription() method of the RTCPeerConnection interface changes the local description associated with the connection.
This description specifies the properties of the local end of the connection, including the media format.
The method takes a single parameter—the session description—and it returns a Promise which is fulfilled once the description has been changed, asynchronously.

[Value("setLocalDescription")]
public Task<GlobalObject.Undefined> SetLocalDescription(RTCLocalSessionDescriptionInit description = null)

Parameters

description RTCLocalSessionDescriptionInit

Returns

Task<GlobalObject.Undefined>

A {{jsxref("Promise")}} which is fulfilled once the value of LocalDescription is successfully changed or rejected if the change cannot be applied (for example, if the specified description is incompatible with one or both of the peers on the connection).
The promise&apos;s fulfillment handler receives no input parameters.

NOTE

The process of changing descriptions actually involves intermediary steps handled by the WebRTC layer to ensure that an active connection can be changed without losing the connection if the change does not succeed.
See Pending and current descriptions in the WebRTC Connectivity page for more details on this process.

Remarks

If setLocalDescription() is called while a connection is already in place, it means renegotiation is underway (possibly to adapt to changing network conditions).
Because descriptions will be exchanged until the two peers agree on a configuration, the description submitted by calling setLocalDescription() does not immediately take effect.
Instead, the current connection configuration remains in place until negotiation is complete. Only then does the agreed-upon configuration take effect.

-WebRTC API
-RTCSessionDescription

See also on MDN

SetLocalDescription(RTCLocalSessionDescriptionInit, VoidFunction, RTCPeerConnectionErrorCallback)

The setLocalDescription() method of the RTCPeerConnection interface changes the local description associated with the connection.
This description specifies the properties of the local end of the connection, including the media format.
The method takes a single parameter—the session description—and it returns a Promise which is fulfilled once the description has been changed, asynchronously.

[Value("setLocalDescription")]
public Task<GlobalObject.Undefined> SetLocalDescription(RTCLocalSessionDescriptionInit description, VoidFunction successCallback, RTCPeerConnectionErrorCallback failureCallback)

Parameters

description RTCLocalSessionDescriptionInit

successCallback VoidFunction

failureCallback RTCPeerConnectionErrorCallback

Returns

Task<GlobalObject.Undefined>

A {{jsxref("Promise")}} which is fulfilled once the value of LocalDescription is successfully changed or rejected if the change cannot be applied (for example, if the specified description is incompatible with one or both of the peers on the connection).
The promise&apos;s fulfillment handler receives no input parameters.

NOTE

The process of changing descriptions actually involves intermediary steps handled by the WebRTC layer to ensure that an active connection can be changed without losing the connection if the change does not succeed.
See Pending and current descriptions in the WebRTC Connectivity page for more details on this process.

Remarks

If setLocalDescription() is called while a connection is already in place, it means renegotiation is underway (possibly to adapt to changing network conditions).
Because descriptions will be exchanged until the two peers agree on a configuration, the description submitted by calling setLocalDescription() does not immediately take effect.
Instead, the current connection configuration remains in place until negotiation is complete. Only then does the agreed-upon configuration take effect.

-WebRTC API
-RTCSessionDescription

See also on MDN

SetRemoteDescription(RTCSessionDescriptionInit)

The setRemoteDescription() method of the RTCPeerConnection interface sets the specified session description as the remote peer's current offer or answer.
The description specifies the properties of the remote end of the connection, including the media format.
The method takes a single parameter—the session description—and it returns a Promise which is fulfilled once the description has been changed, asynchronously.

[Value("setRemoteDescription")]
public Task<GlobalObject.Undefined> SetRemoteDescription(RTCSessionDescriptionInit description)

Parameters

description RTCSessionDescriptionInit

Returns

Task<GlobalObject.Undefined>

A {{jsxref("Promise")}} which is fulfilled once the value of the connection's RemoteDescription is successfully changed or rejected if the change cannot be applied (for example, if the specified description is incompatible with one or both of the peers on the connection).
The promise fulfillment handler receives no input parameters.

NOTE

The process of changing descriptions actually involves intermediary steps handled by the WebRTC layer to ensure that an active connection can be changed without losing the connection if the change does not succeed.
See Pending and current descriptions in the WebRTC Connectivity page for more details on this process.

Remarks

This is typically called after receiving an offer or answer from another peer over the signaling server.
Keep in mind that if setRemoteDescription() is called while a connection is already in place, it means renegotiation is underway (possibly to adapt to changing network conditions).

Because descriptions will be exchanged until the two peers agree on a configuration, the description submitted by calling setRemoteDescription() does not immediately take effect.
Instead, the current connection configuration remains in place until negotiation is complete.
Only then does the agreed-upon configuration take effect.

-WebRTC
-RemoteDescription,
PendingRemoteDescription,
CurrentRemoteDescription
-RTCSessionDescription

See also on MDN

SetRemoteDescription(RTCSessionDescriptionInit, VoidFunction, RTCPeerConnectionErrorCallback)

The setRemoteDescription() method of the RTCPeerConnection interface sets the specified session description as the remote peer's current offer or answer.
The description specifies the properties of the remote end of the connection, including the media format.
The method takes a single parameter—the session description—and it returns a Promise which is fulfilled once the description has been changed, asynchronously.

[Value("setRemoteDescription")]
public Task<GlobalObject.Undefined> SetRemoteDescription(RTCSessionDescriptionInit description, VoidFunction successCallback, RTCPeerConnectionErrorCallback failureCallback)

Parameters

description RTCSessionDescriptionInit

successCallback VoidFunction

failureCallback RTCPeerConnectionErrorCallback

Returns

Task<GlobalObject.Undefined>

A {{jsxref("Promise")}} which is fulfilled once the value of the connection's RemoteDescription is successfully changed or rejected if the change cannot be applied (for example, if the specified description is incompatible with one or both of the peers on the connection).
The promise fulfillment handler receives no input parameters.

NOTE

The process of changing descriptions actually involves intermediary steps handled by the WebRTC layer to ensure that an active connection can be changed without losing the connection if the change does not succeed.
See Pending and current descriptions in the WebRTC Connectivity page for more details on this process.

Remarks

This is typically called after receiving an offer or answer from another peer over the signaling server.
Keep in mind that if setRemoteDescription() is called while a connection is already in place, it means renegotiation is underway (possibly to adapt to changing network conditions).

Because descriptions will be exchanged until the two peers agree on a configuration, the description submitted by calling setRemoteDescription() does not immediately take effect.
Instead, the current connection configuration remains in place until negotiation is complete.
Only then does the agreed-upon configuration take effect.

-WebRTC
-RemoteDescription,
PendingRemoteDescription,
CurrentRemoteDescription
-RTCSessionDescription

See also on MDN