Merge pull request #302 from martinthomson/sd_ic_dict

Removing interface use for RTCSessionDescription and RTCIceCandidate

Author: alvestrand

webrtc.html

@@ -611,7 +611,7 @@ <h4>Operation</h4>
 
                 <p>Add the candidate to <var>connection</var>'s
                 <code><a>localDescription</a></code> and create a
-                <code><a>RTCIceCandidate</a></code> object to represent the
+                <code><a>RTCIceCandidate</a></code> instance to represent the
                 candidate. Let <var>newCandidate</var> be that object.</p>
               </li>
 
@@ -789,13 +789,13 @@ <h3>Interface Definition</h3>
           </dd>
 
           <dt>Promise&lt;void&gt; setLocalDescription (
-            RTCSessionDescription description)</dt>
+            RTCSessionDescriptionInit description)</dt>
 
           <dd>
             <p>The <dfn id=
             "dom-peerconnection-setlocaldescription"><code>setLocalDescription()</code></dfn>
             method instructs the <code><a>RTCPeerConnection</a></code> to apply
-            the supplied <code><a>RTCSessionDescription</a></code> as the local
+            the supplied <code><a>RTCSessionDescriptionInit</a></code> as the local
             description.</p>
 
             <p>This API changes the local media state. In order to successfully
@@ -814,7 +814,7 @@ <h3>Interface Definition</h3>
 
             <p>The following list describes the <dfn id=
             "set-description-model">processing model</dfn> for setting a new
-            <code><a>RTCSessionDescription</a></code>.</p>
+            <code><a>RTCSessionDescriptionInit</a></code>.</p>
 
             <ul>
               <li>
@@ -846,7 +846,7 @@ <h3>Interface Definition</h3>
 
                   <li>
                     <p>The user agent MUST start the process to apply the
-                    <code><a>RTCSessionDescription</a></code> argument.</p>
+                    <code><a>RTCSessionDescriptionInit</a></code> argument.</p>
                   </li>
 
                   <li>
@@ -857,7 +857,7 @@ <h3>Interface Definition</h3>
 
               <li>
                 <p>If the process to apply the
-                <code><a>RTCSessionDescription</a></code> argument fails for
+                <code><a>RTCSessionDescriptionInit</a></code> argument fails for
                 any reason, then user agent MUST queue a task runs the
                 following steps:</p>
 
@@ -880,9 +880,9 @@ <h3>Interface Definition</h3>
                     <ul>
                       <li>
                         <p>The content of the
-                        <code><a>RTCSessionDescription</a></code> argument is
+                        <code><a>RTCSessionDescriptionInit</a></code> argument is
                         invalid or the <code><a href=
-                        "#widl-RTCSessionDescription-type">type</a></code> is
+                        "#widl-RTCSessionDescriptionInit-type">type</a></code> is
                         wrong for the current <a href=
                         "#dom-peerconnection-signaling-state">signaling
                         state</a> of <var>connection</var>.</p>
@@ -892,7 +892,7 @@ <h3>Interface Definition</h3>
                       </li>
 
                       <li>
-                        <p>The <code><a>RTCSessionDescription</a></code> is a
+                        <p>The <code><a>RTCSessionDescriptionInit</a></code> is a
                         valid description but cannot be applied at the media
                         layer.</p>
 
@@ -923,7 +923,7 @@ <h3>Interface Definition</h3>
               </li>
 
               <li>
-                <p>If the <code><a>RTCSessionDescription</a></code> argument is
+                <p>If the <code><a>RTCSessionDescriptionInit</a></code> argument is
                 applied successfully, then user agent MUST queue a task (<dfn
                 id="setlocal-resolve">setLocalDescription() resolve task</dfn>)
                 that runs the following steps:</p>
@@ -965,15 +965,15 @@ <h3>Interface Definition</h3>
 
                     <!-- A transition stable to haveLocalOffer --> <li> <p>If
                     the local description was set, and the
-                    <code><a>RTCSessionDescription</a></code> argument has a
+                    <code><a>RTCSessionDescriptionInit</a></code> argument has a
                     type of "offer", and it has a version that is later than the
                     currentLocalDescription, then the pendingLocalDescription will be set to
                     the argument and the state will transition to
                     have-local-offer.  </p> </li>
 
                     <!-- C transition haveRemoteOffer or haveLocalProvAnswer to
                     stable --> <li><p>If the local description was set, and the
