WebRTC 1.0: Real-time Communication Between Browsers

4.2.1 RTCConfiguration Type

dictionary RTCConfiguration {
    RTCIceServer[] iceServers;
};

4.2.2 RTCIceServer Type

dictionary RTCIceServer {
    DOMString  url;
    DOMString? credential;
};

In network topologies with multiple layers of NATs, it is desirable to have a STUN server between every layer of NATs in addition to the TURN servers to minimize the peer to peer network latency.

An example array of RTCIceServer objects is:

[ { url:"stun:stun.example.net" } , { url:"turn:user@turn.example.org", credential:"myPassword"} ]

4.3.1 Operation

Calling new RTCPeerConnection(configuration ) creates an RTCPeerConnection object.

The configuration has the information to find and access the [STUN] and [TURN] servers. There may be multiple servers of each type and any TURN server also acts as a STUN server.

An RTCPeerConnection object has an associated ICE agent[ICE], RTCPeerConnection signaling state, ICE gathering state, and ICE connection state. These are initialized when the object is created.

An RTCPeerConnection object has two associated stream sets. A local streams set, representing streams that are currently sent, and a remote streams set, representing streams that are currently received with this RTCPeerConnection object. The stream sets are initialized to empty sets when the RTCPeerConnection object is created.

When the RTCPeerConnection() constructor is invoked, the user agent must run the following steps. This algorithm has a synchronous section (which is triggered as part of the event loop algorithm).

1. Create an ICE Agent as defined in [ICE] and let connection's RTCPeerConnection ICE Agent be that ICE Agent and provide it the STUN and TURN servers from the configuration array. The ICE Agent will proceed with gathering as soon as the IceTransports constraint is not set to "none". At this point the ICE Agent does not know how many ICE components it needs (and hence the number of candidates to gather), but it can make a reasonable assumption such as 2. As the RTCPeerConnection object gets more information, the ICE Agent can adjust the number of components.

2. Set connection's RTCPeerConnection signalingState to stable.

3. Set connection's RTCPeerConnection ice connection state to starting.

4. Set connection's RTCPeerConnection ice gathering state to new.

5. Initialize an internal variable to represent a queue of operations with an empty set.

6. Return connection, but continue these steps asynchronously.

7. Await a stable state. The synchronous section consists of the remaining steps of this algorithm.

Once the RTCPeerConnection object has been initialized, for every call to createOffer, setLocalDescription, createAnswer and setRemoteDescription; execute the following steps:

1. Append an object representing the current call being handled (i.e. function name and corresponding arguments) to the operations array.

2. If the length of the operations array is exactly 1, execute the function from the front of the queue asynchronously.

3. When the ascynchronous operation completes (either successfully or with an error), remove the corresponding object from the operations array. After removal, if the array is non-empty, execute the first object queued asynchronously and repeat this step on completion.

The general idea is to have only one among createOffer, setLocalDescription, createAnswer and setRemoteDescription executing at any given time. If subsequent calls are made while one of them is still executing, they are added to a queue and processed when the previous operation is fully completed. It is valid, and expected, for normal error handling procedures to be applied.

Additionally, during the lifetime of the RTCPeerConnection object, the following procedures are followed when an ICE event occurs:

1. If iceConnectionState is "starting" and the IceTransports constraint is not set to "none", it must queue a task to start gathering ICE addresses and set the iceConnectionState to "gathering".

2. If the ICE Agent has found one or more candidate pairs for each MediaStreamTrack that forms a valid connection, the ICE connection state is changed to "connected".

3. When the ICE Agent finishes checking all candidate pairs, if at least one connection has been found for each MediaStreamTrack, the iceConnectionState is changed to "completed"; else the iceConnectionState is changed to "failed".

4. If the iceConnectionState is "connected" or "completed" and both the local and remote session descriptions have received a valid SDP offer / answer pair, the RTCPeerConnection state is set to "stable".

5. If the iceConnectionState is "failed", a task is queued to call the close method.

   Issue 1

   Open Issue: CJ - this seems wrong to me - just because a network connection failed does not mean the PC should be put into a dead state it can not recover from.

User agents negotiate the codec resolution, bitrate, and other media parameters. It is recommended that user agents initially negotiate for the maximum resolution of a video stream. For streams that are then rendered (using a video element), it is recommended that user agents renegotiate for a resolution that matches the rendered display size.

