update to latest tube spec

3 files changed, 27 insertions, 54 deletions

diff --git a/extensions/Channel_Interface_Tube.xml b/extensions/Channel_Interface_Tube.xml
index bea58d44..8e1ffab3 100644
--- a/extensions/Channel_Interface_Tube.xml
+++ b/extensions/Channel_Interface_Tube.xml
@@ -40,21 +40,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       simultaneously).</p>
     </tp:docstring>
 
-    <property name="Initiator" type="u" tp:type="Contact_Handle" access="read"
-              tp:name-for-bindings="Initiator">
-      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>Initiator handle.</p>
-        <p>When requesting a channel with 
-          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
-          this property MUST NOT be included in the request.</p>
-      </tp:docstring>
-    </property>
-
     <property name="Parameters" type="a{sv}" tp:type="String_Variant_Map"
               access="readwrite" tp:name-for-bindings="Parameters">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>Each tube has a dictionary of arbitrary parameters. Parameters are
-          commonly used for bootstrap information. The allowable keys,
+          commonly used to bootstrap legacy protocols where you can't
+          negotiate parameters in-band. The allowable keys,
           types and values are defined by the service. Connection managers
           must support the value being a string (D-Bus type 's'), array of bytes
           (D-Bus type 'ay'), unsigned integer (D-Bus type 'u'), integer (D-Bus
@@ -62,15 +53,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         <p>When the tube is offered, the parameters are transmitted with the
           offer and appear as a property of the incoming tube for other
           participants.</p>
-        <p>Example of valid parameters:
-          <code>{'game name': 'go', 'board size': 19}</code></p>
+        <p>Example of valid parameters for 'smb' Server Message Block over
+          TCP/IP (from <a href="http://www.dns-sd.org/ServiceTypes.html">DNS
+          SRV (RFC 2782) Service Types
+          http://www.dns-sd.org/ServiceTypes.html</a>):
+          <code>{'u': 'username', 'p': 'password', 'path': 'path'}</code></p>
         <p>When requesting a channel with 
           <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
           this property MAY be included in the request. If it is not included in
           the request, the connection manager MUST consider the property to be
           empty. This property MAY be changed after the channel creation when
           the tube is in the state Not_Offered. If the tube is in another
-          state, changing this property MUST fail without side effect.</p>
+          state, changing this property MUST fail without side effects.</p>
       </tp:docstring>
     </property>
 
diff --git a/extensions/Channel_Type_DBus_Tube.xml b/extensions/Channel_Type_DBus_Tube.xml
index 3846afbe..a3b98d7e 100644
--- a/extensions/Channel_Type_DBus_Tube.xml
+++ b/extensions/Channel_Type_DBus_Tube.xml
@@ -42,8 +42,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         private messages, or can send broadcast messages which are
         received by everyone in the tube (including themselves).
         Each participant has a D-Bus unique name; connection managers
-        must prevent participants from sending messages with the wrong
-        sender unique name, and should attempt to avoid participants
+        MUST prevent participants from sending messages with the wrong
+        sender unique name, and SHOULD attempt to avoid participants
         receiving messages not intended for them.</p>
 
       <p>In a 1-1 context (Handle_Type_Contact) the tube behaves like
@@ -84,7 +84,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       <arg direction="out" name="address" type="s">
         <tp:docstring>
           The string describing the address of the private bus. The client
-          should not attempt to connect to the address until the tube is open.
+          SHOULD not attempt to connect to the address until the tube is open.
         </tp:docstring>
       </arg>
       <tp:possible-errors>
@@ -167,7 +167,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
               tp:name-for-bindings="Service_Name">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>A string representing the service name that will be used over the
-          tube. It should be a well-known D-Bus service name, of the form
+          tube. It SHOULD be a well-known D-Bus service name, of the form
           com.example.ServiceName.</p>
         <p>When the tube is offered, the service name is transmitted to the
           other end.</p>
diff --git a/extensions/Channel_Type_Stream_Tube.xml b/extensions/Channel_Type_Stream_Tube.xml
index f34f441b..4a43a007 100644
--- a/extensions/Channel_Type_Stream_Tube.xml
+++ b/extensions/Channel_Type_Stream_Tube.xml
@@ -25,11 +25,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       <p>A stream tube is a transport for ordered, reliable data transfer,
         similar to SOCK_STREAM sockets.</p>
 
-      <p>When accepting a stream tube, a new listening local socket is
-        created. Each time the client connects to this socket, the
-        connection manager of the initiator of the tube opens a new
-        connection to its local socket. Both sides can then use this pair
-        of sockets to communicate together.</p>
+      <p>When offering a stream tube, the initiating client creates a local
+        listening socket and offers it to the recipient client using the
+        <tp:member-ref>OfferStreamTube</tp:member-ref> method.  When a
+        recipient accepts a stream tube using the
+        <tp:member-ref>AcceptStreamTube</tp:member-ref> method, the
+        recipient's connection manager creates a new local listening socket.
+        Each time the recipient's client connects to this socket, the
+        initiator's connection manager proxies this connection to the
+        originally offered socket.</p>
 
     </tp:docstring>
 
@@ -72,8 +76,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         </tp:error>
         <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
           <tp:docstring>
-            The connection manager doesn't support stream tubes, or
-            does not support the given address type or access-control type.
+            The connection manager doesn't support the given address type
+            or access-control type.
           </tp:docstring>
         </tp:error>
       </tp:possible-errors>
@@ -114,8 +118,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
           <tp:docstring>
-            The given tube ID is invalid or does not refer to a stream
-            tube.
+            The access_control_param is invalid with the given access_control.
           </tp:docstring>
         </tp:error>
         <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
@@ -126,33 +129,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       </tp:possible-errors>
     </method>
 
-    <method name="GetStreamTubeSocketAddress"
-            tp:name-for-bindings="Get_Stream_Tube_Socket_Address">
-      <tp:docstring>
-        For a stream tube, obtain the address of the socket used to
-        communicate over this tube.
-      </tp:docstring>
-      <arg direction="out" name="address_type" type="u" tp:type="Socket_Address_Type">
-        <tp:docstring>
-          The type of the listening address of the socket, as a member of
-          Socket_Address_Type.
-        </tp:docstring>
-      </arg>
-      <arg direction="out" name="address" type="v">
-        <tp:docstring>
-          The listening address of the socket, as indicated by the
-          address_type.
-        </tp:docstring>
-      </arg>
-      <tp:possible-errors>
-        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
-          <tp:docstring>
-            This tube is not in the "open" state.
-          </tp:docstring>
-        </tp:error>
-      </tp:possible-errors>
-    </method>
-
     <signal name="StreamTubeNewConnection"
             tp:name-for-bindings="Stream_Tube_New_Connection">
       <tp:docstring>
@@ -206,6 +182,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
           }
         </pre>
 
+        <p>Connection Managers MUST support at least IPv4 with the localhost
+          access control.</p>
+
         <p>When requesting a channel with 
           <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
           this property MUST NOT be included in the request.</p>