revise spec to have (uv) for stream addresses, and other misc adjustments

20070718112530-c9803-49d17297331bc001c5e40fd5a91a70135a661219.gz

1 files changed, 85 insertions, 23 deletions

diff --git a/spec/Channel_Type_Tubes.xml b/spec/Channel_Type_Tubes.xml
index 78ad8a40..348a659a 100644
--- a/spec/Channel_Type_Tubes.xml
+++ b/spec/Channel_Type_Tubes.xml
@@ -21,8 +21,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
   <interface name="org.freedesktop.Telepathy.Channel.Type.Tubes" tp:name-const="CHANNEL_TYPE_TUBES">
     <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-      <p>A "tube" is a mechanism for arbitrary data transfer. Currently, one
-        kind of data transfer is specified, namely that of D-Bus messages.
+      <p>A "tube" is a mechanism for arbitrary data transfer. Two types of
+        data transfer are specified: D-Bus messages, and streams of bytes.
         Each tube has a service name, which is a string specifying the kind of
         communication that takes place over it, and a dictionary of arbitrary
         parameters. Tube parameters are commonly used for bootstrap
@@ -31,6 +31,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 
        <p>The Tubes channel type may be requested for handles of type
          HANDLE_TYPE_CONTACT and HANDLE_TYPE_ROOM.</p>
+
+       <p>Stream tubes specify listening addresses using structs (uv), where u
+         is a member of Tube_Stream_Address_Type, and the v is dependent on
+         the type of address.</p>
     </tp:docstring>
 
     <tp:enum name="Tube_Type">
@@ -53,10 +57,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         </tp:docstring>
       </tp:enumvalue>
 
-      <tp:enumvalue suffix="Stream_Unix" value="1">
+      <tp:enumvalue suffix="Stream" value="1">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-          <p>An ordered reliable transport, for transporting TCP traffic
-            through a Unix stream socket.</p>
+          <p>A transport for ordered, reliable data transfer, similar to
+            SOCK_STREAM sockets.</p>
 
           <p>For each Stream Unix tube offered, the connection manager exports
             a local Unix socket to the participants of the tube.
@@ -87,6 +91,29 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       </tp:enumvalue>
     </tp:enum>
 
+    <tp:enum name="Tube_Stream_Address_Type">
+      <tp:enumvalue suffix="Unix" value="0">
+        <tp:docstring>
+          A Unix socket. The address is a string containing the path of the
+          socket.
+        </tp:docstring>
+      </tp:enumvalue>
+
+      <tp:enumvalue suffix="Abstract_Unix" value="1">
+        <tp:docstring>
+          An abstract Unix socket. The address is a string containing the path
+          of the socket. There is no leading null byte.
+        </tp:docstring>
+      </tp:enumvalue>
+
+      <tp:enumvalue suffix="TCP" value="2">
+        <tp:docstring>
+          A TCP socket. The address has signature (su), containing the
+          hostname and the port number respectively.
+        </tp:docstring>
+      </tp:enumvalue>
+    </tp:enum>
+
     <method name="GetAvailableTubeTypes">
       <arg direction="out" type="au" tp:type="Tube_Type[]">
         <tp:docstring>
@@ -152,9 +179,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       </tp:possible-errors>
     </method>
 
-    <method name="OfferStreamUnixTube">
+    <method name="OfferStreamTube">
       <tp:docstring>
-        Offers a Stream Unix tube exporting the local socket specified.
+        Offer a stream tube exporting the local socket specified.
       </tp:docstring>
       <arg direction="in" name="service" type="s">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -165,14 +192,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
             http://www.dns-sd.org/ServiceTypes.html</a>.
         </tp:docstring>
       </arg>
-      <arg direction="in" name="socket" type="s">
+      <arg direction="in" name="parameters" type="a{sv}">
         <tp:docstring>