The word "components" in this context refers to an RTP media flow and does not have anything to do with how [ICE] uses the term "component".

When a user agent has reached the point where a MediaStream can be created to represent incoming components, the user agent must run the following steps:

1. Let connection be the RTCPeerConnection expecting this media.

2. Create a MediaStream object stream, to represent the incoming media stream.

3. Run the algorithm to represent an incoming component with a track for each incoming component.

   Note

   The creation of new incoming MediaStreams may be triggered either by SDP negotiation or by the receipt of media on a given flow.

4. Queue a task to run the following substeps:

   1. If the connection's RTCPeerConnection signalingState is closed, abort these steps.

   2. Add stream to connection's remote streams set.

   3. Fire a stream event named addstream with stream at the connection object.

When a user agent has negotiated media for a component that belongs to a media stream that is already represented by an existing MediaStream object, the user agent must associate the component with that MediaStream object.

When an RTCPeerConnection finds that a stream from the remote peer has been removed, the user agent must follow these steps:

1. Let connection be the RTCPeerConnection associated with the stream being removed.

2. Let stream be the MediaStream object that represents the media stream being removed, if any. If there isn't one, then abort these steps.

3. By definition, stream is now finished.

   Note

   A task is thus queued to update stream and fire an event.

4. Queue a task to run the following substeps:

   1. If the connection's RTCPeerConnection signalingState is closed, abort these steps.

   2. Remove stream from connection's remote streams set.

   3. Fire a stream event named removestream with stream at the connection object.

The task source for the tasks listed in this section is the networking task source.

If something in the browser changes that causes the RTCPeerConnection object to need to initiate a new session description negotiation, a negotiationneeded event is fired at the RTCPeerConnection object.

In particular, if an RTCPeerConnection object is consuming a MediaStream on which a track is added, by, e.g., the addTrack() method being invoked, the RTCPeerConnection object must fire the "negotiationneeded" event. Removal of media components must also trigger "negotiationneeded".

To prevent network sniffing from allowing a fourth party to establish a connection to a peer using the information sent out-of-band to the other peer and thus spoofing the client, the configuration information should always be transmitted using an encrypted connection.

4.3.2 Interface Definition

[Constructor (RTCConfiguration configuration, optional MediaConstraints constraints)]
interface RTCPeerConnection : EventTarget  {
    void                  createOffer (RTCSessionDescriptionCallback successCallback, RTCPeerConnectionErrorCallback failureCallback, optional MediaConstraints constraints);
    void                  createAnswer (RTCSessionDescriptionCallback successCallback, RTCPeerConnectionErrorCallback failureCallback, optional MediaConstraints constraints);
    void                  setLocalDescription (RTCSessionDescription description, VoidFunction successCallback, RTCPeerConnectionErrorCallback failureCallback);
    readonly attribute RTCSessionDescription localDescription;
    void                  setRemoteDescription (RTCSessionDescription description, VoidFunction successCallback, RTCPeerConnectionErrorCallback failureCallback);
    readonly attribute RTCSessionDescription remoteDescription;
    readonly attribute RTCSignalingState     signalingState;
    void                  updateIce (optional RTCConfiguration configuration, optional MediaConstraints constraints);
    void                  addIceCandidate (RTCIceCandidate candidate);
    readonly attribute RTCIceGatheringState  iceGatheringState;
    readonly attribute RTCIceConnectionState iceConnectionState;
    sequence<MediaStream> getLocalStreams ();
    sequence<MediaStream> getRemoteStreams ();
    MediaStream?          getStreamById (DOMString streamId);
    void                  addStream (MediaStream stream, optional MediaConstraints constraints);
    void                  removeStream (MediaStream stream);
    void                  close ();
             attribute EventHandler          onnegotiationneeded;
             attribute EventHandler          onicecandidate;
             attribute EventHandler          onopen;
             attribute EventHandler          onstatechange;
             attribute EventHandler          onaddstream;
             attribute EventHandler          onremovestream;
             attribute EventHandler          ongatheringchange;
             attribute EventHandler          onicechange;
};

4.3.3 Garbage collection

A Window object has a strong reference to any RTCPeerConnection objects created from the constructor whose global object is that Window object.

