Import telepathy-spec 0.17.25, plus a patch to errors.xml to correct error naming

Reviewed-by: Andre Moreira Magalhaes (andrunko) <andre.magalhaes@collabora.co.uk>

7 files changed, 333 insertions, 171 deletions

diff --git a/spec/Channel_Interface_Tube.xml b/spec/Channel_Interface_Tube.xml
index 5d1eda71..45506738 100644
--- a/spec/Channel_Interface_Tube.xml
+++ b/spec/Channel_Interface_Tube.xml
@@ -17,8 +17,7 @@ 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.Interface.Tube.DRAFT"
-      tp:causes-havoc="experimental">
+  <interface name="org.freedesktop.Telepathy.Channel.Interface.Tube">
     <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
       <p>A <i>tube</i> is a mechanism for arbitrary data transfer between
@@ -26,37 +25,38 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       systems to communicate without having to establish network
       connections themselves. Currently, two types of tube exist:
       <tp:dbus-ref namespace="org.freedesktop.Telepathy"
-      >Channel.Type.DBusTube.DRAFT</tp:dbus-ref> and
+      >Channel.Type.DBusTube</tp:dbus-ref> and
       <tp:dbus-ref namespace="org.freedesktop.Telepathy"
-      >Channel.Type.StreamTube.DRAFT</tp:dbus-ref>. This interface contains
+      >Channel.Type.StreamTube</tp:dbus-ref>. This interface contains
       the properties, signals and methods common to both types of tube;
       you can only create channels of a specific tube type, not of this
       type. A tube channel contains exactly one tube; if you need several
       tubes, you have to create several tube channels.</p>
 
-      <p>Tube channels can be requested for handles of type
-      HANDLE_TYPE_CONTACT (for 1-1 communication) or of type
-      HANDLE_TYPE_ROOM (to communicate with others in the room
-      simultaneously).</p>
+      <p>Tube channels can be requested for <tp:type>Handle_Type</tp:type>
+        Contact (for 1-1 communication) or Room (to communicate with others in
+        the room simultaneously).</p>
 
       <p>As an exception to the usual handling of capabilities, connection managers
-        for protocols with capability discovery, such as XMPP, SHOULD advertise the
+        for protocols with capability discovery (such as XMPP) SHOULD advertise the
         capability representing each Tube type that they support
-       (<tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.DBusTube.DRAFT</tp:dbus-ref> and/or
-        <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.StreamTube.DRAFT</tp:dbus-ref>)
+       (<tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.DBusTube</tp:dbus-ref> and/or
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.StreamTube</tp:dbus-ref>)
         even if no client has indicated via
         <tp:dbus-ref
           namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</tp:dbus-ref>
-        that such a tube is supported.</p>
-
-        <tp:rationale>
-          <p>To lower the barrier entry of new tube application, CM SHOULD accept to offer tubes of any
-            <tp:dbus-ref
-              namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube.DRAFT">Service</tp:dbus-ref> or
-            <tp:dbus-ref
-              namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube.DRAFT">ServiceName</tp:dbus-ref>
-            if the contact announced to support tubes.</p>
-        </tp:rationale>
+        that such a tube is supported. They SHOULD also allow clients to offer tubes with any
+        <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube">Service</tp:dbus-ref> or
+        <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube">ServiceName</tp:dbus-ref>
+        to any contact which supports the corresponding tube capability.</p>
+
+      <tp:rationale>
+        <p>This lowers the barrier to entry for those writing new tube
+          applications, and preserves interoperability with older versions of
+          the Telepathy stack which did not support rich capabilities.</p>
+      </tp:rationale>
     </tp:docstring>
 
     <property name="Parameters" type="a{sv}" tp:type="String_Variant_Map"
@@ -65,26 +65,43 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         <p>Each tube has a dictionary of arbitrary parameters. Parameters are
           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