-                    <code><a>RTCSessionDescription</a></code> argument has a
+                    <code><a>RTCSessionDescriptionInit</a></code> argument has a
                     type of "answer", then this completes an offer answer
                     negotiation and currentLocalDescription is set to the argument,
                     currentRemoteDescription is set to the value of pendingRemoteDescription,
@@ -982,15 +982,15 @@ <h3>Interface Definition</h3>
 
                     <!-- D transition stable to haveRemoteOffer --> <li> <p>If
                     the remote description was set, and the
-                    <code><a>RTCSessionDescription</a></code> argument has a
+                    <code><a>RTCSessionDescriptionInit</a></code> argument has a
                     type of "offer", and it has a version that is later than the
                     currentRemoteDescription, then the pendingRemoteDescription will be set to
                     the argument and the state will transition to
                     have-remote-offer.  </p> </li>
 
                     <!-- F transition haveRemoteOffer or haveLocalProvAnswer to
                     stable --> <li><p>If the remote description was set, and the
-                    <code><a>RTCSessionDescription</a></code> argument has a
+                    <code><a>RTCSessionDescriptionInit</a></code> argument has a
                     type of "answer", then this completes an offer answer
                     negotiation and currentRemoteDescription is set to the argument,
                     currentLocalDescription is set to the value of pendingLocalDescription,
@@ -999,21 +999,21 @@ <h3>Interface Definition</h3>
 
                     <!-- B transition rollback to haveLocalOffer to stable -->
                     <li> <p>If the local description was set, and the
-                    <code><a>RTCSessionDescription</a></code> argument has a
+                    <code><a>RTCSessionDescriptionInit</a></code> argument has a
                     type of "rollback", then this is a rollback and the
                     pendingLocalDescription is set to null and the state will
                     transition to stable.  </p> </li>
 
                     <!-- E transition rollback to haveRemoteOffer to stable -->
                     <li> <p>If the remote description was set, and the
-                    <code><a>RTCSessionDescription</a></code> argument has a
+                    <code><a>RTCSessionDescriptionInit</a></code> argument has a
                     type of "rollback", then this is a rollback and the
                     pendingRemoteDescription is set to null and the state will
                     transition to stable.  </p> </li>
 
                     <!-- G transition haveRemoteOffer to haveLocalProvAnswer -->
                     <li><p>If the local description was set, and the
-                    <code><a>RTCSessionDescription</a></code> argument has a
+                    <code><a>RTCSessionDescriptionInit</a></code> argument has a
                     type of "pranswer", then pendingLocalDescription will be set to the
                     argument and the state will transitions to
                     have-local-pranswer unless the state was stable,
@@ -1022,7 +1022,7 @@ <h3>Interface Definition</h3>
 
                      <!-- H transition haveRemoteOffer to haveLocalProvAnswer
                     --> <li><p>If the remote description was set, and the
-                    <code><a>RTCSessionDescription</a></code> argument has a
+                    <code><a>RTCSessionDescriptionInit</a></code> argument has a
                     type of "pranswer", then pendingRemoteDescription will be set to
                     the argument and the state will transitions to
                     have-remote-pranswer unless the state was stable,
@@ -1135,13 +1135,13 @@ <h3>Interface Definition</h3>
 
 
           <dt>Promise&lt;void&gt; setRemoteDescription (
-            RTCSessionDescription description)</dt>
+            RTCSessionDescriptionInit description)</dt>
 
           <dd>
             <p>The <dfn id=
             "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
+            the supplied <code><a>RTCSessionDescriptionInit</a></code> as the
             remote offer or answer. This API changes the local media state.</p>
 
             <p>When the method is invoked, the user agent MUST follow the <a
@@ -1150,7 +1150,7 @@ <h3>Interface Definition</h3>
             In addition, a remote description is processed to determine and
             verify the identity of the peer.</p>
 
-            <p>If the <code><a>RTCSessionDescription</a></code> argument is
+            <p>If the <code><a>RTCSessionDescriptionInit</a></code> argument is
             applied successfully, the user agent MUST <a href=
             "#dispatch-receiver">dispatch a receiver</a> for all new
             media descriptions [[!RTCWEB-JSEP]] before queuing the <a href=
@@ -1633,7 +1633,7 @@ <h3>Legacy Interface Extensions</h3>
             argument.</p>
           </dd>
 