4.4.1 RTCPeerState Enum

enum RTCSignalingState {
    "stable",
    "have-local-offer",
    "have-remote-offer",
    "have-local-pranswer",
    "have-remote-pranswer",
    "closed"
};

The non-normative peer state transitions are:

An example set of transitions might be:

Caller transition:

• new PeerConnection(): stable
• setLocal(offer): have-local-offer
• setRemote(pranswer): have-remote-pranswer
• setRemote(answer): stable
• close(): closed

Callee transition:

• new PeerConnection(): stable
• setRemote(offer): have-remote-offer
• setLocal(pranswer): have-local-pranswer
• setLocal(answer): stable
• close(): closed

4.4.2 RTCIceGatheringState Enum

enum RTCIceGatheringState {
    "new",
    "gathering",
    "complete"
};

4.4.3 RTCIceConnectionState Enum

enum RTCIceState {
    "starting",
    "checking",
    "connected",
    "completed",
    "failed",
    "disconnected",
    "closed"
};

States take either the value of any component or all components, as outlined below:

• checking occurs if ANY component has received a candidate and can start checking
• connected occurs if ALL components have established a working connection
• completed occurs if ALL components have finalized the running of their ICE processes
• failed occurs if ANY component has given up trying to connect
• disconnected occurs if ANY component has failed liveness checks
• closed occurs only if PeerConnection.close() has been called.

If a component is discarded as a result of signaling (e.g. RTCP mux or BUNDLE), the state may advance directly from checking to completed.

An example transition might look like:

• new PeerConnection(): Starting
• (Starting, remote candidates received): Checking
• (Checking, found usable connection): Connected
• (Checking, gave up): Failed
• (Connected, finished all checks): Completed
• (Completed, lost connectivity): Disconnected
• (any state, ICE restart occurs): Starting
• close(): Closed

The non-normative ICE state transitions are:

4.5.1 RTCPeerConnectionErrorCallback

callback RTCPeerConnectionErrorCallback = void (RTCError error);

4.6.1 General Principles

Errors are indicated in two ways: exceptions and objects passed to error callbacks. Both forms of error reporting must provide an object of type RTCError. An exception must be thrown in the following cases:

• The type of any argument passed to a function did not match what was expected. An appropriate string from the RTCExceptionName enum must be used as the error name.
• A function call was made when the RTCPeerConnection is in an invalid state, or a state in which that particular function is not allowed to be executed. In this case, the string INVALID_STATE must be used as the error name.

In all other cases, an error object must be provided to the failure callback. The error name in the object provided must be picked from either the RTCExceptionName or RTCErrorName enums.

4.6.2 RTCError

interface RTCError {
    readonly attribute DOMString  name;
    readonly attribute DOMString? message;
};

4.6.3 RTCSdpError

interface RTCSdpError : RTCError {
    readonly attribute long sdpLineNumber;
};

4.6.4 RTCExceptionName

enum RTCExceptionName {
    "INVALID_CONSTRAINTS_TYPE",
    "INVALID_CANDIDATE_TYPE",
    "INVALID_MEDIASTREAM_TRACK",
    "INVALID_STATE"
};

4.6.5 RTCErrorName

enum RTCErrorName {
    "INVALID_SESSION_DESCRIPTION",
    "INCOMPATIBLE_CONSTRAINTS",
    "INCOMPATIBLE_MEDIASTREAMTRACK"
};

4.7.1 RTCSdpType

The RTCSdpType enum describes the type of an RTCSessionDescription instance.

enum RTCSdpType {
    "offer",
    "pranswer",
    "answer"
};

4.7.2 RTCSessionDescription Class

The RTCSessionDescription() constructor takes an optional dictionary argument, descriptionInitDict, whose content is used to initialize the new RTCSessionDescription object. If a dictionary key is not present in descriptionInitDict, the corresponding attribute will be initialized to null. If the constructor is run without the dictionary argument, all attributes will be initialized to null. This class is a future extensible carrier for the data contained in it and does not perform any substantive processing.

Objects implementing the RTCSessionDescription interface must serialize with the serialization pattern "{ attribute }".

dictionary RTCSessionDescriptionInit {
    RTCSdpType type;
    DOMString  sdp;
};