-          The path of the local Unix socket exported over the tube.
+          A dictionary of properties for the new tube.
         </tp:docstring>
       </arg>
-      <arg direction="in" name="parameters" type="a{sv}">
+      <arg direction="in" name="address" type="(uv)">
         <tp:docstring>
-          A dictionary of properties for the new tube.
+          The listening address of the local service.
         </tp:docstring>
       </arg>
       <arg direction="out" type="u">
@@ -184,13 +211,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
           <tp:docstring>
-            The contact associated with this channel doesn't have tubes
+            The contact associated with this channel doesn't have tube
             capabilities.
           </tp:docstring>
         </tp:error>
         <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
           <tp:docstring>
-            The connection manager doesn't support Stream Unix tubes.
+            The connection manager doesn't support stream tubes.
           </tp:docstring>
         </tp:error>
       </tp:possible-errors>
@@ -232,22 +259,57 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       </arg>
     </signal>
 
-    <method name="AcceptTube">
+    <method name="AcceptDBusTube">
       <tp:docstring>
-        Accept a tube that's in the "local pending" state. The connection
-        manager will attempt to open the tube. The tube remains in the
-        "local pending" state until the TubeStateChanged signal is emitted.
+        Accept a D-Bus tube that's in the "local pending" state. The
+        connection manager will attempt to open the tube. The tube remains in
+        the "local pending" state until the TubeStateChanged signal is
+        emitted.
       </tp:docstring>
       <arg direction="in" name="id" type="u">
         <tp:docstring>
           The ID of the tube to accept.
         </tp:docstring>
       </arg>
+      <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.
+        </tp:docstring>
+      </arg>
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument" />
       </tp:possible-errors>
     </method>
 
+    <method name="AcceptStreamTube">
+      <tp:docstring>
+        Accept a stream tube that's in the "local pending" state. The
+        connection manager will attempt to open the tube. The tube remains in
+        the "local pending" state until the TubeStateChanged signal is
+        emitted.
+      </tp:docstring>
+      <arg direction="in" name="id" type="u">
+        <tp:docstring>
+          The ID of the tube to accept.
+        </tp:docstring>
+      </arg>
+      <arg direction="in" name="address_type" type="u">
+        <tp:docstring>
+          The type of address the connection manager should listen on.
+        </tp:docstring>
+      </arg>
+      <arg direction="out" name="address" type="v">
+        <tp:docstring>
+          The address on which the connection manager will listen for
+          connections to this tube. The client should not attempt to connect
+          to the address until the tube is open.
+        </tp:docstring>
+      </arg>
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument" />
+      </tp:possible-errors>
+    </method>
     <signal name="TubeStateChanged">
       <tp:docstring>
         Emitted when the state of a tube changes.
@@ -290,7 +352,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       </arg>
     </signal>
 
-    <method name="GetDBusServerAddress">
+    <method name="GetDBusTubeAddress">
       <tp:docstring>
         For a D-Bus tube, return a string describing the address of the
         private bus.
@@ -372,8 +434,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 
     <method name="GetStreamUnixSocketAddress">
       <tp:docstring>
-        For a Stream Unix tube, obtain the path of the Unix socket
-        used to communicate over this tube.
+        For a stream tube, obtain the address of the socket used to
+        communicate over this tube.
       </tp:docstring>
       <arg direction="in" name="id" type="u">
         <tp:docstring>
@@ -388,7 +450,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 tube is not a Stream Unix tube.
+            The tube is not a stream tube.
           </tp:docstring>
         </tp:error>
         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
@@ -399,9 +461,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       </tp:possible-errors>
     </method>
 
-    <signal name="StreamUnixSocketNewConnection">
+    <signal name="StreamTubeNewConnection">
       <tp:docstring>
-        Emitted on a Stream Unix tube when a participant opens a new connection
+        Emitted on a stream tube when a participant opens a new connection
         to its socket.
       </tp:docstring>
       <arg name="id" type="u">