telepathy-mission-control: Deprecate mcp_dispatch_operation_leave_channels

[Simon McVittie]

Module: telepathy-mission-control
Branch: master
Commit: a9afabf2a6219f27038b34e29d36cc20dd2965eb
URL:    http://cgit.freedesktop.org/telepathy/telepathy-mission-control/commit/?id=a9afabf2a6219f27038b34e29d36cc20dd2965eb

Author: Simon McVittie <simon.mcvittie at collabora.co.uk>
Date:   Wed Feb 13 15:01:54 2013 +0000

Deprecate mcp_dispatch_operation_leave_channels

It was designed for StreamedMedia, and is the wrong thing for Call.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=55391
Reviewed-by: Xavier Claessens <xavier.claessens at collabora.co.uk>

---

 mission-control-plugins/dispatch-operation.c |   16 ++++++++++++++++
 mission-control-plugins/dispatch-operation.h |    4 ++++
 tests/twisted/mcp-plugin.c                   |    5 +++++
 3 files changed, 25 insertions(+), 0 deletions(-)

diff --git a/mission-control-plugins/dispatch-operation.c b/mission-control-plugins/dispatch-operation.c
index 27a8bef..ab51eb9 100644
--- a/mission-control-plugins/dispatch-operation.c
+++ b/mission-control-plugins/dispatch-operation.c
@@ -295,6 +295,16 @@ mcp_dispatch_operation_end_delay (McpDispatchOperation *self,
  *
  * Leave all channels in this bundle by using RemoveMembersWithReason if the
  * channel has the Group interface, or Close if not.
+ *
+ * This method was intended for StreamedMedia channels, which (ab)used the
+ * Group interface for call control. StreamedMedia channels have been
+ * superseded by Call channels, which have a proper "hang up" method which
+ * should be used instead.
+ *
+ * Deprecated: 5.15.UNRELEASED: Use tp_call_channel_hangup_async() to
+ *  hang up Call channels, mcp_dispatch_operation_close_channels() to close
+ *  generic channels, or mcp_dispatch_operation_destroy_channels() to
+ *  terminate the channel destructively.
  */
 void
 mcp_dispatch_operation_leave_channels (McpDispatchOperation *self,
@@ -320,6 +330,9 @@ mcp_dispatch_operation_leave_channels (McpDispatchOperation *self,
  *  (usually recommended), wait for Observers to reply first
  *
  * Close all channels in this bundle by using the Close D-Bus method.
+ *
+ * Plugins that terminate an audio or audio/video call should
+ * use tp_call_channel_hangup_async() instead.
  */
 void
 mcp_dispatch_operation_close_channels (McpDispatchOperation *self,
@@ -340,6 +353,9 @@ mcp_dispatch_operation_close_channels (McpDispatchOperation *self,
  *
  * Close all channels in this bundle destructively, by using the Destroy D-Bus
  * method if implemented, or the Close D-Bus method if not.
+ *
+ * Plugins that terminate an audio or audio/video call should
+ * use tp_call_channel_hangup_async() instead.
  */
 void
 mcp_dispatch_operation_destroy_channels (McpDispatchOperation *self,
diff --git a/mission-control-plugins/dispatch-operation.h b/mission-control-plugins/dispatch-operation.h
index 7cb4dd6..5ad12d9 100644
--- a/mission-control-plugins/dispatch-operation.h
+++ b/mission-control-plugins/dispatch-operation.h
@@ -85,9 +85,13 @@ McpDispatchOperationDelay *mcp_dispatch_operation_start_delay (
 void mcp_dispatch_operation_end_delay (McpDispatchOperation *self,
     McpDispatchOperationDelay *delay);
 
+#ifndef MC_DISABLE_DEPRECATED
+G_DEPRECATED_FOR (mcp_dispatch_operation_close_channels or tp_call_channel_hangup_async)
 void mcp_dispatch_operation_leave_channels (McpDispatchOperation *self,
     gboolean wait_for_observers, TpChannelGroupChangeReason reason,
     const gchar *message);
+#endif
+
 void mcp_dispatch_operation_close_channels (McpDispatchOperation *self,
     gboolean wait_for_observers);
 void mcp_dispatch_operation_destroy_channels (McpDispatchOperation *self,
diff --git a/tests/twisted/mcp-plugin.c b/tests/twisted/mcp-plugin.c
index 1c53666..7d347b1 100644
--- a/tests/twisted/mcp-plugin.c
+++ b/tests/twisted/mcp-plugin.c
@@ -19,6 +19,7 @@
  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  */
 
+#undef MC_DISABLE_DEPRECATED
 #include "config.h"
 
 #include <mission-control-plugins/mission-control-plugins.h>
@@ -136,9 +137,11 @@ permission_cb (DBusPendingCall *pc,
         }
       else
         {
+          G_GNUC_BEGIN_IGNORE_DEPRECATIONS
           mcp_dispatch_operation_leave_channels (ctx->dispatch_operation,
               TRUE, TP_CHANNEL_GROUP_CHANGE_REASON_PERMISSION_DENIED,
               "Computer says no");
+          G_GNUC_END_IGNORE_DEPRECATIONS
         }
     }
   else
@@ -511,9 +514,11 @@ test_rejection_plugin_check_cdo (McpDispatchOperationPolicy *policy,
   else if (!tp_strdiff (target_id, "mc.hammer at example.net"))
     {
       DEBUG ("MC Hammer detected, leaving channels when observers have run");
+      G_GNUC_BEGIN_IGNORE_DEPRECATIONS
       mcp_dispatch_operation_leave_channels (dispatch_operation, TRUE,
           TP_CHANNEL_GROUP_CHANGE_REASON_PERMISSION_DENIED,
           "Can't touch this");
+      G_GNUC_END_IGNORE_DEPRECATIONS
     }
 
   g_hash_table_unref (properties);