[Constructor (optional RTCSessionDescriptionInit descriptionInitDict)]
interface RTCSessionDescription {
             attribute RTCSdpType? type;
             attribute DOMString?  sdp;
    serializer = {attribute};
};

4.7.3 RTCSessionDescriptionCallback

callback RTCSessionDescriptionCallback = void (RTCSessionDescription sdp);

4.8.1 RTCIceCandidate Type

The RTCIceCandidate() constructor takes an optional dictionary argument, candidateInitDict, whose content is used to initialize the new RTCIceCandidate object. If a dictionary key is not present in candidateInitDict, the corresponding attribute will be initialized to null. If the constructor is run without the dictionary argument, all attributes will be initialized to null. This class is a future extensible carrier for the data contained in it and does not perform any substantive processing.

Objects implementing the RTCIceCandidate interface must serialize with the serialization pattern "{ attribute }".

dictionary RTCIceCandidateInit {
    DOMString      candidate;
    DOMString      sdpMid;
    unsigned short sdpMLineIndex;
};

[Constructor (optional RTCIceCandidateInit candidateInitDict)]
interface RTCIceCandidate {
             attribute DOMString?      candidate;
             attribute DOMString?      sdpMid;
             attribute unsigned short? sdpMLineIndex;
    serializer = {attribute};
};

4.8.2 RTCPeerConnectionIceEvent

The icecandidate event of the RTCPeerConnection uses the RTCPeerConnectionIceEvent interface.

Firing an RTCPeerConnectionIceEvent event named e with an RTCIceCandidate candidate means that an event with the name e, which does not bubble (except where otherwise stated) and is not cancelable (except where otherwise stated), and which uses the RTCPeerConnectionIceEvent interface with the candidate attribute set to the new ICE candidate, must be created and dispatched at the given target.

dictionary RTCPeerConnectionIceEventInit : EventInit {
    RTCIceCandidate candidate;
};

[Constructor(DOMString type, RTCPeerConnectionIceEventInit eventInitDict)]
interface RTCPeerConnectionIceEvent : Event {
    readonly attribute RTCIceCandidate candidate;
};

5.1.1 Attributes

ondatachannel of type EventHandler

This event handler, of type datachannel , must be supported by all objects implementing the RTCPeerConnection interface.

5.1.2 Methods

createDataChannel

Creates a new RTCDataChannel object with the given label. The RTCDataChannelInit dictionary can be used to configure properties of the underlying channel such as data reliability. A corresponding RTCDataChannel object is dispatched at the other peer if the channel setup was successful.

When the createDataChannel() method is invoked, the user agent must run the following steps.

1. If the RTCPeerConnection object’s RTCPeerConnection signalingState is closed, throw an INVALID_STATE exception.

2. Let channel be a newly created RTCDataChannel object.

3. Initialize channel's label attribute to the value of the first argument.

4. Initialize channel's reliable attribute to true.

5. If the second argument is present and it contains a reliable dictionary member, then set channel's reliable attribute to the dictionary member value.

6. Return channel and continue these steps in the background.

7. Create channel's associated underlying data transport.

Parameter	Type	Nullable	Optional	Description
label	DOMString	✘	✘
dataChannelDict	RTCDataChannelInit	✘	✔

Return type: RTCDataChannel

5.2.1 Attributes

binaryType of type DOMString

The binaryType attribute must, on getting, return the value to which it was last set. On setting, the user agent must set the IDL attribute to the new value. When a RTCDataChannel object is created, the binaryType attribute must be initialized to the string "blob".

This attribute controls how binary data is exposed to scripts. See the [WEBSOCKETS-API] for more information.

bufferedAmount of type unsigned long, readonly

The bufferedAmount attribute must return the number of bytes of application data (UTF-8 text and binary data) that have been queued using send() but that, as of the last time the event loop started executing a task, had not yet been transmitted to the network. (This thus includes any text sent during the execution of the current task, regardless of whether the user agent is able to transmit text asynchronously with script execution.) This does not include framing overhead incurred by the protocol, or buffering done by the operating system or network hardware. If the channel is closed, this attribute's value will only increase with each call to the send() method (the attribute does not reset to zero once the channel closes).

label of type DOMString, readonly

The RTCDataChannel.label attribute represents a label that can be used to distinguish this RTCDataChannel object from other RTCDataChannel objects. The attribute must return the value to which it was set when the RTCDataChannel object was created.