-          <dt>void setLocalDescription (RTCSessionDescription description,
+          <dt>void setLocalDescription (RTCSessionDescriptionInit description,
           VoidFunction successCallback, RTCPeerConnectionErrorCallback
           failureCallback)</dt>
 
@@ -1704,7 +1704,7 @@ <h3>Legacy Interface Extensions</h3>
             argument.</p>
           </dd>
 
-          <dt>void setRemoteDescription (RTCSessionDescription description,
+          <dt>void setRemoteDescription (RTCSessionDescriptionInit description,
           VoidFunction successCallback, RTCPeerConnectionErrorCallback
           failureCallback)</dt>
 
@@ -2125,7 +2125,7 @@ <h4>RTCSdpError</h4>
         <dl class="idl" title="interface RTCSdpError : DOMError">
           <dt>readonly attribute long sdpLineNumber</dt>
 
-          <dd>The line number of an <code><a>RTCSessionDescription</a></code>
+          <dd>The line number of an <code><a>RTCSessionDescriptionInit</a></code>
           at which the error was encountered.</dd>
         </dl>
 
@@ -2137,13 +2137,13 @@ <h4>RTCSdpError</h4>
 
           <ul>
             <li>InvalidSessionDescriptionError: The provided
-            RTCSessionDescription contained invalid SDP, or the type was wrong
+            RTCSessionDescriptionInit contained invalid SDP, or the type was wrong
             for the current state of the RTCPeerConnection. User agents SHOULD
             provide as much additional information in the error message as
             possible, including the sdpLineNumber, if appropriate.</li>
 
             <li>IncompatibleSessionDescriptionError: The provided
-            RTCSessionDescription contained SDP that could not be correctly
+            RTCSessionDescriptionInit contained SDP that could not be correctly
             applied to the RTCPeerConnection due to its current state. User
             agents SHOULD provide as much additional information in the error
             message as possible, including the sdpLineNumber, if
@@ -2168,6 +2168,7 @@ <h3>Session Description Model</h3>
         <h4>RTCSdpType</h4>
 
         <p>The RTCSdpType enum describes the type of an
+        <code><a>RTCSessionDescriptionInit</a></code> or
         <code><a>RTCSessionDescription</a></code> instance.</p>
 
         <dl class="idl" title="enum RTCSdpType">
@@ -2215,6 +2216,11 @@ <h4>RTCSdpType</h4>
       <section>
         <h4>RTCSessionDescription Class</h4>
 
+        <p>The <code>RTCSessionDescription</code> class is used by
+        <code><a>RTCPeerConnection</a></code> to expose local and remote session
+        descriptions.  Attributes on this interface are mutable for legacy
+        reasons.</p>
+
         <dl class="idl" data-merge="RTCSessionDescriptionInit" title=
         "interface RTCSessionDescription">
           <dt>Constructor (RTCSessionDescriptionInit descriptionInitDict)</dt>
@@ -2223,9 +2229,9 @@ <h4>RTCSessionDescription Class</h4>
           "dom-sessiondescription"><code>RTCSessionDescription()</code></dfn>
           constructor takes a dictionary argument,
           <var>descriptionInitDict</var>, whose content is used to initialize
-          the new <code><a>RTCSessionDescription</a></code> object.  This class
-          is a future extensible carrier for the data contained in it and does
-          not perform any substantive processing.</dd>
+          the new <code><a>RTCSessionDescription</a></code> object.  This
+          constructor is deprecated; it exists for legacy compatibility reasons
+          only.</dd>
 
           <dt>attribute RTCSdpType type</dt>
 
@@ -2314,47 +2320,31 @@ <h3>Interfaces for Connectivity Establishment</h3>
       <section>
         <h4>RTCIceCandidate Type</h4>
 
-        <p>This class is a future extensible carrier for the data contained in
-        it and does not perform any substantive processing.</p>
-
-        <dl class="idl" data-merge="RTCIceCandidateInit" title=
-        "interface RTCIceCandidate">
-          <dt>Constructor (RTCIceCandidateInit candidateInitDict)</dt>
-
-          <dd>The <dfn id=
-          "dom-icecandidate"><code>RTCIceCandidate()</code></dfn> constructor
-          takes a dictionary argument, <var>candidateInitDict</var>,
-          whose content is used to initialize the new
-          <code><a>RTCIceCandidate</a></code> object. When constructed, values
-          for <var>candidate</var> and either <var>sdpMid</var>
-          or <var>sdpMLineIndex</var> MUST be provided.</dd>
+        <p>This describes an ICE candidate. Though not explicitly required,
+        values for <var>candidate</var> and either <var>sdpMid</var>
+        or <var>sdpMLineIndex</var> MUST be provided.</p>
 
-          <dt>attribute DOMString candidate</dt>
+        <dl class="idl" title="[Constructor(RTCIceCandidate copy)] dictionary RTCIceCandidate">
+          <dt>required DOMString candidate</dt>
 
           <dd>This carries the <code>candidate-attribute</code> as defined in
           section 15.1 of [[!ICE]].</dd>
 
-          <dt>attribute DOMString? sdpMid</dt>
+          <dt>DOMString sdpMid</dt>
 
           <dd>If present, this contains the identifier of the "media stream
           identification" as defined in [[!RFC3388]] for the media section this
           candidate is associated with.</dd>
 
-          <dt>attribute unsigned short? sdpMLineIndex</dt>
+          <dt>unsigned short sdpMLineIndex</dt>
 
           <dd>This indicates the index (starting at zero) of the m-line in the
           SDP this candidate is associated with.</dd>
-
-          <dt>serializer = { attribute}</dt>
-        </dl>
-
-        <dl class="idl" title="dictionary RTCIceCandidateInit">
-          <dt>required DOMString candidate</dt>
-
-          <dt>DOMString sdpMid</dt>
-
-          <dt>unsigned short sdpMLineIndex</dt>
         </dl>
+        <div class="note">
+          <p>The constructor on <code><a>RTCIceCandidate</a></code> exists
+          for legacy compatibility reasons only.</p>
+        </div>
       </section>
 
       <section>
@@ -6291,7 +6281,7 @@ <h3>Simple Peer-to-peer Example</h3>
         })
         .then(function () {
             // send the offer to the other peer
-            signalingChannel.send(JSON.stringify({ "sdp": pc.localDescription }));
+            signalingChannel.send(JSON.stringify({ "desc": pc.localDescription }));
         })
         .catch(logError);
     };
