[Telepathy-commits] [telepathy-spec/master] Clarify the direction of new streams to be (Receive, Pending_Local_Send) until or unless changed by a StreamDirectionChanged signal

[Simon McVittie]

This may require existing connection managers to emit an extra signal for
spec compliance, but shouldn't break existing clients.
---
 spec/Channel_Type_Streamed_Media.xml |   52 +++++++++++++++++++++++++++++++--
 1 files changed, 48 insertions(+), 4 deletions(-)

diff --git a/spec/Channel_Type_Streamed_Media.xml b/spec/Channel_Type_Streamed_Media.xml
index 90b8b2c..c7bb826 100644
--- a/spec/Channel_Type_Streamed_Media.xml
+++ b/spec/Channel_Type_Streamed_Media.xml
@@ -279,10 +279,54 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           The stream type (a value from MediaStreamType)
         </tp:docstring>
       </arg>
-      <tp:docstring>
-        Emitted when a new stream has been added to this channel.
-        Clients SHOULD assume that the stream's
-        <tp:type>Media_Stream_State</tp:type> is initially Disconnected.
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Emitted when a new stream has been added to this channel.
+          Clients SHOULD assume that the stream's
+          <tp:type>Media_Stream_State</tp:type> is initially Disconnected.</p>
+
+        <p>If a connection manager needs to represent the addition of a stream
+          whose state is already Connecting or Connected, it MUST do this
+          by emitting StreamAdded, closely followed by
+          <tp:member-ref>StreamStateChanged</tp:member-ref> indicating a
+          change to the appropriate state.</p>
+
+        <tp:rationale>
+          <p>Historically, it was not clear from the StreamAdded signal what
+            the state of the stream was. telepathy-spec 0.17.UNRELEASED
+            clarified this.</p>
+        </tp:rationale>
+
+        <p>Similarly, clients SHOULD assume that the initial
+          <tp:type>Media_Stream_Direction</tp:type> of a newly added stream
+          is Receive, and that the initial
+          <tp:type>Media_Stream_Pending_Send</tp:type> is
+          Pending_Local_Send.</p>
+
+        <p>If a connection manager needs to represent the addition of a stream
+          whose direction or pending-send differs from those initial values,
+          it MUST do so by emitting StreamAdded, closely followed by
+          <tp:member-ref>StreamDirectionChanged</tp:member-ref> indicating a
+          change to the appropriate direction and pending-send state.</p>
+
+        <tp:rationale>
+          <p>StreamAdded doesn't itself indicate the stream's direction; this
+            is unfortunate, but is preserved for compatibility.</p>
+
+          <p>This is the appropriate direction for streams added by a remote
+            contact on existing connection managers, and does not violate
+            user privacy by automatically sending audio or video (audio streams
+            start off muted, video streams start off not sending). For
+            streams added by the local user using the client receiving the
+            signal, the true direction can also be determined from the return
+            value of the <tp:member-ref>RequestStreams</tp:member-ref>
+            method.</p>
+
+          <p>Existing clients typically operate by maintaining a separate
+            idea of the directions that they would like the streams to have,
+            and enforcing these intended directions by calling
+            <tp:member-ref>RequestStreamDirection</tp:member-ref> whenever
+            needed.</p>
+        </tp:rationale>
       </tp:docstring>
     </signal>
 
-- 
1.5.6.5