onclose of type EventHandler

This event handler, of type close, must be supported by all objects implementing the RTCDataChannel interface.

onerror of type EventHandler

This event handler, of type error, must be supported by all objects implementing the RTCDataChannel interface.

onmessage of type EventHandler

This event handler, of type message ,must be supported by all objects implementing the RTCDataChannel interface.

onopen of type EventHandler

This event handler, of type open, must be supported by all objects implementing the RTCDataChannel interface.

readyState of type RTCDataChannelState, readonly

The RTCDataChannel.readyState attribute represents the state of the RTCDataChannel object. It must return the value to which the user agent last set it (as defined by the processing model algorithms).

reliable of type boolean, readonly

The RTCDataChannel.reliable attribute returns true if the RTCDataChannel is reliable, and false otherwise. The attribute must return the value to which it was set when the RTCDataChannel was created.

5.2.2 Methods

close

Closes the RTCDataChannel. It may be called regardless of whether the RTCDataChannel object was created by this peer or the remote peer.

When the close() method is called, the user agent must run the following steps:

1. Let channel be the RTCDataChannel object which is about to be closed.

2. If channel's readyState is closing or closed, then abort these steps.

3. Set channel's readyState attribute to closing.

4. If the closing procedure has not started yet, start it.

No parameters.

Return type: void

send

Run the steps described by the send() algorithm with argument type string object.

Parameter	Type	Nullable	Optional	Description
data	DOMString	✘	✘

Return type: void

send

Run the steps described by the send() algorithm with argument type Blob object.

Parameter	Type	Nullable	Optional	Description
data	Blob	✘	✘

Return type: void

send

Run the steps described by the send() algorithm with argument type ArrayBuffer object.

Parameter	Type	Nullable	Optional	Description
data	ArrayBuffer	✘	✘

Return type: void

send

Run the steps described by the send() algorithm with argument type ArrayBufferView object.

Parameter	Type	Nullable	Optional	Description
data	ArrayBufferView	✘	✘

Return type: void

5.2.3 Dictionary RTCDataChannelInit Members

reliable of type boolean

5.3.1 Attributes

channel of type RTCDataChannel, readonly

The channel attribute represents the RTCDataChannel object associated with the event.

5.3.2 Dictionary RTCDataChannelEventInit Members

channel of type RTCDataChannel

TODO

6.1.1 Methods

createDTMFSender

The createDTMFSender() method creates an RTCDTMFSender that references the given MediaStreamTrack. The MediaStreamTrack must be an element of a MediaStream that's currently in the RTCPeerConnection object's local streams set; if not, throw an exception with an RTCError object of type INVALID_MEDIASTREAMTRACK.

Parameter	Type	Nullable	Optional	Description
track	MediaStreamTrack	✘	✘

Return type: RTCDTMFSender

6.2.1 Attributes

canInsertDTMF of type boolean, readonly

The canInsertDTMF attribute must indicate if the RTCDTMFSender is capable of sending DTMF.

duration of type long, readonly

The duration attribute must return the current tone duration value. This value will be the value last set via the insertDTMF() method, or the default value of 100 ms if insertDTMF() was called without specifying the duration.

interToneGap of type long, readonly

The interToneGap attribute must return the current value of the between-tone gap. This value will be the value last set via the insertDTMF() method, or the default value of 50 ms if insertDTMF() was called without specifying the interToneGap.

ontonechange of type EventHandler

This event handler uses the RTCDTMFToneChangeEvent interface to return the character for each tone as it is played out. See RTCDTMFToneChangeEvent for details.

toneBuffer of type DOMString, readonly

The toneBuffer attribute must return a list of the tones remaining to be played out. For the syntax, content, and interpretation of this list, see insertDTMF.

track of type MediaStreamTrack, readonly

The track attribute must return the MediaStreamTrack given as argument to the createDTMFSender() method.

6.2.2 Methods

insertDTMF

An RTCDTMFSender object’s insertDTMF() method is used to send DTMF tones.

The tones parameter is treated as a series of characters. The characters 0 through 9, A through D, #, and * generate the associated DTMF tones. The characters a to d are equivalent to A to D. The character ',' indicates a delay of 2 seconds before processing the next character in the tones parameter. Unrecognized characters are ignored.