@@ -6317,8 +6307,8 @@ <h3>Simple Peer-to-peer Example</h3>
         start();
 
     var message = JSON.parse(evt.data);
-    if (message.sdp) {
-        var desc = new RTCSessionDescription(message.sdp);
+    if (message.desc) {
+        var desc = message.desc;
 
         // if we get an offer, we need to reply with an answer
         if (desc.type == "offer") {
@@ -6329,13 +6319,13 @@ <h3>Simple Peer-to-peer Example</h3>
                 return pc.setLocalDescription(answer);
             })
             .then(function () {
-                signalingChannel.send(JSON.stringify({ "sdp": pc.localDescription }));
+                signalingChannel.send(JSON.stringify({ "desc": pc.localDescription }));
             })
             .catch(logError);
         } else
             pc.setRemoteDescription(desc).catch(logError);
     } else
-        pc.addIceCandidate(new RTCIceCandidate(message.candidate)).catch(logError);
+        pc.addIceCandidate(message.candidate).catch(logError);
 };
 
 function logError(error) {
@@ -6392,7 +6382,7 @@ <h3>Peer-to-peer Data Example</h3>
         })
         .then(function () {
             // send the offer to the other peer
-            signalingChannel.send(JSON.stringify({ "sdp": pc.localDescription }));
+            signalingChannel.send(JSON.stringify({ "desc": pc.localDescription }));
         })
         .catch(logError);
     };
@@ -6415,8 +6405,8 @@ <h3>Peer-to-peer Data Example</h3>
         start(false);
 
     var message = JSON.parse(evt.data);
-    if (message.sdp) {
-        var desc = new RTCSessionDescription(message.sdp);
+    if (message.desc) {
+        var desc = message.desc;
 
         // if we get an offer, we need to reply with an answer
         if (desc.type == "offer") {
@@ -6427,13 +6417,13 @@ <h3>Peer-to-peer Data Example</h3>
                 return pc.setLocalDescription(answer);
             })
             .then(function () {
-                signalingChannel.send(JSON.stringify({ "sdp": pc.localDescription }));
+                signalingChannel.send(JSON.stringify({ "desc": pc.localDescription }));
             })
             .catch(logError);
         } else
             pc.setRemoteDescription(desc).catch(logError);
     } else
-        pc.addIceCandidate(new RTCIceCandidate(message.candidate)).catch(logError);
+        pc.addIceCandidate(message.candidate).catch(logError);
 };
 
 function setupChat() {