[next] telepathy-glib: channel-manager: deprecate emit_new_channels

[Jonny Lamb]

Module: telepathy-glib
Branch: next
Commit: f28758a1337c3ad948845b4b03629afaebb9b894
URL:    http://cgit.freedesktop.org/telepathy/telepathy-glib/commit/?id=f28758a1337c3ad948845b4b03629afaebb9b894

Author: Jonny Lamb <jonny.lamb at collabora.co.uk>
Date:   Thu May 10 18:35:01 2012 +0100

channel-manager: deprecate emit_new_channels

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=47942
Signed-off-by: Jonny Lamb <jonny.lamb at collabora.co.uk>

---

 telepathy-glib/channel-manager.c |   17 +++++++++++++++--
 telepathy-glib/channel-manager.h |    2 ++
 2 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/telepathy-glib/channel-manager.c b/telepathy-glib/channel-manager.c
index 56fca96..da24493 100644
--- a/telepathy-glib/channel-manager.c
+++ b/telepathy-glib/channel-manager.c
@@ -237,6 +237,13 @@ channel_manager_base_init (gpointer klass)
        * generally emit NewChannels (and NewChannel) in response to this
        * signal, and then return from pending CreateChannel, EnsureChannel
        * and/or RequestChannel calls if appropriate.
+       *
+       * Since 0.UNRELEASED, clients should not emit more than one
+       *  channel in this signal at one time as the creation of
+       *  multiple channels together in a single signal is strongly
+       *  recommended against: it's very complicated, hard to get
+       *  right in clients, and not nearly as useful as it originally
+       *  sounded.
        */
       signals[S_NEW_CHANNELS] = g_signal_new ("new-channels",
           G_OBJECT_CLASS_TYPE (klass),
@@ -349,6 +356,13 @@ tp_channel_manager_get_type (void)
  * If @channels is non-empty, emit the #TpChannelManager::new-channels
  * signal indicating that those channels have been created.
  *
+ * Deprecated: in 0.UNRELEASED this function should not be
+ *  used. Signalling the creation of multiple channels together in a
+ *  single signal is strongly recommended against as it's very
+ *  complicated, hard to get right in clients, and not nearly as
+ *  useful as it originally sounded. Use
+ *  tp_channel_manager_emit_new_channel() instead.
+ *
  * Since: 0.7.15
  */
 void
@@ -372,8 +386,7 @@ tp_channel_manager_emit_new_channels (gpointer instance,
  *                  channel
  *
  * Emit the #TpChannelManager::new-channels signal indicating that the
- * channel has been created. (This is a convenient shortcut for calling
- * tp_channel_manager_emit_new_channels() with a one-entry hash table.)
+ * channel has been created.
  *
  * Since: 0.7.15
  */
diff --git a/telepathy-glib/channel-manager.h b/telepathy-glib/channel-manager.h
index 777a2ea..47e0aa6 100644
--- a/telepathy-glib/channel-manager.h
+++ b/telepathy-glib/channel-manager.h
@@ -129,6 +129,8 @@ GType tp_channel_manager_get_type (void);
 
 void tp_channel_manager_emit_new_channel (gpointer instance,
     TpExportableChannel *channel, GSList *request_tokens);
+
+_TP_DEPRECATED_IN_UNRELEASED
 void tp_channel_manager_emit_new_channels (gpointer instance,
     GHashTable *channels);