The duration parameter indicates the duration in ms to use for each character passed in the tones parameters. The duration cannot be more than 6000 ms or less than 70 ms. The default duration is 100 ms for each tone.

The interToneGap parameter indicates the gap between tones. It must be at least 50 ms. The default value is 50 ms.

Issue 4

ISSUE: How are invalid values handled?

When the insertDTMF() method is invoked, the user agent must run the following steps:

1. If the associated MediaStreamTrack is not connected to the associated RTCPeerConnection, return.
2. If the canInsertDTMF attribute is false, return.
3. Set the value of the toneBuffer attribute to the value of the tones argument, the value of the duration attribute to the duration argument if specified, and the value of the interToneGap to the interToneGap argument, if specified.
4. If toneBuffer is an empty string, return.
5. If a Playout task is scheduled to be run; abort these steps; otherwise queue a task that runs the following steps (Playout task):
1. If toneBuffer is an empty string, fire an event named tonechange with an empty string at the RTCDTMFSender object and abort these steps.
2. Remove the first character from toneBuffer and let that character be tone.
3. Start playout of tone for duration ms on the associated RTP media stream, using the appropriate codec.
4. Queue a task to be executed in duration + interToneGap ms from now that runs the steps labelled Playout task.
5. Fire an event named tonechange with a string consisting of tone at the RTCDTMFSender object.

Calling insertDTMF() with an empty tones parameter can be used to cancel all tones queued to play after the currently playing tone.

Parameter	Type	Nullable	Optional	Description
tones	DOMString	✘	✘
duration	long	✘	✔
interToneGap	long	✘	✔

Return type: void

6.3.1 Attributes

tone of type DOMString, readonly

The tone attribute contains the character for the tone that has just begun playout (see insertDTMF()). If the value is the empty string, it indicates that the previous tone has completed playback.

7.2.1 Methods

getStats

Gathers stats for the given selector and reports the result asynchronously.

When the getStats() method is invoked, the user agent must queue a task to run the following steps:

1. If the RTCPeerConnection object's RTCPeerConnection signalingState is closed, throw an INVALID_STATE exception.

2. Return, but continue the following steps in the background.

3. Let selectorArg be the methods first argument.

