[telepathy-mission-control/master] fd.o #21169: Update ChannelRequest from telepathy-spec master, and implement it

[Simon McVittie]

Implement and test PreferredHandler property; no further substantive
changes.
---
 .../libmissioncontrol-server/tmpl/mcd-channel.sgml |    5 +++++
 src/mcd-channel.c                                  |   19 +++++++++++++++++++
 test/twisted/dispatcher/create-text.py             |    1 +
 xml/Channel_Request.xml                            |   20 ++++++++++++++++++++
 4 files changed, 45 insertions(+), 0 deletions(-)

diff --git a/doc/reference/libmissioncontrol-server/tmpl/mcd-channel.sgml b/doc/reference/libmissioncontrol-server/tmpl/mcd-channel.sgml
index 124280d..968dc4c 100644
--- a/doc/reference/libmissioncontrol-server/tmpl/mcd-channel.sgml
+++ b/doc/reference/libmissioncontrol-server/tmpl/mcd-channel.sgml
@@ -48,6 +48,11 @@ McdChannel
 
 </para>
 
+<!-- ##### ARG McdChannel:preferred-handler ##### -->
+<para>
+
+</para>
+
 <!-- ##### ARG McdChannel:requests ##### -->
 <para>
 
diff --git a/src/mcd-channel.c b/src/mcd-channel.c
index 9cde325..d284371 100644
--- a/src/mcd-channel.c
+++ b/src/mcd-channel.c
@@ -111,6 +111,7 @@ enum _McdChannelPropertyType
     PROP_ACCOUNT_PATH,
     PROP_REQUESTS,
     PROP_USER_ACTION_TIME,
+    PROP_PREFERRED_HANDLER,
 };
 
 #define DEPRECATED_PROPERTY_WARNING \
@@ -403,6 +404,15 @@ _mcd_channel_get_property (GObject * obj, guint prop_id,
         g_value_set_int64 (val, 0);
         break;
 
+    case PROP_PREFERRED_HANDLER:
+        if (priv->request_data != NULL)
+        {
+            g_value_set_string (val, priv->request_data->preferred_handler);
+            break;
+        }
+        g_value_set_static_string (val, "");
+        break;
+
     case PROP_REQUESTS:
         if (priv->request_data != NULL &&
             priv->request_data->properties != NULL)
@@ -551,6 +561,7 @@ mcd_channel_class_init (McdChannelClass * klass)
     static TpDBusPropertiesMixinPropImpl request_props[] = {
         { "Account", "account-path", NULL },
         { "UserActionTime", "user-action-time", NULL },
+        { "PreferredHandler", "preferred-handler", NULL },
         { "Requests", "requests", NULL },
         { NULL }
     };
@@ -617,6 +628,14 @@ mcd_channel_class_init (McdChannelClass * klass)
                              G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 
     g_object_class_install_property
+        (object_class, PROP_PREFERRED_HANDLER,
+         g_param_spec_string ("preferred-handler",
+                             "PreferredHandler",
+                             "Well-known bus name of the preferred Handler",
+                             NULL,
+                             G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
+
+    g_object_class_install_property
         (object_class, PROP_USER_ACTION_TIME,
          g_param_spec_int64 ("user-action-time",
                              "UserActionTime",
diff --git a/test/twisted/dispatcher/create-text.py b/test/twisted/dispatcher/create-text.py
index 528f42b..ccbdfba 100644
--- a/test/twisted/dispatcher/create-text.py
+++ b/test/twisted/dispatcher/create-text.py
@@ -88,6 +88,7 @@ def test_channel_creation(q, bus, account, client, conn, ensure):
     assert request_props['Account'] == account.object_path
     assert request_props['Requests'] == [request]
     assert request_props['UserActionTime'] == user_action_time
+    assert request_props['PreferredHandler'] == client.bus_name
 
     cr.Proceed(dbus_interface=cs.CR + '.DRAFT')
 
diff --git a/xml/Channel_Request.xml b/xml/Channel_Request.xml
index 3706bdb..e1ba48e 100644
--- a/xml/Channel_Request.xml
+++ b/xml/Channel_Request.xml
@@ -37,6 +37,12 @@
           <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelDispatcher.DRAFT.CreateChannel</tp:dbus-ref>
           for rationale for ChannelRequest being a separate object.</p>
       </tp:rationale>
+
+      <p>A channel request can be cancelled by any client (not just the one
+        that requested it). This means that the ChannelDispatcher will
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref>
+        the resulting channel, or refrain from requesting it at all, rather
+        than dispatching it to a handler.</p>
     </tp:docstring>
 
     <property name="Account" tp:name-for-bindings="Account"
@@ -62,6 +68,20 @@
       </tp:docstring>
     </property>
 
+    <property name="PreferredHandler" tp:name-for-bindings="Preferred_Handler"
+      type="s" tp:type="DBus_Well_Known_Name" access="read">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>Either the well-known bus name (starting with
+            <code>org.freedesktop.Telepathy.Client.</code>)
+            of the preferred handler for this
+            channel, or an empty string to indicate that any handler would be
+            acceptable.</p>
+
+        <p>This property is set when the channel request is created,
+          and can never change.</p>
+      </tp:docstring>
+    </property>
+
     <property name="Requests" tp:name-for-bindings="Requests" type="aa{sv}"
       tp:type="Qualified_Property_Value_Map[]"
       access="read">
-- 
1.5.6.5