addIceCandidate-
+
The addIceCandidate()
+ method provides a remote candidate to the ICE Agent. In addition to
+ being added to the remote description, connectivity checks will be
+ sent to the new candidates as long as the ICE Transports setting is not
+ set to none. This call will result in a change
+ to the connection state of the ICE Agent, and may result in a
+ change to media state if it results in different connectivity being
+ established.
+
+
+ If the candidate parameter is malformed, throw a
+ SyntaxError exception and abort these steps.
+
+
+ If the candidate is successfully applied, the user agent MUST
+ queue a task to invoke successCallback.
+
+
+ If the candidate could not be successfully applied, the user
+ agent MUST queue a task to invoke failureCallback with a
+ DOMError object whose name attribute has
+ the value TBD (TODO InvalidCandidate and InvalidMidIndex).
+
+
+ Note
+ What errors do we need here? Should we reuse the
+ *SessionDescriptionError names or invent new ones for candidates?
+ Should this method be queued?
+
Return type: void
addStream-
+
Adds a new stream to the RTCPeerConnection.
+
+
+ When the addStream() method is invoked, the user agent MUST
+ run the following steps:
+
+
+
+ -
+
Let connection be the
+ RTCPeerConnectionMediaStream, stream, is to be
+ added.
+
+
+
+ -
+
If connection's RTCPeerConnection
+ signalingState is closed, throw an
+ InvalidStateError exception and abort these
+ steps.
+
+
+
+ -
+
If stream is already in connection's
+ local streams set, then abort
+ these steps.
+
+
+
+ -
+
Add stream to connection's local streams set.
+
+
+
+
+ -
+
If connection's RTCPeerConnection
+ signalingState is stable, then fire a negotiationneeded event at
+ connection.
+
+
+ | Parameter | Type | Nullable | Optional | Description |
|---|
| stream | MediaStream | ✘ | ✘ | |
Return type: void
close-
+
When the RTCPeerConnection close() method is invoked, the
+ user agent MUST run the following steps:
+
+
+
+
+ -
+ If the
RTCPeerConnection object's RTCPeerConnection
+ signalingState is closed, abort these steps.
+
+
+ -
+
Destroy the RTCPeerConnection
+ ICE Agent, abruptly ending any active ICE processing and
+ any active streaming, and releasing any relevant resources
+ (e.g. TURN permissions).
+
+
+
+ -
+
Set the object's RTCPeerConnection
+ signalingState to closed.
+
+
+ No parameters.
Return type: void
createAnswer-
+
The createAnswer method generates an [SDP] answer with the
+ supported configuration for the session that is compatible with the
+ parameters in the remote configuration. Like createOffer, the
+ returned blob contains descriptions of the local MediaStreams
+ attached to this RTCPeerConnection, the codec/RTP/RTCP options
+ negotiated for this session, and any candidates that have been
+ gathered by the ICE Agent. The options parameter may be
+ supplied to provide additional control over the generated
+ answer.
+
+
+ As an answer, the generated SDP will contain a specific
+ configuration that, along with the corresponding offer, specifies
+ how the media plane should be established. The generation of the
+ SDP must follow the appropriate process for generating an
+ answer.
+
+
+ Session descriptions generated by createAnswer must be
+ immediately usable by setLocalDescription without generating an
+ error if setLocalDescription is called from the successCallback
+ function. Like createOffer, the returned description should reflect
+ the current state of the system. The session descriptions MUST
+ remain usable by setLocalDescription without causing an error until
+ at least the end of the successCallback function. Calling this
+ method is needed to get the ICE user name fragment and
+ password.
+
+
+ An answer can be marked as provisional, as described in
+ [RTCWEB-JSEP], by setting the type to
+ "pranswer".
+
+
+ If the RTCPeerConnection is configured to generate
+ Identity assertions, then the session description SHALL contain an
+ appropriate assertion.
+
+
+ If this RTCPeerConnection object is closed before
+ the SDP generation process completes, the USER agent MUST suppress
+ the result and not call any of the result callbacks.
+
+
+ If the SDP generation process completed successfully, the user
+ agent MUST queue a task to invoke successCallback with a
+ newly created RTCSessionDescription
+
+
+ If the SDP generation process failed for any reason, the user
+ agent MUST queue a task to invoke failureCallback with
+ an DOMError object of type TBD as its argument.
+ Return type: void
createOffer-
+
The createOffer method generates a blob of SDP that contains an
+ RFC 3264 offer with the supported configurations for the session,
+ including descriptions of the local MediaStreams
+ attached to this RTCPeerConnection, the codec/RTP/RTCP
+ options supported by this implementation, and any candidates that
+ have been gathered by the ICE Agent. The options parameter may
+ be supplied to provide additional control over the offer generated.
+
+
+
+ As an offer, the generated SDP will contain the full set of
+ capabilities supported by the session (as opposed to an answer,
+ which will include only a specific negotiated subset to use); for
+ each SDP line, the generation of the SDP must follow the
+ appropriate process for generating an offer. In the event
+ createOffer is called after the session is established, createOffer
+ will generate an offer that is compatible with the current session,
+ incorporating any changes that have been made to the session since
+ the last complete offer-answer exchange, such as addition or
+ removal of streams. If no changes have been made, the offer will
+ include the capabilities of the current local description as well
+ as any additional capabilities that could be negotiated in an
+ updated offer.
+
+
+ Session descriptions generated by createOffer MUST be
+ immediately usable by setLocalDescription without causing an error
+ as long as setLocalDescription is called within the successCallback
+ function. If a system has limited resources (e.g. a finite number
+ of decoders), createOffer needs to return an offer that reflects
+ the current state of the system, so that setLocalDescription will
+ succeed when it attempts to acquire those resources. The session
+ descriptions MUST remain usable by setLocalDescription without
+ causing an error until at least end of the successCallback
+ function. Calling this method is needed to get the ICE user name
+ fragment and password.
+
+
+ If the RTCPeerConnection is configured to generate
+ Identity assertions, then the session description SHALL contain an
+ appropriate assertion.
+
+
+ If this RTCPeerConnection object is closed before
+ the SDP generation process completes, the USER agent MUST suppress
+ the result and not call any of the result callbacks.
+
+
+ If the SDP generation process completed successfully, the user
+ agent MUST queue a task to invoke successCallback with a
+ newly created RTCSessionDescription
+
+
+ If the SDP generation process failed for any reason, the user
+ agent MUST queue a task to invoke failureCallback with
+ an DOMError object of type TBD as its argument.
+
+
+ To Do: Discuss privacy aspects of this from a fingerprinting
+ point of view - it's probably around as bad as access to a canvas
+ :-)
+ Return type: void
getConfiguration-
+
Returns a RTCConfigurationRTCPeerConnection
+
+
+ When this method is call, the user agent MUST construct new RTCConfiguration
+ No parameters.
getLocalStreams-
+
Returns a sequence of MediaStream objects
+ representing the streams that are currently sent with this
+ RTCPeerConnection
+
+
+ The getLocalStreams()
+ method MUST return a new sequence that represents a snapshot of all
+ the MediaStream objects in this
+ RTCPeerConnection
+ No parameters.
getRemoteStreams-
+
Returns a sequence of MediaStream objects
+ representing the streams that are currently received with this
+ RTCPeerConnection
+
+
+ The getRemoteStreams()
+ method MUST return a new sequence that represents a snapshot of all
+ the MediaStream objects in this
+ RTCPeerConnection
+ No parameters.
getStreamById-
+
If a MediaStream object, with an
+ id
+ equal to streamId, exists in this
+ RTCPeerConnectiongetStreamById()
+ method MUST return that MediaStream object. The
+ method MUST return null if no stream matches the
+ streamId argument.
+
+
+ Note
+
For this method to make sense, we need to make sure that ids
+ are unique within the two stream sets of a RTCPeerConnection.
+ This is not the case today when a peer re-adds a stream that is
+ received. Two different stream instances will now have the same
+ id at both peers; one in the remote stream set and one in the
+ local stream set.
+
+
+
One way to resolve this is to not allow re-adding a stream
+ instance that is received (guard on id). If an application really
+ needs this functionality it's really easy to make a clone of the
+ stream, which will give it a new id, and send the clone.
+
| Parameter | Type | Nullable | Optional | Description |
|---|
| streamId | DOMString | ✘ | ✘ | |
removeStream-
+
Removes the given stream from the
+ RTCPeerConnection
+
+
+ When the other peer stops sending a stream in this manner, a
+ removestream event is
+ fired at the RTCPeerConnection
+
+
+ When the removeStream() method is invoked, the user agent
+ MUST run the following steps:
+
+
+
+ -
+
Let connection be the
+ RTCPeerConnectionMediaStream, stream, is to be
+ removed.
+
+
+
+ -
+
If connection's RTCPeerConnection
+ signalingState is closed, throw an
+ InvalidStateError exception.
+
+
+
+ -
+
If stream is not in connection's
+ local streams set, then abort
+ these steps.
+
+
+
+ -
+
Remove stream from connection's
+ local streams set.
+
+
+
+ -
+
If connection's RTCPeerConnection
+ signalingState is stable, then fire a negotiationneeded event at
+ connection.
+
+
+ | Parameter | Type | Nullable | Optional | Description |
|---|
| stream | MediaStream | ✘ | ✘ | |
Return type: void
setLocalDescription-
+
The setLocalDescription()
+ method instructs the RTCPeerConnectionRTCSessionDescription
+
+
+ This API changes the local media state. In order to successfully
+ handle scenarios where the application wants to offer to change
+ from one media format to a different, incompatible format, the
+ RTCPeerConnectionRTCPeerConnection
+
+
+ Issue 1
ISSUE: how to indicate to rollback?
To Do: specify what parts of the SDP can be changed between the
+ createOffer and setLocalDescription
+
+
+ When the method is invoked, the user agent must follow the
+ processing model described by
+ the following list:
+
+
+
+ -
+
If this RTCPeerConnectionclosed, the user agent MUST throw an
+ InvalidStateError exception and abort this
+ operation.
+
+
+
+ -
+
If a local description contains a different set of ICE
+ credentials, then the ICE Agent MUST trigger an ICE restart.
+ When ICE restarts, the gathering state will be changed back to
+ "gathering", if it was not already gathering. If the
+ IceConnectionState was "completed", it will be changed back to
+ "connected".
+
+
+
+ -
+
If the process to apply the
+ RTCSessionDescription
+
+
+
+ -
+
Let connection be the
+ RTCPeerConnection
+
+
+
+ -
+
If connection's signaling state
+ is closed, then abort these steps.
+
+
+
+ -
+
If the reason for the failure is:
+
+
+
+ -
+
The content of the
+ RTCSessionDescriptiontype is
+ wrong for the current signaling
+ state of connection.
+
+
+ Let errorType be
+ InvalidSessionDescriptionError.
+
+
+
+ -
+
The RTCSessionDescription
+
+
+ TODO ISSUE - next few points are probably wrong.
+ Make sure to check this in setRemote too.
+
+
+ This can happen, e.g., if there are insufficient
+ resources to apply the SDP. The user agent MUST then
+ rollback as necessary if the new description was
+ partially applied when the failure occurred.
+
+
+ If rollback was not necessary or was completed
+ successfully, let errorType be
+ IncompatibleSessionDescriptionError. If
+ rollback was not possible, let errorType be
+ InternalError and set
+ connection's signaling
+ state to closed.
+
+
+
+
+
+ -
+
Invoke the failureCallback with an
+ DOMError object, whose name
+ attribute is errorType, as its argument.
+
+
+
+
+
+ -
+
If the RTCSessionDescription
+
+
+
+ -
+
Let connection be the
+ RTCPeerConnection
+
+
+
+ -
+
If connection's signaling state
+ is closed, then abort these steps.
+
+
+
+ -
+
Set connection's description attribute
+ (localDescription or
+ remoteDescription depending on the
+ setting operation) to the
+ RTCSessionDescription
+
+
+
+ -
+
If the local description was set,
+ connection's ice gathering
+ state is new, and the local description
+ contains media, then set connection's ice gathering
+ state to gathering.
+
+
+
+ -
+
If the local description was set with content that
+ caused an ICE restart, then set connection's
+ ice
+ gathering state to gathering.
+
+
+
+ -
+
Set connection's signalingState
+ accordingly.
+
+
+
+ -
+
Fire a simple event named signalingstatechange
+ at connection.
+
+
+
+ -
+
Queue a new task that, if connection's
+ signalingState is
+ not closed, invokes the
+ successCallback.
+
+
+
+
+ Return type: void
setRemoteDescription-
+
The setRemoteDescription()
+ method instructs the RTCPeerConnectionRTCSessionDescription
+
+
+ If a=identity attributes are present, the browser
+ verifies the identity following the procedures in [TODO REF to
+ SECTION ACTION MARTIN TO GO DO THIS
+ sec.identity-proxy-assertion-request].
+
+
+ If any tracks on the RTCPeerConnection have a
+ peerIdentity constraint and either the RTCPeerConnection
+ connection has no peer identity or that identity is not equal to
+ the specified peerIdentity, the user agent MUST queue a
+ task to invoke failureCallback with a
+ DOMError object whose name attribute has
+ the value IncompatibleConstraintsError. Media must not
+ be transmitted to the other side in this case.
+
+ Note
Open Issue:
+ Waiting for Martin to see if the above should send black instead of
+ doing what is above.
When the method is invoked, the user agent must follow the
+ processing model of
+ setLocalDescription()
+ .
+ Return type: void
updateIce-
+
The updateIce method updates the ICE Agent process of gathering
+ local candidates and pinging remote candidates.
+
+
+ This call may result in a change to the state of the ICE Agent,
+ and may result in a change to media state if it results in
+ connectivity being established.
+
+
+ When the updateIce()
+ method is invoked, the user MUST run the following steps to
+ process the RTCConfiguration
+
+
+
+ -
+
If the iceTransports member
+ is present, let its value be the ICE Agent's ICE transports setting.
+
+
+
+ -
+
If the iceTransports member
+ was omitted and the ICE Agent's ICE transports setting is unset,
+ set the ICE Agent's ICE transports setting to the iceTransports
+ dictionary member default value.
+
+
+
+ -
+
If the iceServers dictionary
+ member is present, but its value is an empty list, then throw
+ an InvalidAccessError and abort these steps. If
+ the list, on the other hand, has elements, each element must be
+ validated by running the following sub-steps:
+
+
+
+ -
+
Let server be the current list element.
+
+
+
+ -
+
If the server.urls dictionary member is
+ omitted or an empty list, then throw an
+ InvalidAccessError and abort these steps.
+
+
+
+ -
+
If server.urls is a string, let
+ urls be a list consisting of just that string.
+ Otherwise, let urls refer to the
+ server.urls list.
+
+
+
+ -
+
For each url in urls, parse the url and
+ obtain scheme name. If the parsing fails or if
+ scheme name is not implemented by the browser,
+ throw a SyntaxError and abort these steps.
+
+
+
+ -
+
If scheme name is "turn" and either of the
+ dictionary members server.username or
+ server.credential are omitted, then throw an
+ InvalidAccessError and abort these steps.
+
+
+
+ After passing the validation, let the iceServers
+ dictionary member be the ICE Agent's ICE servers list.
+
+ If a new list of servers replaces the ICE Agent's existing
+ ICE servers list, no action will taken until the
+ RTCPeerConnection's ice gathering
+ state transitions to gathering. If a script
+ wants this to happen immediately, it should do an ICE restart.
+
+
+
-
+
If the iceServers dictionary
+ member was omitted, and the ICE Agent's ICE servers list is unset, throw an
+ InvalidAccessError and abort these steps.
+
+
+
+
+ Note
+ The exception types throw in the above algorithm are provisional
+ (until we decide what to do in each case).
+
Return type: void
+