4. If selectorArg is an invalid selector, the user agent must queue a task to invoke the failure callback (the method's third argument).

5. Start gathering the stats indicated by selectorArg. In case selectorArg is null, stats must be gathered for the whole RTCPeerConnection object.

6. When the relevant stats have been gathered, queue a task to invoke the success callback (the method's second argument) with a new RTCStatsReport object, representing the gathered stats, as its argument.

Parameter	Type	Nullable	Optional	Description
selector	MediaStreamTrack	✔	✘
successCallback	RTCStatsCallback	✘	✘
failureCallback	RTCPeerConnectionErrorCallback	✘	✘

Return type: void

7.3.1 Callback RTCStatsCallback Parameters

report of type RTCStatsReport

A RTCStatsReport representing the gathered stats.

7.4.1 Methods

RTCStats

Getter to retrieve the RTCStats objects that this stats report is composed of.

The set of supported property names [WEBIDL] is defined as the ids of all the RTCStats objects that has been generated for this stats report. The order of the property names is left to the user agent.

Parameter	Type	Nullable	Optional	Description
id	DOMString	✘	✘

Return type: getter

7.5.1 Dictionary RTCStats Members

id of type DOMString

A unique id that is associated with the object that was inspected to produce this RTCStats object. Two RTCStats objects, extracted from two different RTCStatsReport objects, must have the same id if they were produced by inspecting the same underlying object. User agents are free to pick any format for the id as long as it meets the requirements above.

Note

Consider naming id something that indicates that the id refers to the underlying object that was inspected to produce the stats, instead of being an id for the JavaScript object. Suggestions: statsObjectId, reporterId, srcId.

timestamp of type DOMHiResTimeStamp

The timestamp, of type DOMHiResTimeStamp [HIGHRES-TIME], associated with this object. The time is relative to the UNIX epoch (Jan 1, 1970, UTC).

type of type RTCStatsType

The type of this object.

The type attribute must be initialized to the name of the most specific type this RTCStats dictionary represents.

7.6.1 Dictionary RTCRTPStreamStats Members

remoteId of type DOMString

The remoteId can be used to look up the corresponding RTCStats object that represents stats reported by the other peer.

ssrc of type DOMString

...

7.6.2 Dictionary RTCInboundRTPStreamStats Members

bytesReceived of type unsigned long

...

packetsReceived of type unsigned long

...

7.6.3 Dictionary RTCOutboundRTPStreamStats Members

bytesSent of type unsigned long

...

packetsSent of type unsigned long

...

8.1.1 Peer-Connection/IdP Communications

In order to communicate with the IdP, the browser must instantiate an isolated interpreted context [TODO: What's the technical term?], such as an invisible IFRAME. The initial contents of the context are loaded from a URI derived from the IdP's domain name. [RTCWEB-SECURITY-ARCH; Section XXX].

For purposes of generating assertions, the IdP shall be chosen as follows:

1. If the setIdentityProvider() method has been called, the IdP provided shall be used.
2. If the setIdentityProvider() method has not been called, then the browser shall use an IdP configured into the browser. If more than one such IdP is configured, the browser should provide the user with a chooser interface.

In order to verify assertions, the IdP domain name and protocol shall be equal to the "domain" and "protocol" fields of the identity assertion.

The context must have a MessageChannel named window.TBD which is "entangled" to the RTCPeerConnection and is unique to that subcontext. This channel is used for messaging between the RTCPeerConnection and the IdP. All messages sent via this channel are strings, specifically the JSONified versions of JavaScript structs.

All messages sent from the RTCPeerConnection to the IdP context must have an origin of rtcweb://peerconnection/. The fact that ordinary Web pages cannot set their origin values arbitrarily is an essential security feature, as it stops attackers from requesting WebRTC-compatible identity assertions from IdPs. For this reason, the origin must be included in the identity assertion and verified by the consuming RTCPeerConnection.

8.1.2 Requesting Assertions

The identity assertion request process involves the following steps.

1. The RTCPeerConnection instantiates an IdP context as described in the previous section.
2. The IdP serves up the IdP JavaScript code to the IdP context.
3. Once the IdP is loaded and ready to receive messages it sends a "READY" message [RTCWEB-SECURITY-ARCH; Section 5.6.5.2]. Note that this does not imply that the user is logged in, merely that enough IdP state is booted up to be ready to handle PostMessage calls.
4. The IdP sends a "SIGN" message (Section 5.6.5.2.2) to the IdP proxy context. This message includes the material the RTCPeerConnection desires to be bound to the user's identity.
5. If the user is not logged in, at this point the IdP will initiate the login process. For instance, it might pop up a dialog box inviting the user to enter their (IdP) username and password.
6. Once the user is logged in (potentially after the previous step), the IdP proxy generates an identity assertion (depending on the authentication protocol this may involve interacting with the IDP server).
7. Once the assertion is generated, the IdP proxy sends a response (Section 5.6.5.2.2) containing the assertion to the RTCPeerConnection over the message channel.
8. The RTCPeerConnection stores the assertion for use with future offers or answers. If the identity request was triggered by a createOffer() or createAnswer(), then the assertion is inserted in the offer/answer.

8.1.3 Verifying Assertions

The identity assertion request process involves the following steps.

1. The RTCPeerConnection instantiates an IdP context as described in the previous section.
2. The IdP serves up the IdP JavaScript code to the IdP context.
3. Once the IdP is loaded and ready to receive messages it sends a "READY" message [RTCWEB-SECURITY-ARCH; Section 5.6.5.2]. Note that this does not imply that the user is logged in, merely that enough IdP state is booted up to be ready to handle PostMessage calls.
4. The IdP sends a "VERIFY" message (Section 5.6.5.2.2) to the IdP proxy context. This message includes assertion from the offer/answer which is to be verified.
5. The IdP proxy verifies the identity assertion (depending on the authentication protocol this may involve interacting with the IDP server).
6. Once the assertion is verified the IdP proxy sends a response containing the verified assertion results (Section 5.6.5.2.3) to the RTCPeerConnection over the message channel.
7. The RTCPeerConnection displays the assertion information in the browser UI and stores the assertion in the peerIdentity attribute for availability to the JavaScript application. The assertion information to be displayed shall contain the domain name of the IdP and the identity returned by the IdP and must be displayed via some mechanism which cannot be spoofed by content. [[OPEN ISSUE: The identity information should also be available in the inspector interface defined in [RTCWEB-SECURITY-ARCH; Section 5.5].

8.2.1 Attributes

onidentityresult of type EventHandler

This event handler, of event handler event type identityresult, must be fired by all objects implementing the RTCPeerConnection interface. It is called any time an identity verification succeeds or fails.

peerIdentity of type RTCIdentityAssertion, readonly, nullable

Contains the peer identity assertion information if an identity assertion was provided and verified.

8.2.2 Methods

getIdentityAssertion

Initiates the process of obtaining an identity assertion. Applications need not make this call. It is merely intended to allow them to start the process of obtaining identity assertions before a call is initiated. If an identity is needed, either because the browser has been configured with a default identity provider or because the setIdentityProvider() method was called, then an identity will be automatically requested when an offer or answer is created.

Queue a task to run the following substeps.

1. If the connection's RTCPeerConnection signalingState is closed, abort these steps.

2. Instantiate a new IdP proxy and request an identity assertion.

No parameters.

Return type: void

setIdentityProvider

Sets the identity provider to be used for a given PeerConnection object. Applications need not make this call; if the browser is already configured for an IdP, then that configured IdP will be used to get an assertion.

When the setIdentityProvider() method is invoked, the user agent must run the following steps:

1. Set the current identity values to the triplet (provider, protocol, username).

2. If the RTCPeerConnection object's RTCPeerConnection signalingState is stable, and any of the identity settings have changed, queue a task to run the following substeps:

   1. If the connection's RTCPeerConnection signalingState is closed, abort these steps, and throw an exception with an RTCError object of type INVALID_STATE.

   2. Instantiate a new IdP proxy and request an identity assertion.

   3. If/when the assertion is obtained, fire a negotiationneeded event.

Parameter	Type	Nullable	Optional	Description
provider	DOMString	✘	✘
protocol	DOMString	✘	✔
username	DOMString	✘	✔

Return type: void

8.3.1 Dictionary RTCIdentityAssertion Members

idp of type DOMString

A domain name representing the identity provider.

name of type DOMString

An RFC822-conformant [TODO: REF] representation of the verified peer identity. This identity will have been verified via the procedures described in [RTCWEB-SECURITY-ARCH].

9.2.1 id

The id attribute specified in MediaStream returns an id that is unique to this stream, so that streams can be recognized after they are sent through the RTCPeerConnection API.

When a MediaStream is created to represent a stream obtained from a remote peer, the id attribute is initialized from information provided by the remote source.

9.2.2 Events on MediaStream

A new media track may be associated with an existing MediaStream. For example, if a remote peer adds a new MediaStreamTrack object to a MediaStream that is being sent over an RTCPeerConnection, this is observed on the local user agent. If this happens for the reason exemplified, or for any other reason than the addTrack() method being invoked locally on a MediaStream or tracks being added as the stream is created (i.e. the stream is initialized with tracks), the user agent must run the following steps:

1. Let stream be the target MediaStream object.

2. Represent component with track: Run the following steps to create a track representing the incoming component:

   1. Create a MediaStreamTrack object track to represent the component.

   2. Initialize track’s kind attribute to "audio" or "video" depending on the media type of the incoming component.

   3. Initialize track’s id attribute to the component track id.

   4. Initialize track’s label attribute to "remote audio" or "remote video" depending on the media type of the incoming component.

   5. Initialize track’s readyState attribute to muted.

   6. Add track to stream’s track set.

3. Fire a track event named addtrack with the newly created MediaStreamTrack object at stream.

An existing media track may also be disassociated from a MediaStream. If this happens for any other reason than the removeTrack() method being invoked locally on a MediaStream or the stream being destroyed, the user agent must run the following steps:

1. Let stream be the target MediaStream object.

2. Let track be the MediaStreamTrack object representing the media component about to be removed.

3. Remove track from stream’s track set.

4. Fire a track event named removetrack with track at stream.

The event source for the onended event in the networked case is the RTCPeerConnection object.

9.4.1 Attributes

stream of type MediaStream, readonly, nullable

The stream attribute represents the MediaStream object associated with the event.

9.4.2 Dictionary MediaStreamEventInit Members

stream of type MediaStream