- From: Anant Narayanan via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 16 Aug 2012 17:19:00 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2011/webrtc/editor
In directory hutz:/tmp/cvs-serv5538/editor
Modified Files:
webrtc.html webrtc.js
Added Files:
webrtc-20120816.html
Log Message:
Updating draft to github version webrtc-20120816.html
Index: webrtc.html
===================================================================
RCS file: /sources/public/2011/webrtc/editor/webrtc.html,v
retrieving revision 1.21
retrieving revision 1.22
diff -u -d -r1.21 -r1.22
--- webrtc.html 13 Aug 2012 19:14:21 -0000 1.21
+++ webrtc.html 16 Aug 2012 17:18:58 -0000 1.22
@@ -24,14 +24,13 @@
<body>
<section id="abstract">
- <p>This document defines a set of APIs to represent streaming media,
- including audio and video, in JavaScript, to allow media to be sent over
- the network to another browser or device implementing the appropriate set
- of real-time protocols, and media received from another browser or device
- to be processed and displayed locally. This specification is being
- developed in conjunction with a protocol specification developed by the
- IETF RTCWEB group and an API specification to get access to local media
- devices developed by the Media Capture Task Force.</p>
+ <p>This document defines a set of ECMAScript APIs in WebIDL to allow media
+ to be sent over the network to another browser or device implementing the
+ appropriate set of real-time protocols, and media to be received from
+ another browser or device. This specification is being developed in
+ conjunction with a protocol specification developed by the IETF RTCWEB group
+ and an API specification to get access to local media devices developed by
+ the Media Capture Task Force.</p>
</section>
<section id="sotd">
@@ -136,7 +135,8 @@
<p>A <code>MediaStream</code> as defined in [[!GETUSERMEDIA]] may contain
zero or more <code>MediaStreamTrack</code> objects. A
<code>MediaStreamTrack</code> sent to another peer will appear as one and
- only one <code>MediaStreamTrack</code> to the recipient.</p>
+ only one <code>MediaStreamTrack</code> to the recipient. A peer is
+ defined as a user agent that supports this specification.</p>
<p>Channels are the smallest unit considered in the
<code>MediaStream</code> specification. Channels are intended to be
@@ -169,13 +169,12 @@
<section>
<h3>Interface definitions</h3>
- <p class="note">In this section, we only specify aspects of the the
+ <p class="note">In this section, we only specify aspects of the
following objects that are relevant when used along with a
<code><a>RTCPeerConnection</a></code>. Please refer to the original
definitions of the objects in the [[!GETUSERMEDIA]] document for general
information on using <code>MediaStream</code> and
- <code>MediaStreamTrack</code> both in and outside the context of
- <code><a>RTCPeerConnection</a></code>.</p>
+ <code>MediaStreamTrack</code>.
<section>
<h4>MediaStream</h4>
@@ -197,24 +196,25 @@
<p class="note">The label of a <code><a>MediaStream</a></code> object
is unique to the source of the stream, but that does not mean it is
not possible to end up with duplicates. For example, a locally
- generated stream could be sent from one user to a remote peer using
- <code><a>RTCPeerConnection</a></code> , and then sent back to the
- original user in the same manner, in which case the original user
- will have multiple streams with the same label (the locally-generated
- one and the one received from the remote peer).</p>
+ generated stream could be sent from one user agent to a remote peer
+ using <code><a>RTCPeerConnection</a></code> ,and then sent back to the
+ original user agent in the same manner, in which case the original
+ user agent will have multiple streams with the same label (the
+ locally-generated one and the one received from the remote peer).</p>
</section>
<section>
<h4>Events on MediaStream</h4>
- <p>A new media component may be associated with an existing
- <code><a>MediaStream</a></code> . This happens, e.g., on the A-side
- when the B-side adds a new <code><a>MediaStreamTrack</a></code>
- object to one of the track lists of a <code><a>MediaStream</a></code>
- that is being sent over a <code><a>RTCPeerConnection</a></code> . If
- this happens for the reason exemplified, or for any other reason than
- the <code>add()</code> [[!GETUSERMEDIA]] method being invoked locally
- on a <code><a>MediaStreamTrackList</a></code> or tracks are being
+ <p>A new media track may be associated with an existing
+ <code><a>MediaStream</a></code> . For example, if a remote peer
+ adds a new <code><a>MediaStreamTrack</a></code> object to one of the
+ track lists of a <code><a>MediaStream</a></code> that is being sent
+ over a <code><a>RTCPeerConnection</a></code>, this is observed on
+ the local user agent. If this happens for the reason exemplified, or
+ for any other reason than the <code>add()</code> [[!GETUSERMEDIA]]
+ method being invoked locally on a
+ <code><a>MediaStreamTrackList</a></code> or tracks are being
added as the stream is created (i.e. the stream is initialized with
tracks), the user agent MUST run the following steps:</p>
@@ -231,9 +231,6 @@
<code><a>MediaStream</a></code> object’s <code><a href=
"getusermedia.html#dom-mediastream-audiotracks">audioTracks</a></code>
<code><a>MediaStreamTrackList</a></code> object.</p>
-
- <p class="issue">ISSUE: Is there a way to generalize this so that
- if we add a "smell" track this continues to work.</p>
</li>
<li>
@@ -253,7 +250,7 @@
</li>
</ol>
- <p>An existing media component may also be disassociated from a
+ <p>An existing media track may also be disassociated from a
<code><a>MediaStream</a></code> . If this happens for any other
reason than the <code>remove()</code> [[!GETUSERMEDIA]] method being
invoked locally on a <code><a>MediaStreamTrackList</a></code> or the
@@ -309,11 +306,12 @@
media data arrives.</p>
<p>In addition, a <code>MediaStreamTrack</code> has its
- <code>readyState</code> set to <code>MUTED</code> on the B-side if the
- A-side disables the corresponding <code><a>MediaStreamTrack</a></code>
- in the <code><a>MediaStream</a></code> that is being sent. When the
- addstream event triggers on a <code><a>RTCPeerConnection</a></code> ,
- all <code><a>MediaStreamTrack</a></code> objects in the resulting
+ <code>readyState</code> set to <code>MUTED</code> on the remote peer if
+ the local user agent disables the corresponding
+ <code><a>MediaStreamTrack</a></code> in the
+ <code><a>MediaStream</a></code> that is being sent. When the addstream
+ event triggers on a <code><a>RTCPeerConnection</a></code>, all
+ <code><a>MediaStreamTrack</a></code> objects in the resulting
<code><a>MediaStream</a></code> are muted until media data can be read
from the RTP source.</p>
@@ -325,12 +323,11 @@
<section>
<h4>AudioMediaStreamTrack</h4>
- <p class="issue">ISSUE: The DTMF API is having a bunch of list discussion
- and will probably change. </p>
-
+ <p class="note">The DTMF API is having a bunch of list discussion and
+ will probably change.</p>
- <p>The <code><a>AudioMediaStreamTrack</a></code> is a specialization of
- of a normal <code><a>MediaStreamTrack</a></code> that only carries audio
+ <p>The <code><a>AudioMediaStreamTrack</a></code> is a specialization of a
+ normal <code><a>MediaStreamTrack</a></code> that only carries audio
and is extended to have the capability to send and/or receive DTMF
codes.</p>
@@ -351,13 +348,13 @@
<dd>
<p>When a <code><a>AudioMediaStreamTrack</a></code> object’s <dfn id=
"dom-AudioMediaStreamTrack-insertDTMF"><code>insertDTMF()</code></dfn>
- method is invoked, the user agent MUST queue a task that that sends
- the DTMF tones.</p>
+ method is invoked, the user agent MUST queue a task that sends the
+ DTMF tones.</p>
<p>The tone parameters is treated as a series of characters. The
characters 0 to 9, A to D, #, and * generated the associated DTMF
- tones. The characters a to d are equivalent to A to D. The character
- , indicates a an delay of 2 seconds before processing the next
+ tones. The characters a to d are equivalent to A to D. The character,
+ indicates a an delay of 2 seconds before processing the next
character in the tones parameter. Unrecognized characters are
ignored.</p>
@@ -370,9 +367,9 @@
<p class="issue">ISSUE: How are invalid values handled?</p>
<p>If insertDTMF is called on the same object while an existing task
- for this object is generate DTMF is still running, the previous task
+ for this object to generate DTMF is still running, the previous task
is canceled. Calling insertDTMF with an empty tones parameter can be
- used to cancel any tones currently being send.</p>
+ used to cancel any tones currently being sent.</p>
<p class="note">Editor Note: We need to add a callback that is set on
the object that is called after the tones are sent. This is needed to
@@ -404,8 +401,8 @@
[[!STUN]] and [[!TURN]] servers. There may be multiple servers of each type
and any TURN server also acts as a STUN server.</p>
- <p>A RTCPeerConnection object has an associated ICE Agent,
- RTCPeerConnection state, and ICE State. These are initialized when the
+ <p>A RTCPeerConnection object has an associated ICE agent,
+ RTCPeerConnection state, and ICE state. These are initialized when the
object is created.</p>
<p>When the <dfn id=
@@ -473,46 +470,47 @@
<ol>
<li>
- <p>If the ice state is "new" and the IceTransports constraint is not
- set to "none", it MUST queue a task to start gathering ICE address and
- set the ice state to "gathering".</p>
+ <p>If <var>iceState</var> is "new" and the IceTransports constraint is
+ not set to "none", it MUST queue a task to start gathering ICE address
+ and set the <var>iceState</var> to "gathering".</p>
</li>
<li>
<p>If the ICE Agent has found one or more candidate pairs for any
- MediaTrack that forms a valid connection, the ICE state is changed to
- "connected".</p>
+ MediaStreamTrack that forms a valid connection, the ICE state is changed
+ to "connected".</p>
</li>
<li>
<p>When the ICE Agent finishes checking all candidate pairs, if at
- least one connection has been found for some MediaTrack, the iceState
- is changed to "completed" and if no connection has been found for any
- MediaTrack, the iceState is changed to "failed".</p>
+ least one connection has been found for some MediaStreamTrack, the
+ <var>iceState</var> is changed to "completed" and if no connection has
+ been found for any MediaStreamTrack, the iceState is changed to
+ "failed".</p>
<p class="issue">ISSUE: Note that this means that if I was able to
- negotiate audio but not video via ICE, then iceState == "completed". Is
- this really what is desired?</p>
+ negotiate audio but not video via ICE, then <var>iceState</var> ==
+ "completed". Is this really what is desired?</p>
</li>
<li>
- <p>If the iceState is "connected" or "completed" and both the local and
- remote session descriptions are set, the peerState is set to
- "active".</p>
+ <p>If the <var>iceState</var> is "connected" or "completed" and both the
+ local and remote session descriptions are set, the RTCPeerConnection
+ state is set to "active".</p>
</li>
<li>
- <p>If the iceState is "failed", a task is queued to calls the close
- method.</p>
+ <p>If the <var>iceState</var> is "failed", a task is queued to calls the
+ close method.</p>
<p class="issue">ISSUE:: CJ - this seems wrong to me.</p>
</li>
</ol>
<p>User agents negotiate the codec resolution, bitrate, and other media
- parameters. User agents are encouraged to initially negotiate for the
+ parameters. User agents are RECOMMENDED to initially negotiate for the
maximum resolution of a video stream. For streams that are then rendered
- (using a <code>video</code> element), user agents are encouraged to
+ (using a <code>video</code> element), user agents are RECOMMENDED to
renegotiate for a resolution that matches the rendered display size.</p>
<p class="note">Starting with the native resolution means that if the Web
@@ -521,7 +519,7 @@
there will be no need for a renegotiation once the stream is flowing.</p>
<!--
<p>All SDP media descriptions for RTP flows represented by <code>
- <a>MediaTrack</a>
+ <a>MediaStreamTrack</a>
</code> objects MUST include a label attribute ("<code
title="">a=label:</code>") whose value is the value of the <code>
<a>MediaStream</a>
@@ -551,12 +549,10 @@
<li>
<p>Create a <code><a>MediaStream</a></code> object to represent the
- media stream.
+ media stream.
<!-- Set its <code> <a href="#dom-mediastream-label">label</a>
</code> attribute to the value of the SDP Label attribute for that
component's media stream. --></p>
-
- <p class="issue">ISSUE: What if one already exists?</p>
</li>
<li>
@@ -590,7 +586,7 @@
<p class="note">The creation of new incoming <code>MediaStream</code>s
may be triggered either by SDP negotiation or by the receipt of media
- on a given flow.
+ on a given flow.
<!-- [[OPEN ISSUE: How many <code>MediaStream</code>s are created
when you receive multiple conflicting pranswers?]] --></p>
@@ -698,8 +694,8 @@
<p>If something in the browser changes that causes the
<code><a>RTCPeerConnection</a></code> object to need to initiate a new
- session descipriton negotiation, an <code><a href=
- "#event-renegotiation">renegotiationneeded</a></code> event is fired at the
+ session description negotiation, an <code><a href=
+ "#event-negotiation">negotiationneeded</a></code> event is fired at the
<code><a>RTCPeerConnection</a></code> object.</p>
<p>In particular, if a <code><a>RTCPeerConnection</a></code> object is
@@ -709,8 +705,8 @@
<code><a href=
"getusermedia.html#dom-mediastreamtracklist-add">add()</a></code> method
being invoked, the <code><a>RTCPeerConnection</a></code> object MUST fire
- the "renegotiationneeded" event. Removal of media components must also
- trigger "renegotianneeded".</p>
+ the "negotiationneeded" event. Removal of media components must also
+ trigger "negotiationneeded".</p>
<p class="warning">To prevent network sniffing from allowing a fourth party
to establish a connection to a peer using the information sent out-of-band
@@ -764,30 +760,64 @@
<p>The <dfn id=
"dom-sessiondescription"><code>RTCSessionDescription()</code></dfn>
- constructor takes one argument, <var>description</var>, whose content
- is used to construct the new <code><a>RTCSessionDescription</a></code>
- object. This class is a future extensible carrier for for the data
- contained in it and does not perform any substantive processing.</p>
+ constructor takes an optional dictionary argument,
+ <var>descriptionInitDict</var>, whose content is used to initialize the
+ new <code><a>RTCSessionDescription</a></code> object. If a dictionary
+ key is not present in <var>descriptionInitDict</var>, 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.</p>
- <dl class="idl" title=
- "[Constructor (DOMString description)] interface RTCSessionDescription">
- <dt>attribute RTCSdpType type</dt>
+ <dl class="idl" data-merge="RTCSessionDescriptionInit" title=
+ "[Constructor (optional RTCSessionDescriptionInit descriptionInitDict)]
+ interface RTCSessionDescription">
+ <dt>attribute RTCSdpType? type</dt>
<dd>What type of SDP this RTCSessionDescription represents.</dd>
- <dt>attribute DOMString sdp</dt>
+ <dt>attribute DOMString? sdp</dt>
<dd>The string representation of the SDP [[!SDP]]</dd>
- <!-- FIXME: this syntax is not fully supported by ReSpec -->
<dt>stringifier DOMString ()</dt>
<dd>
- <p>Objects that implement the
- <code><a>RTCSessionDescription</a></code> interface must stringify
- as [[!SDP]].</p>
+ <p>Objects implementing the <code><a>RTCSessionDescription</a>
+ </code> interface MUST stringify by running the steps below. Let
+ <code><a href="#widl-RTCSessionDescription-type">type</a></code>
+ and <code><a href="#widl-RTCSessionDescription-sdp">sdp</a></code>
+ be the elements of <var>attributeList</var>, the list of attributes
+ to include in the string representation.</p>
+
+ <ol>
+ <li>
+ <p>Let <var>result</var> be U+0028 LEFT PARENTHESIS U+007B LEFT
+ CURLY BRACKET.</p>
+ </li>
+
+ <li>
+ <p>For each attribute in <var>attributeList</var> append, to
+ <var>result</var>, the attribute name, U+003A COLON U+0022
+ QUOTATION MARK, the attribute value, U+0022 QUOTATION MARK and
+ U+002C COMMA. If the attribute was the last element in
+ <var>attributeList</var>, then remove the last U+002C COMMA.</p>
+ </li>
+
+ <li>
+ <p>Append U+007D RIGTH CURLY BRACKET U+0029 RIGHT PARENTHESIS to
+ <var>result</var> and return <var>result</var>.</p>
+ </li>
+ </ol>
</dd>
</dl>
+
+ <dl class="idl" title=
+ "dictionary RTCSessionDescriptionInit">
+ <dt>RTCSdpType type</dt>
+
+ <dt>DOMString sdp</dt>
+ </dl>
</section>
<section>
@@ -816,13 +846,9 @@
<dd>
Information about what went wrong.
- <p class="issue">ISSUE: How does this work? Is it human readable?
- I18N? ENUM?</p>
+ <p class="issue">ISSUE: Should this be an enum?</p>
</dd>
</dl>
-
- <p class="issue">ISSUE: should this be defined as event like
- NavigatorUserMediaErrorCallback in getusermedia</p>
</section>
<section>
@@ -863,7 +889,7 @@
<section>
<h3>RTCIceState Enum</h3>
- <p class="issue">ISSUE: There is active discussion around changing
+ <p class="note">There is active discussion around changing
these states.</p>
<dl class='idl' title='enum RTCIceState'>
@@ -914,27 +940,30 @@
<h3>RTCIceCandidate Type</h3>
<p>The <dfn id="dom-icecandidate"><code>RTCIceCandidate()</code></dfn>
- constructor takes one argument, <var>candidate</var>, whose content is
- used to construct the new <code><a>RTCIceCandidate</a></code> object.
- This class is a future extensible carrier for for the data contained in
+ constructor takes an optional dictionary argument,
+ <var>candidateInitDict</var>, whose content is used to initialize the
+ new <code><a>RTCIceCandidate</a></code> object. If a dictionary
+ key is not present in <var>candidateInitDict</var>, 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.</p>
- <p>Note: TODO - the constructor needs some work here</p>
-
- <dl class="idl" title=
- "[Constructor (DOMString candidate)] interface RTCIceCandidate">
- <dt>attribute DOMString candidate</dt>
+ <dl class="idl" data-merge="RTCIceCandidateInit" title=
+ "[Constructor (optional RTCIceCandidateInit candidateInitDict)]
+ interface RTCIceCandidate">
+ <dt>attribute DOMString? candidate</dt>
<dd>This carries the candidate-attribute as defined in section 15.1
of [[!ICE]].</dd>
- <dt>attribute DOMString? sdpMid;</dt>
+ <dt>attribute DOMString? sdpMid</dt>
<dd>If present, this contains the identierfier of the "media stream
identification" as defined in [RFC 3388] for m-line this candidate is
assocated with.</dd>
- <dt>attribute unsigned short sdpMLineIndex;</dt>
+ <dt>attribute unsigned short? sdpMLineIndex</dt>
<dd>This indeicates the index (starting at zero) of m-line in the SDP
this candidate is assocated with.</dd>
@@ -942,8 +971,23 @@
<dt>stringifier DOMString ()</dt>
<dd>Objects that implement the <code><a>RTCIceCandidate</a></code>
- interface must stringify as the candidate-attribute as defined in
- section 15.1 of [[ICE]].</dd>
+ interface must stringify as defined by the <code>
+ <a>RTCSessionDescription</a></code> <code><a
+ href="#widl-RTCSessionDescription-DOMString-stringifier">stringifier
+ algorithm</a></code> with <code><a
+ href="#widl-RTCIceCandidate-candidate">candidate</a></code>, <code>
+ <a href="#widl-RTCIceCandidate-sdpMid">sdpMid</a></code>, <code>
+ <a href="#widl-RTCIceCandidate-sdpMLineIndex">sdpMLineIndex</a></code>
+ as the elements of <var>attributeList</var>.</dd>
+ </dl>
+
+ <dl class="idl" title=
+ "dictionary RTCIceCandidateInit">
+ <dt>DOMString candidate</dt>
+
+ <dt>DOMString sdpMid</dt>
+
+ <dt>unsigned short sdpMLineIndex</dt>
</dl>
</section>
@@ -992,8 +1036,7 @@
<section>
<h3>RTCPeerConnection Interface</h3>
- <p class="issue">ISSUE: "optional optional" occurs twice several times
- in the following class description.</p>
+ <dl class="idl" title="typedef MediaStream[] MediaStreamArray">
<dl class="idl" title=
"[Constructor (RTCConfiguration configuration, optional MediaConstraints
@@ -1021,12 +1064,12 @@
-->
<dt>void createOffer (RTCSessionDescriptionCallback successCallback,
- optional RTCPeerConnectionErrorCallback failureCallback, optional
+ optional RTCPeerConnectionErrorCallback failureCallback,
MediaConstraints constraints)</dt>
<dd>
<p>The createOffer method generates a blob of SDP that contains a
- RFC offer with the supported configurations for the session,
+ 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
@@ -1066,8 +1109,6 @@
<p>A TBD exception is thrown if the constraints parameter is
malformed.</p>
- <p class="issue">ISSUE: How are errors reported?</p>
-
<p>To Do: Discuss privacy aspects of this from a finger printing
point of view - it's probably around as bad as access to a canvas
:-)</p>
@@ -1075,9 +1116,8 @@
<dt>void createAnswer (RTCSessionDescription offer,
RTCSessionDescriptionCallback successCallback, optional
- RTCPeerConnectionErrorCallback failureCallback, optional
- MediaConstraints constraints, optional boolean
- createProvisionalAnswer = false)</dt>
+ RTCPeerConnectionErrorCallback failureCallback, MediaConstraints
+ constraints, boolean createProvisionalAnswer = false)</dt>
<dd>
<p>The createAnswer method generates a [[!SDP]] answer with the
@@ -1102,11 +1142,11 @@
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 is needed to get the ICE user name fragment and password.
+ method is needed to get the ICE user name fragment and password.
Provisional offers, as described in [[RTCWEB-JSEP]], are created if
and only if the createProvisionalOffer flag is true.</p>
- <p>The failureCallback will be called if the system can not
+ <p>The failureCallback will be called if the system cannot
generate an appropriate answer given the offer.</p>
<p>A TBD exception is thrown if the constraints parameter is
@@ -1115,7 +1155,7 @@
<dt>void setLocalDescription (RTCSessionDescription description,
optional RTCVoidCallback successCallback,
- optional RTCPeerConnectionErrorCallback failureCallback)</dt>
+ RTCPeerConnectionErrorCallback failureCallback)</dt>
<dd>
<p>The <dfn id=
@@ -1171,7 +1211,7 @@
</dd>
<dt>void setRemoteDescription (RTCSessionDescription description,
- optional RTCVoidCallback successCallback, optional
+ optional RTCVoidCallback successCallback,
RTCPeerConnectionErrorCallback failureCallback)</dt>
<dd>
@@ -1179,19 +1219,19 @@
"dom-peerconnection-setremotedescription"><code>setRemoteDescription()</code></dfn>
method instructs the <code><a>RTCPeerConnection</a></code> to apply
the supplied <code><a>RTCSessionDescription</a></code> as the
- remote description. This API changes the local media state.</p>
+ remote offer or answer. This API changes the local media state.</p>
<p>Changes to the state of media transmission will occur when a
- final answer is successfully applied. <code><a>remoteDescription</a></code>
- MUST return the previous description until the new
- description is successfully applied.</p>
+ final answer is successfully applied.
+ <code><a>remoteDescription</a></code> MUST return the previous
+ description until the new description is successfully applied.</p>
<p>The <code>failureCallback</code> will be called if the
- <code><a>RTCSessionDescription</a></code> is a valid description but cannot be
- applied at the media layer, e.g., if there are
- insufficient resources to apply the SDP. The user agent
- MUST roll back as necessary if the new description was
- partially applied when the failure occurred.</p>
+ <code><a>RTCSessionDescription</a></code> is a valid description but
+ cannot be applied at the media layer, e.g., if there are
+ insufficient resources to apply the SDP. The user agent MUST roll
+ back as necessary if the new description was partially applied when
+ the failure occurred.</p>
<p>A TBD exception is thrown if the SDP content is invalid.</p>
</dd>
@@ -1223,14 +1263,14 @@
readiness state</a>.</p>
</dd>
- <dt>void updateIce (optional RTCConfiguration configuration, optional
- MediaConstraints constraints, optional boolean restart=false)</dt>
+ <dt>void updateIce (optional RTCConfiguration configuration,
+ MediaConstraints constraints, boolean restart = false)</dt>
<dd>
<p>The updateIce method restarts or updates the ICE Agent process
of gathering local candidates and pinging remote candidates. If
there is a mandatory constraint called "IceTransports" it will
- control which how the ICE engine can act. This can be used to limit
+ control how the ICE engine can act. This can be used to limit
the use to TURN candidates by a callee to avoid leaking location
information prior to the call being accepted.</p>
@@ -1241,7 +1281,7 @@
<p>If the restart parameter is set to true, the ICE state machine
discards all candidates it has gathered, allocates new ports for
the host candidates, and restarts ICE as if there had been no
- previos ICE session. Applications can use this to reset all ICE
+ previous ICE session. Applications can use this to reset all ICE
negotiation when something has gone terribly wrong.</p>
<p>A TBD exception will be thrown if constraints parameter is
@@ -1272,15 +1312,11 @@
MUST return the state of the <a href=
"#peerconnection-ice-agent"><code>RTCPeerConnection</code> ICE
Agent</a> ICE state.</p>
- </dd><!-- FIXME: MediaStream[] breaks respec -->
+ </dd>
<dt>readonly attribute MediaStreamArray localStreams</dt>
<dd>
- <p class="issue">ISSUE: Specifying "readonly attribute
- MediaStream[]" breaks rendering of methods in this interface. Using
- MediaStreamArray temporarily.</p>
-
<p>Returns a live array containing the local streams (those that
were added with <code title=
"dom-RTCPeerConnection-addStream"><a href=
@@ -1477,7 +1513,7 @@
</li>
<li>
- <p>Fire a renegotiationneeded event.</p>
+ <p>Fire a negotiationneeded event.</p>
<p class="issue">ISSUE: Should this fire if the
RTCPeerConnection is in "new"?</p>
@@ -1489,7 +1525,7 @@
<dd>
<p>Removes the given stream from the localStream array in the
- RTCPeerConnection and fires 'renegotiationneeded.</p>
+ RTCPeerConnection and fires negotiationneeded.</p>
<p>When the other peer stops sending a stream in this manner, a
<code title="event-MediaStream-removestream"><a href=
@@ -1528,7 +1564,7 @@
</li>
<li>
- <p>Fire a renegotiationneeded event.</p>
+ <p>Fire a negotiationneeded event.</p>
</li>
</ol>
</dd>
@@ -1567,16 +1603,13 @@
</ol>
</dd>
- <dt>attribute EventHandler onrenegotationneeded</dt>
+ <dt>attribute EventHandler onnegotationneeded</dt>
<dd>
This event handler, of event handler event type <code><a href=
- "#event-renegotiation-needed">renegotiationneeded</a></code> , MUST
+ "#event-negotiation-needed">negotiationneeded</a></code> , MUST
be supported by all objects implementing the
<code><a>RTCPeerConnection</a></code> interface.
-
- <p class="issue">ISSUE: Need to sort out which things should be
- Function and which should be a Callback.</p>
</dd>
<dt>attribute EventHandler onicecandidate</dt>
@@ -1584,8 +1617,8 @@
<dd>This event handler, of event handler event type <code><a href=
"#event-onicecandidate">onicecandidate</a></code> , MUST be supported
by all objects implementing the <code><a>RTCPeerConnection</a></code>
- interface. It is called any time there is a new ICE candiate can be
- added to the a previos offer or answer.</dd>
+ interface. It is called any time there is a new ICE candidate
+ added to a previous offer or answer.</dd>
<dt>attribute EventHandler onopen</dt>
@@ -1605,30 +1638,31 @@
<dd>
This event handler, of event handler event type <code><a href=
- "#event-mediastream-addstream">addstream</a></code> , MUST be
- supported by all objects implementing the
- <code><a>RTCPeerConnection</a></code> interface.
-
- <p class="issue">ISSUE: It seems like this even handler needs to be
- fired when the first of two things happens - the remote side sends
- signaling indicating a media will be sent, or the side that sent an
- offer start receiving media in reply to that offer.</p>
+ "#event-mediastream-addstream">addstream</a></code>, MUST be
+ fired by all objects implementing the
+ <code><a>RTCPeerConnection</a></code> interface It is called any
+ time a MediaStream is added by the remote peer.
</dd>
<dt>attribute EventHandler onremovestream</dt>
- <dd>This event handler, of event handler event type <code><a href=
- "#event-mediastream-removestream">removestream</a></code> , MUST be
- supported by all objects implementing the
- <code><a>RTCPeerConnection</a></code> interface.</dd>
+ <dd>
+ This event handler, of event handler event type <code><a href=
+ "#event-mediastream-removestream">removestream</a></code>, MUST be
+ fired by all objects implementing the
+ <code><a>RTCPeerConnection</a></code> interface. It is called any
+ time a MediaStream is removed by the remote peer.
+ </dd>
<dt>attribute EventHandler onicechange</dt>
- <dd>This event handler, of event handler event type <code><a href=
- "#event-mediastream-icechange">icechange</a></code> , MUST be
- supported by all objects implementing the
- <code><a>RTCPeerConnection</a></code> interface. It is called any
- time the iceState changes.</dd>
+ <dd>
+ This event handler, of event handler event type <code><a href=
+ "#event-mediastream-icechange">icechange</a></code>, MUST be
+ fired by all objects implementing the
+ <code><a>RTCPeerConnection</a></code> interface. It is called any
+ time the <var>iceState</var> changes.
+ </dd>
</dl>
</section>
@@ -1669,7 +1703,7 @@
<p>In some cases, a RTCPeerConnection may wish to receive video but
it is not going to send any video. The RTCPeerConnection needs to
know if it should signal to the remote side if it wishes to receive
- video or not. This constraints allows an application to indicate its
+ video or not. This constraint allows an application to indicate its
preferences for receiving video when creating an offer.</p>
</dd>
@@ -1693,7 +1727,7 @@
"false". The default is a non mandatory "true".</p>
<p>Many codecs and system are capable of detecting "silence" and
- changing there behavior in this case by doing things such as not
+ changing their behavior in this case by doing things such as not
transmitting any media. In many cases, such as when dealing with
sounds other than spoken voice or emergency calling, it is desirable
to be able to turn off this behavior. This constraints allows the
@@ -1707,13 +1741,13 @@
<p>This is a enum type constraint that can take the values "none",
"relay", and "all". The default is a non mandatory "all".</p>
- <p>This constraints indicates which candidates the ICE engine is
- restricted use. The value "none" means the ICE engine MUST not send
- or receive any packets at this point. The value "relay" indicates the
- ICE engine MUST only using media relay candidates such as candidates
- passing through a TURN server. This can be used to reduce leakage of
- IP addresses in certain use cases. The value of "all" indicates all
- values can be used.</p>
+ <p>This constraint indicates which candidates the ICE engine is
+ allowed to use. The value "none" means the ICE engine MUST not
+ send or receive any packets at this point. The value "relay" indicates
+ the ICE engine MUST only use media relay candidates such as
+ candidates passing through a TURN server. This can be used to reduce
+ leakage of IP addresses in certain use cases. The value of "all"
+ indicates all values can be used.</p>
</dd>
</dl>
@@ -1744,8 +1778,6 @@
mechanism they used to establish that they were going to communicate in
the first place.</p>
- <p>NOTE: TODO - This code does not match the API yet and might have a few
- other problems.</p>
<pre class="example sh_javascript">
var signalingChannel = createSignalingChannel();
var pc;
@@ -1792,8 +1824,8 @@
else
pc.addIceCandidate(new RTCIceCandidate(signal.candidate));
};
-
-</pre>
+
+ </pre>
</div>
</section>
@@ -1803,51 +1835,46 @@
<div>
<p>This example shows the more comples functionality.</p>
<pre class="example sh_javascript">
- TODO
-</pre>
+TODO
+ </pre>
</div>
</section>
+ <section>
+ <h3>Call Flow Browser to Browser</h3>
- <section>
- <h3>Call Flow Browser to Browser </h3>
-
<p class="note">Editor Note: This example flow needs to be discussed on the
list and is likely wrong in many ways.</p>
-
+
<p>This shows an example of one possible call flow between two
browsers. This does not show every callback that gets fired but instead
tries to reduce it down to only show the key events and messages. </p>
-
+
<p><img alt="A MediaStream" src="images/ladder-2party-simple.svg" width=
"100%"></p>
-
+
<p> The following flow show a more complete set of the callbacks and events
that happen. </p>
-
+
<p><img alt="A MediaStream" src="images/ladder-2party-full.svg" width=
"100%"></p>
</section>
-
<section>
<h3>Call Flow Browser to MCU </h3>
-
+
<p class="note">Editor Note: This example flow needs to be discussed on the
list and is likely wrong in many ways.</p>
-
+
<p>This shows an example of one possible call flow between a centralized
conferencing server and a browsers. This does not show every callback that
gets fired but instead tries to reduce it down to only show the key events
and messages. </p>
-
+
<p><img alt="A MediaStream" src="images/ladder-mcu-simple.svg" width=
"100%"></p>
-
- </section>
+ </section>
-
-
<section>
<h2>Peer-to-peer Data API</h2>
@@ -1883,13 +1910,6 @@
transport properties of a offered data channel. The actual wire protocol
between the peers is out of the scope for this specification.</p>
- <p class="issue">ISSUE: this needs to explain how the configuration state
- is passed between the peers.</p>
-
- <p class="issue">ISSUE: this type of design where one side can pick
- anything and the other side much support everything has proven to make
- future upgrades very difficult.</p>
-
<p>A <code><a>DataChannel</a></code> created with <code><a href=
"#dom-peerconnection-createdatachannel">createDataChannel()</a></code>
MUST initially be in the <code><a href=
@@ -2247,14 +2267,14 @@
chan.onmessage = function (evt) {
// use evt.data };
chan.send("hello");
-</pre>
+}
+ </pre>
</div>
<div>
<p>This simple example shows how to register an event listener to
handle the case when a remote peer creates a new DataChannel.</p>
<pre class="example sh_javascript">
-
peerConn.ondatachannel = function (evt) {
var chan = evt.channel;
chan.onmessage = function (evt) {
@@ -2264,8 +2284,10 @@
// remote side closed the data channel
};
};
-</pre>
- </div><!--div>
+ </pre>
+ </div>
+
+ <!--div>
<p>This simple example shows how configure two DataChannel objects for different purposes.</p>
<pre class='example sh_javascript'>
// the chat channel is reliable and not as prioritized as game data
@@ -2273,7 +2295,7 @@
// the game data channel is prioritized and unreliable low latency channel for high performance
var gameDataChan = peerConn.createDataChannel("data", { "reliable": false, "priority": 10 });
- </pre>
+ </pre>
</div-->
</section>
</section>
@@ -2311,7 +2333,7 @@
which does not bubble (except where otherwise stated) and is not
cancelable (except where otherwise stated), and which uses the
<code>RTCPeerConnectionIceEvent</code> interface with the
- <code>candidate</code> attribute set to the new ICE candiate MUST be
+ <code>candidate</code> attribute set to the new ICE candidate MUST be
created and dispatched at the given target.</p>
<dl class="idl" data-merge="RTCPeerConnectionIceEventInit" title=
@@ -2320,7 +2342,7 @@
<dd>
<p>The <code>candidate</code> attribute is the
- <code><a>RTCIceCandidate</a></code> object with the new ICE candiate
+ <code><a>RTCIceCandidate</a></code> object with the new ICE candidate
that caused the event.</p>
</dd>
</dl>
@@ -2595,16 +2617,13 @@
<tr>
<td><dfn id=
- "event-renegotiation"><code>renegotiationneeded</code></dfn></td>
+ "event-negotiation"><code>negotiationneeded</code></dfn></td>
<td><code><a>Event</a></code></td>
<td>
The browser wishes to inform the application that session
- negotiation needs to be redone at some point in the near future.
-
- <p class="issue">ISSUE: should this be moved to "Negotiation
- Needed" instead of "Re-Negotiation Needed"?</p>
+ negotiation needs to be done at some point in the near future.
</td>
</tr>
@@ -2637,11 +2656,28 @@
</section>
<section>
+ <h2>Security Considerations</h2>
+ <p>TBD.</p>
+ </section>
+
+ <section>
<h2>Change Log</h2>
<p>This section will be removed before publication.</p>
-
+
<!-- Why do the first two headings automatically convert to <h2>? -->
+ <h3>Changes since Aug 13, 2012</h3>
+
+ <ol>
+ <li>Made the RTCSessionDescription and RTCIceCandidate constructors take
+ dictionaries instead of a strings. Also added detailed stringifier
+ algorithm.</li>
+
+ <li>Went through the list of issues (issue numbers are only valid with
+ HEAD at fcda53c460). Closed (fixed/wontfix): 1, 8, 10, 13, 14, 16, 18, 19,
+ 22, 23, 24. Converted to notes: 4, 12. Updated: 9.</li>
+ </ol>
+
<h3>Changes since Jul 20, 2012</h3>
<ol>
@@ -2787,7 +2823,6 @@
<li>Moved (and extended) the explanation about track references and media
sources from LocalMediaStream to MediaStreamTrack.</li>
-
</ol>
</section>
--- NEW FILE: webrtc-20120816.html ---
<!DOCTYPE html>
<html lang="en">
<head>
<title>WebRTC 1.0: Real-time Communication Between Browsers</title>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<!--
After making changes to this document in the github repo, run:
./publish.sh webrtc.html
to publish a new editor's draft to the W3C CVS. This assumes your
CVS checkout is located at ../2011/webrtc, you can specify the location
as the second argument, for example:
./publish.sh webrtc.html ~/path/to/w3/2011/webrtc
-->
<script class="remove" src="http://www.w3.org/Tools/respec/respec-w3c-common"
type="text/javascript">
// keep this comment
</script>
[...2797 lines suppressed...]
<li>Updated the LocalMediaStream.stop() algorithm to implicitly use the
end track algorithm.</li>
<li>Replaced an occurrence the term finished track with ended track (to
align with rest of spec).</li>
<li>Moved (and extended) the explanation about track references and media
sources from LocalMediaStream to MediaStreamTrack.</li>
</ol>
</section>
<section class="appendix">
<h2>Acknowledgements</h2>
<p>The editors wish to thank the Working Group chairs, Harald Alvestrand
and Stefan Håkansson, for their support.</p>
</section>
</body>
</html>
Index: webrtc.js
===================================================================
RCS file: /sources/public/2011/webrtc/editor/webrtc.js,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- webrtc.js 13 Aug 2012 19:14:21 -0000 1.2
+++ webrtc.js 16 Aug 2012 17:18:58 -0000 1.3
@@ -24,7 +24,7 @@
// if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
// and its maturity status
previousMaturity: "ED",
- previousURI: "http://dev.w3.org/2011/webrtc/editor/webrtc-20120720.html",
+ previousURI: "http://dev.w3.org/2011/webrtc/editor/webrtc-20120813.html",
// if there a publicly available Editor's Draft, this is the link
edDraftURI: "http://dev.w3.org/2011/webrtc/editor/webrtc.html",
Received on Thursday, 16 August 2012 17:19:03 UTC