Upgrade to latest tube draft

From: Guillaume Desmottes <gdesmott@gnome.org>

svn path=/trunk/; revision=2485

3 files changed, 93 insertions, 84 deletions

diff --git a/extensions/Channel_Interface_Tube.xml b/extensions/Channel_Interface_Tube.xml
index 8e1ffab3a..8e6eb6514 100644
--- a/extensions/Channel_Interface_Tube.xml
+++ b/extensions/Channel_Interface_Tube.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" ?>
 <node name="/Channel_Interface_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright>
-  <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
+  <tp:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright>
+  <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
   <tp:license>
     This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
@@ -38,10 +38,29 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       HANDLE_TYPE_CONTACT (for 1-1 communication) or of type
       HANDLE_TYPE_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
+        capability representing each Tube type that they support
+       (<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>
     </tp:docstring>
 
     <property name="Parameters" type="a{sv}" tp:type="String_Variant_Map"
-              access="readwrite" tp:name-for-bindings="Parameters">
+              access="read" 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 to bootstrap legacy protocols where you can't
@@ -58,21 +77,23 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
           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 
+        <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 effects.</p>
+          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>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>
+          signal.</p>
       </tp:docstring>
     </property>
 
-    <property name="Status" type="u" tp:type="Tube_Channel_State" access="read"
-              tp:name-for-bindings="Status">
+    <property name="State" type="u" tp:type="Tube_Channel_State" access="read"
+              tp:name-for-bindings="State">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>Status of the tube in this channel.</p>
-        <p>When requesting a channel with 
+        <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>,
           this property MUST NOT be included in the request.</p>
       </tp:docstring>
diff --git a/extensions/Channel_Type_DBus_Tube.xml b/extensions/Channel_Type_DBus_Tube.xml
index a3b98d7e4..513d77caa 100644
--- a/extensions/Channel_Type_DBus_Tube.xml
+++ b/extensions/Channel_Type_DBus_Tube.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" ?>
 <node name="/Channel_Type_DBus_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright>
-  <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
+  <tp:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright>
+  <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
   <tp:license>
     This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
@@ -58,6 +58,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       <tp:docstring>
         Offers a D-Bus tube providing the service specified.
       </tp:docstring>
+      <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>
+          to send with the tube offer.
+        </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.NetworkError"/>
         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
@@ -66,11 +80,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
             capabilities.
           </tp:docstring>
         </tp:error>
-        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
-          <tp:docstring>
-            The connection manager doesn't support D-Bus tubes.
-          </tp:docstring>
-        </tp:error>
       </tp:possible-errors>
     </method>
 
@@ -87,71 +96,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
           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:docstring>
-            The given tube ID is invalid or does not refer to a D-Bus
-            tube.
-          </tp:docstring>
-        </tp:error>
-      </tp:possible-errors>
-    </method>
-
-    <method name="GetDBusTubeAddress"
-            tp:name-for-bindings="Get_DBus_Tube_Address">
-      <tp:docstring>
-        Return a string describing the address of the private bus.
-      </tp:docstring>
-      <arg direction="out" type="s">
-        <tp:docstring>
-          The bus address.
-        </tp:docstring>
-      </arg>
-      <tp:possible-errors>
-        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
-          <tp:docstring>
-            The tube is not a D-Bus tube.
-          </tp:docstring>
-        </tp:error>
-        <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>
-
-    <method name="GetDBusNames" tp:name-for-bindings="Get_DBus_Names">
-      <tp:docstring>
-        For a multi-user (i.e. Handle_Type_Room) D-Bus tube, obtain a mapping
-        between contact handles and their unique bus names on this tube.
-      </tp:docstring>
-      <arg direction="out" type="a(us)" tp:type="DBus_Tube_Member[]">
-        <tp:docstring>
-          An array of structures, each containing a contact handle and a D-Bus
-          bus name.
-        </tp:docstring>
-      </arg>
-      <tp:possible-errors>
-        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
-          <tp:docstring>
-            The tube is not a multi-user D-Bus tube.
-          </tp:docstring>
-        </tp:error>
-        <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="DBusNamesChanged" tp:name-for-bindings="DBus_Names_Changed">
       <tp:docstring>
         Emitted on a multi-user (i.e. Handle_Type_Room) D-Bus tube when a
-        participant opens or closes the tube.
+        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_Member[]">
+      <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>
@@ -171,12 +124,39 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
           com.example.ServiceName.</p>
         <p>When the tube is offered, the service name is transmitted to the
           other end.</p>
-        <p>When requesting a channel with 
+        <p>When requesting a channel with
           <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>
 
+    <property name="DBusNames" tp:name-for-bindings="DBus_Names"
+      access="read" type="a{us}" tp:type="DBus_Tube_Participants">
+      <tp:docstring>
+        For a multi-user (i.e. Handle_Type_Room) D-Bus tube, a mapping
+        between contact handles and their unique bus names on this tube.
+        For a peer-to-peer (i.e. Handle_Type_Contact) D-Bus tube, the empty
+        dictionary.  Change notification is via
+        <tp:member-ref>DBusNamesChanged</tp:member-ref>.
+      </tp:docstring>
+    </property>
+
+    <tp:mapping name="DBus_Tube_Participants">
+      <tp:docstring>Represents the participants in a multi-user D-Bus tube, as
+        used by the <tp:member-ref>DBusNames</tp:member-ref> property and the
+        <tp:member-ref>DBusNamesChanged</tp:member-ref> signal.</tp:docstring>
+      <tp:member type="u" tp:type="Contact_Handle" name="Handle">
+        <tp:docstring>
+          The handle of a participant in this D-Bus tube.
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="s" tp:type="DBus_Unique_Name" name="Unique_Name">
+        <tp:docstring>
+          That participant's unique name.
+        </tp:docstring>
+      </tp:member>
+    </tp:mapping>
+
   </interface>
 
 </node>
diff --git a/extensions/Channel_Type_Stream_Tube.xml b/extensions/Channel_Type_Stream_Tube.xml
index 4a43a0074..060cd0bb0 100644
--- a/extensions/Channel_Type_Stream_Tube.xml
+++ b/extensions/Channel_Type_Stream_Tube.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" ?>
 <node name="/Channel_Type_Stream_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright>
-  <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
+  <tp:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright>
+  <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
   <tp:license>
     This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
@@ -66,6 +66,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
           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>
+          to send with the tube offer.
+        </tp:docstring>
+      </arg>
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
@@ -154,7 +162,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
           "rsync" or "daap".</p>
         <p>When the tube is offered, the service name is transmitted to the
           other end.</p>
-        <p>When requesting a channel with 
+        <p>When requesting a channel with
           <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>
@@ -185,7 +193,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         <p>Connection Managers MUST support at least IPv4 with the localhost
           access control.</p>
 
-        <p>When requesting a channel with 
+        <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>