sync with spec 0.17.25

1 files changed, 111 insertions, 25 deletions

diff --git a/spec/Channel_Type_Stream_Tube.xml b/spec/Channel_Type_Stream_Tube.xml
index 060cd0bb0..63e7b2f50 100644
--- a/spec/Channel_Type_Stream_Tube.xml
+++ b/spec/Channel_Type_Stream_Tube.xml
@@ -17,19 +17,18 @@ You should have received a copy of the GNU Lesser General Public
 License along with this library; if not, write to the Free Software
 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
   </tp:license>
-  <interface name="org.freedesktop.Telepathy.Channel.Type.StreamTube.DRAFT"
-      tp:causes-havoc="experimental">
+  <interface name="org.freedesktop.Telepathy.Channel.Type.StreamTube">
     <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
-    <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT"/>
+    <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Tube"/>
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
       <p>A stream tube is a transport for ordered, reliable data transfer,
         similar to SOCK_STREAM sockets.</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
+        <tp:member-ref>Offer</tp:member-ref> method.  When a
         recipient accepts a stream tube using the
-        <tp:member-ref>AcceptStreamTube</tp:member-ref> method, the
+        <tp:member-ref>Accept</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
@@ -37,7 +36,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 
     </tp:docstring>
 
-    <method name="OfferStreamTube" tp:name-for-bindings="Offer_Stream_Tube">
+    <method name="Offer" tp:name-for-bindings="Offer">
       <tp:docstring>
         Offer a stream tube exporting the local socket specified.
       </tp:docstring>
@@ -60,17 +59,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
           when it connects.
         </tp:docstring>
       </arg>
-      <arg direction="in" name="access_control_param" type="v">
-        <tp:docstring>
-          A parameter for the access control type, to be interpreted as
-          specified in the documentation for the Socket_Access_Control enum.
-        </tp:docstring>
-      </arg>
       <arg direction="in" name="parameters" type="a{sv}"
         tp:type="String_Variant_Map">
         <tp:docstring>
           The dictionary of arbitrary
-          <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT">Parameters</tp:dbus-ref>
+          <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Tube">Parameters</tp:dbus-ref>
           to send with the tube offer.
         </tp:docstring>
       </arg>
@@ -91,12 +84,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       </tp:possible-errors>
     </method>
 
-    <method name="AcceptStreamTube" tp:name-for-bindings="Accept_Stream_Tube">
+    <method name="Accept" tp:name-for-bindings="Accept">
       <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.
+        the "local pending" state until the <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Channel.Interface.Tube">TubeChannelStateChanged</tp:dbus-ref>
+        signal is emitted.
       </tp:docstring>
       <arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type">
         <tp:docstring>
@@ -104,9 +98,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         </tp:docstring>
       </arg>
       <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control">
-        <tp:docstring>
-          The type of access control the connection manager should apply to
-          the socket.
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The type of access control the connection manager should apply to
+          the socket.</p>
+
+          <p>Note that if you plan to establish more than one connection
+          through the tube, the Socket_Access_Control_Port access control
+          can't be used as you can't connect more than once from the same
+          port.</p>
         </tp:docstring>
       </arg>
       <arg direction="in" name="access_control_param" type="v">
@@ -137,17 +136,94 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       </tp:possible-errors>
     </method>
 
-    <signal name="StreamTubeNewConnection"
-            tp:name-for-bindings="Stream_Tube_New_Connection">
-      <tp:docstring>
-        Emitted on a stream tube when a participant opens a new connection
-        to its socket.
+    <signal name="NewRemoteConnection"
+            tp:name-for-bindings="New_Remote_Connection">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Emitted each time a participant opens a new connection to its
+        socket.</p>
+
+        <p>This signal is only fired on the offering side.</p>
       </tp:docstring>
-      <arg name="handle" type="u" tp:type="Contact_Handle">
+      <arg name="Handle" type="u" tp:type="Contact_Handle">
         <tp:docstring>
           The handle of the participant who opened the new connection
         </tp:docstring>
       </arg>
+      <arg name="Connection_Param" type="v">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>A parameter which can be used by the listening process to identify
+          the connection. Note that this parameter has a meaningful value
+          only in the Socket_Access_Control_Port and
+          Socket_Access_Control_Credentials cases. If a different
+          Socket_Access_Control has been chosen when offering the tube, this
+          parameter should be ignored.</p>
+
+          <p>In the Socket_Access_Control_Port case, the variant
+          contains a struct Socket_Address_IPv4 (or Socket_Address_IPv6)
+          containing the address from which the CM is connected to the client
+          application.</p>
+
+          <p>In the Socket_Access_Control_Credentials case, the variant
+          contains the byte (D-Bus signature 'y') that has been sent with
+          the credentials.</p>
+        </tp:docstring>
+      </arg>
+      <arg name="Connection_ID" type="u" tp:type="Stream_Tube_Connection_ID">
+        <tp:docstring>
+          The unique ID associated with this connection. This ID will be used
+          to identifiy the connection when reporting errors with
+          <tp:member-ref>ConnectionClosed</tp:member-ref>.
+        </tp:docstring>
+      </arg>
+    </signal>
+
+    <signal name="NewLocalConnection"
+            tp:name-for-bindings="New_Local_Connection">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Emitted when the tube application connects to the CM's socket.</p>
+
+        <p>This signal is only fired on the accepting side.</p>
+      </tp:docstring>
+      <arg name="Connection_ID" type="u" tp:type="Stream_Tube_Connection_ID">
+        <tp:docstring>
+          The unique ID associated with this connection. This ID will be used
+          to identifiy the connection when reporting errors with
+          <tp:member-ref>ConnectionClosed</tp:member-ref>.
+        </tp:docstring>
+      </arg>
+    </signal>
+
+    <signal name="ConnectionClosed"
+            tp:name-for-bindings="Connection_Closed"
+            tp:type="Stream_Tube_Connection_Closed">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Emitted when a connection has been closed.</p>
+      </tp:docstring>
+      <arg name="Connection_ID" type="u" tp:type="Stream_Tube_Connection_ID">
+        <tp:docstring>
+          The ID of the connection.
+        </tp:docstring>
+      </arg>
+      <arg name="Error" type="s" tp:type="DBus_Error_Name">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The name of a D-Bus error describing the error that occurred.</p>
+
+          <p>The following errors can be used:</p>
+          <ul>
+            <li><code>org.freedesktop.Telepathy.Error.Cancelled</code>:
+               user closed the socket or the tube.</li>
+            <li><code>org.freedesktop.Telepathy.Error.ConnectionLost</code>:
+               the bytestream relaying connection's data has been broken.</li>
+            <li><code>org.freedesktop.Telepathy.Error.ConnectionRefused</code>:
+               the tube offer refused the connection.</li>
+          </ul>
+        </tp:docstring>
+      </arg>
+      <arg name="Message" type="s">
+        <tp:docstring>
+          A debug message.
+        </tp:docstring>
+      </arg>
     </signal>
 
     <property name="Service" type="s" access="read"
@@ -200,6 +276,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       </tp:docstring>
     </property>
 
+    <tp:simple-type name="Stream_Tube_Connection_ID" type="u">
+      <tp:docstring>An identifier for a stream tube connection.
+        These are defined with the
+        <tp:member-ref>NewLocalConnection</tp:member-ref> or
+        <tp:member-ref>NewRemoteConnection</tp:member-ref> signals
+        and are used by <tp:member-ref>ConnectionClosed</tp:member-ref>
+        to identify the closed connection.
+        </tp:docstring>
+    </tp:simple-type>
+
   </interface>
 
 </node>