-          type 'i') and boolean (D-Bus type 'b').</p>
+          types and values are defined by the service, but connection managers
+          must support the value being a string (D-Bus type <tt>'s'</tt>),
+          array of bytes (D-Bus type <tt>'ay'</tt>), unsigned integer (D-Bus
+          type <tt>'u'</tt>), integer (D-Bus type <tt>'i'</tt>) and boolean
+          (D-Bus type <tt>'b'</tt>).</p>
+
         <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 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 MUST NOT be included in the request. This property is undefined until the tube is offered
-          (using <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube.DRAFT">OfferStreamTube</tp:dbus-ref>
-          or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube.DRAFT">OfferDBusTube</tp:dbus-ref>).
-          Once it has been offered, this property MUST NOT change.</p>
+
+        <p>For example, a stream tube for <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube">Service</tp:dbus-ref>
+          <tt>"smb"</tt> (<cite>Server Message Block over TCP/IP</cite>) might
+          use the following properties, as defined in <a
+          href="http://www.dns-sd.org/ServiceTypes.html">DNS SRV (RFC 2782)
+          Service Types</a>:</p>
+
+        <pre>
+{ 'u': 'some-username',
+  'p': 'top-secret-password',
+  'path': '/etc/passwd',
+}</pre>
+
+        <p>When requesting a tube with
+          <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>,
+          this property MUST NOT be included in the request; instead, it is set
+          when <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.Channel.Type">StreamTube.Offer</tp:dbus-ref>
+          or <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.Channel.Type">DBusTube.Offer</tp:dbus-ref>
+          (as appropriate) is called. Its value is undefined until the tube is
+          offered; once set, its value MUST NOT change.</p>
+
         <p>When receiving an incoming tube, this property is immutable and so advertised in the
-          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.NewChannels</tp:dbus-ref>
+          <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>
           signal.</p>
       </tp:docstring>
     </property>
@@ -93,8 +110,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
               tp:name-for-bindings="State">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>State of the tube in this channel.</p>
-        <p>When requesting a channel with
-          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
+
+        <p>When requesting a tube 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>
@@ -124,8 +143,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         <tp:docstring>
           The tube channel has been requested but the tube is not yet offered.
           The client should offer the tube to the recipient and the tube's
-          state will be Remote_Pending. The method to offer the tube depend on
-          the tube type.
+          state will be Remote_Pending. The method used to offer the tube
+          depends on the tube type.
         </tp:docstring>
       </tp:enumvalue>
     </tp:enum>
@@ -133,15 +152,106 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
     <signal name="TubeChannelStateChanged"
             tp:name-for-bindings="Tube_Channel_State_Changed">
       <tp:docstring>
-        Emitted when the state of the tube channel changes.
+        Emitted when the state of the tube channel changes. Valid state
+        transitions are documented with <tp:type>Tube_Channel_State</tp:type>.
       </tp:docstring>
-      <arg name="state" type="u" tp:type="Tube_Channel_State">
+      <arg name="State" type="u" tp:type="Tube_Channel_State">
         <tp:docstring>
-          The new state of the tube; see the Tube_Channel_State enumeration.
+          The new state of the tube.
         </tp:docstring>
       </arg>
     </signal>
 
+    <tp:enum name="Socket_Address_Type" type="u">
+      <tp:enumvalue suffix="Unix" value="0">
+        <tp:docstring>
+          A Unix socket. The address variant contains a byte-array, signature 'ay',
+          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 variant contains a byte-array,
+          signature 'ay', containing the path of the socket including the
+          leading null byte.
+        </tp:docstring>
+      </tp:enumvalue>
+
+      <tp:enumvalue suffix="IPv4" value="2">
+        <tp:docstring>
+          An IPv4 socket. The address variant contains a Socket_Address_IPv4,
+          i.e. a structure with signature (sq)
+          in which the string is an IPv4 dotted-quad address literal
+          (and must not be a DNS name), while the 16-bit unsigned integer is
+          the port number.
+        </tp:docstring>
+      </tp:enumvalue>
+
+      <tp:enumvalue suffix="IPv6" value="3">
+        <tp:docstring>
+          An IPv6 socket. The address variant contains a Socket_Address_IPv6,
+          i.e. a structure with signature (sq)
+          in which the string is an IPv6 address literal as specified in
+          RFC2373 (and must not be a DNS name), while the 16-bit unsigned
+          integer is the port number.
+        </tp:docstring>
+      </tp:enumvalue>
+
+    </tp:enum>
+
+    <tp:enum name="Socket_Access_Control" type="u"
+      array-name="Socket_Access_Control_List">
+      <tp:enumvalue suffix="Localhost" value="0">
+        <tp:docstring>
+          The IP or Unix socket can be accessed by any local user (e.g.
+          a Unix socket that accepts all local connections, or an IP socket
+          listening on 127.0.0.1 (or ::1) or rejecting connections not from
+          that address). The associated variant must be ignored.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Port" value="1">
+        <tp:docstring>
+          May only be used on IP sockets. The associated variant must contain
+          a struct Socket_Address_IPv4 (or Socket_Address_IPv6)
+          containing the string form of an IP address of the appropriate
+          version, and a port number. The socket can only be accessed if the
+          connecting process has that address and port number; all other
+          connections will be rejected.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Netmask" value="2">
+        <tp:deprecated version="0.17.25">This has never been implemented.
+        If you want to share a service to your whole LAN, Telepathy is
+        not the way to do it.</tp:deprecated>
+        <tp:docstring>
+          May only be used on IP sockets. The associated variant must contain
+          a struct Socket_Netmask_IPv4 (or Socket_Netmask_IPv6) with
+          signature (sy), containing the string form of an
+          IP address of the appropriate version, and a prefix length "n".
+          The socket can only be accessed if the first n bits of the
+          connecting address match the first n bits of the given address.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Credentials" value="3">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>May only be used on UNIX sockets.
+            The connecting process must send a byte when
+            it first connects, which is not considered to be part of the data
+            stream. If the operating system uses sendmsg() with SCM_CREDS or
+            SCM_CREDENTIALS to pass credentials over sockets, the connecting
+            process must do so if possible; if not, it must still send the
+            byte.</p>
+
+          <p>The listening process will disconnect the connection unless it
+            can determine by OS-specific means that the connecting process
+            has the same user ID as the listening process.</p>
+
+          <p>The associated variant must be ignored.</p>
+        </tp:docstring>
+      </tp:enumvalue>
+    </tp:enum>
+
   </interface>
 
 </node>
diff --git a/spec/Channel_Type_DBus_Tube.xml b/spec/Channel_Type_DBus_Tube.xml
index 513d77ca..96157631 100644
--- a/spec/Channel_Type_DBus_Tube.xml
+++ b/spec/Channel_Type_DBus_Tube.xml
@@ -17,10 +17,9 @@ 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.DBusTube.DRAFT"
-      tp:causes-havoc="experimental">
+  <interface name="org.freedesktop.Telepathy.Channel.Type.DBusTube">
     <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 D-Bus tube is an ordered reliable transport, for transporting D-Bus
         traffic.</p>
@@ -54,7 +53,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 
     </tp:docstring>
 
-    <method name="OfferDBusTube" tp:name-for-bindings="Offer_DBus_Tube">
+    <method name="Offer" tp:name-for-bindings="Offer">
       <tp:docstring>
         Offers a D-Bus tube providing the service specified.
       </tp:docstring>
@@ -62,14 +61,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         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>
+      <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control">
+        <tp:docstring>
+          The access control the connection manager applies to the D-Bus socket.
+        </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.
+          SHOULD NOT attempt to connect to the address until the tube is open.
         </tp:docstring>
       </arg>
       <tp:possible-errors>
@@ -83,17 +87,23 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       </tp:possible-errors>
     </method>
 
-    <method name="AcceptDBusTube" tp:name-for-bindings="Accept_DBus_Tube">
+    <method name="Accept" tp:name-for-bindings="Accept">
       <tp:docstring>
         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.
+        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="access_control" type="u" tp:type="Socket_Access_Control">
+        <tp:docstring>
+          The access control the connection manager applies to the D-Bus socket.
+        </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.
+          SHOULD NOT attempt to connect to the address until the tube is open.
         </tp:docstring>
       </arg>
     </method>
@@ -104,12 +114,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         participant opens or closes the tube.  This provides change
         notification for the <tp:member-ref>DBusNames</tp:member-ref> property.
       </tp:docstring>
-      <arg name="added" type="a{us}" tp:type="DBus_Tube_Participants">
+      <arg name="Added" type="a{us}" tp:type="DBus_Tube_Participants">
         <tp:docstring>
           Array of handles and D-Bus names of new participants.
         </tp:docstring>
       </arg>
-      <arg name="removed" type="au" tp:type="Contact_Handle[]">
+      <arg name="Removed" type="au" tp:type="Contact_Handle[]">
         <tp:docstring>
           Array of handles of former participants.
         </tp:docstring>
@@ -121,11 +131,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       <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
-          com.example.ServiceName.</p>
+          <tt>com.example.ServiceName</tt>.</p>
         <p>When the tube is offered, the service name is transmitted to the
           other end.</p>
         <p>When requesting a channel with
-          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
+          <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>,
           this property MUST be included in the request.</p>
       </tp:docstring>
     </property>
@@ -157,6 +168,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       </tp:member>
     </tp:mapping>
 
+    <property name="SupportedAccessControls" type="au"
+              tp:type="Socket_Access_Control[]" access="read"
+              tp:name-for-bindings="Supported_Access_Controls">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>A list of the access control types that are supported with this channel.
+        Note that only Socket_Access_Control_Localhost and
+        Socket_Access_Control_Credentials can be used with D-Bus tubes.</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>
+
   </interface>
 
 </node>
diff --git a/spec/Channel_Type_Stream_Tube.xml b/spec/Channel_Type_Stream_Tube.xml
index 060cd0bb..63e7b2f5 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>
diff --git a/spec/Channel_Type_Tubes.xml b/spec/Channel_Type_Tubes.xml
index 2cc0131b..c0a973fa 100644
--- a/spec/Channel_Type_Tubes.xml
+++ b/spec/Channel_Type_Tubes.xml
@@ -19,6 +19,14 @@ 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.Tubes">
+
+    <tp:deprecated version="0.17.25">Client implementations
+      SHOULD use <tp:dbus-ref
+        namespace="org.freedesktop.Telepathy.Channel.Type">StreamTube</tp:dbus-ref> and
+        <tp:dbus-ref
+        namespace="org.freedesktop.Telepathy.Channel.Type">DBusTube</tp:dbus-ref>
+      instead.</tp:deprecated>
+
     <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. Two types of
@@ -105,92 +113,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       </tp:enumvalue>
     </tp:enum>
 
-    <tp:enum name="Socket_Address_Type" type="u">
-      <tp:enumvalue suffix="Unix" value="0">
-        <tp:docstring>
-          A Unix socket. The address variant contains a byte-array, signature 'ay',
-          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 variant contains a byte-array,
-          signature 'ay', containing the path of the socket including the
-          leading null byte.
-        </tp:docstring>
-      </tp:enumvalue>
-
-      <tp:enumvalue suffix="IPv4" value="2">
-        <tp:docstring>
-          An IPv4 socket. The address variant contains a Socket_Address_IPv4,
-          i.e. a structure with signature (sq)
-          in which the string is an IPv4 dotted-quad address literal
-          (and must not be a DNS name), while the 16-bit unsigned integer is
-          the port number.
-        </tp:docstring>
-      </tp:enumvalue>
-
-      <tp:enumvalue suffix="IPv6" value="3">
-        <tp:docstring>
-          An IPv6 socket. The address variant contains a Socket_Address_IPv6,
-          i.e. a structure with signature (sq)
-          in which the string is an IPv6 address literal as specified in
-          RFC2373 (and must not be a DNS name), while the 16-bit unsigned
-          integer is the port number.
-        </tp:docstring>
-      </tp:enumvalue>
-
-    </tp:enum>
-
-    <tp:enum name="Socket_Access_Control" type="u"
-      array-name="Socket_Access_Control_List">
-      <tp:enumvalue suffix="Localhost" value="0">
-        <tp:docstring>
-          The IP or Unix socket can be accessed by any local user (e.g.
-          a Unix socket that accepts all local connections, or an IP socket
-          listening on 127.0.0.1 (or ::1) or rejecting connections not from
-          that address). The associated variant must be ignored.
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Port" value="1">
-        <tp:docstring>
-          May only be used on IP sockets. The associated variant must contain
-          a struct Socket_Address_IPv4 (or Socket_Address_IPv6)
-          containing the string form of an IP address of the appropriate
-          version, and a port number. The socket can only be accessed if the
-          connecting process has that address and port number; all other
-          connections will be rejected.
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Netmask" value="2">
-        <tp:docstring>
-          May only be used on IP sockets. The associated variant must contain
-          a struct Socket_Netmask_IPv4 (or Socket_Netmask_IPv6) with
-          signature (sy), containing the string form of an
-          IP address of the appropriate version, and a prefix length "n".
-          The socket can only be accessed if the first n bits of the
-          connecting address match the first n bits of the given address.
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Credentials" value="3">
-        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-          <p>The connecting process must send a single zero (NUL) byte when
-            it first connects, which is not considered to be part of the data
-            stream. If the operating system uses sendmsg() with SCM_CREDS or
-            SCM_CREDENTIALS to pass credentials over sockets, the connecting
-            process must do so if possible; if not, it must still send the
-            byte.</p>
-
-          <p>The listening process will disconnect the connection unless it
-            can determine by OS-specific means that the connecting process
-            has the same user ID as the listening process.</p>
-
-          <p>The associated variant must be ignored.</p>
-        </tp:docstring>
-      </tp:enumvalue>
-    </tp:enum>
-
     <tp:mapping name="Supported_Socket_Map">
       <tp:docstring>The supported socket address and access-control types
         for tubes. See GetAvailableStreamTubeTypes.</tp:docstring>
diff --git a/spec/Properties_Interface.xml b/spec/Properties_Interface.xml
index aaa46029..bc9c8b26 100644
--- a/spec/Properties_Interface.xml
+++ b/spec/Properties_Interface.xml
@@ -158,7 +158,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         tp:type="Property_Value[]">
         <!-- XXX: if we're ever breaking API compatibility, make this a{uv} -->
       <tp:docstring>
-        A dictionary mapping integer identifiers to boxed values
+        An array mapping integer property identifiers to boxed values
       </tp:docstring>
       </arg>
       <tp:possible-errors>
diff --git a/spec/all.xml b/spec/all.xml
index 080fa83a..ed74cb84 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -3,7 +3,7 @@
   xmlns:xi="http://www.w3.org/2001/XInclude">
 
 <tp:title>Telepathy D-Bus Interface Specification</tp:title>
-<tp:version>0.17.24</tp:version>
+<tp:version>0.17.25</tp:version>
 
 <tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright>
 <tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright>
diff --git a/spec/errors.xml b/spec/errors.xml
index f82c532e..7b1798d1 100644
--- a/spec/errors.xml
+++ b/spec/errors.xml
@@ -307,6 +307,24 @@
     </tp:docstring>
   </tp:error>
 
+  <tp:error name="Connection Refused">
+    <tp:docstring>
+      Raised when a connection is refused.
+    </tp:docstring>
+  </tp:error>
+
+  <tp:error name="Connection Failed">
+    <tp:docstring>
+      Raised when a connection can't be established.
+    </tp:docstring>
+  </tp:error>
+
+  <tp:error name="Connection Lost">
+    <tp:docstring>
+      Raised when a connection is broken.
+    </tp:docstring>
+  </tp:error>
+
   <tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright>
   <tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright>
   <tp:license xmlns="http://www.w3.org/1999/xhtml">