[glibmm] giomm: DBus: Add watch/unwatch_name().

[José Alburquerque <jaalburqu src gnome org>]

commit 1ad299035b85458f731e28a8b7f9b1cdc0baec0e
Author: José Alburquerque <jaalburqu svn gnome org>
Date:   Thu Sep 2 19:59:30 2010 -0400

    	giomm: DBus: Add watch/unwatch_name().
    
    	* gio/src/dbuswatchname.{ccg,hg}:
    	* gio/src/filelist.am: Add watch/unwatch_name() functions to the
    	Gio::DBus namespace wrapping the Gio Bus Name Watching API.

 ChangeLog                 |    8 +++
 gio/src/dbuswatchname.ccg |  115 +++++++++++++++++++++++++++++++++++++++++++
 gio/src/dbuswatchname.hg  |  119 +++++++++++++++++++++++++++++++++++++++++++++
 gio/src/filelist.am       |    1 +
 4 files changed, 243 insertions(+), 0 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 5d54522..0ce783d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2010-09-02  José Alburquerque  <jaalburqu svn gnome org>
+
+	giomm: DBus: Add watch/unwatch_name().
+
+	* gio/src/dbuswatchname.{ccg,hg}:
+	* gio/src/filelist.am: Add watch/unwatch_name() functions to the
+	Gio::DBus namespace wrapping the Gio Bus Name Watching API.
+
 2010-09-02  Murray Cumming  <murrayc murrayc com>
 
 	giomm: Added Proxy, ProxyAddress and ProxyResolver.
diff --git a/gio/src/dbuswatchname.ccg b/gio/src/dbuswatchname.ccg
new file mode 100644
index 0000000..1983144
--- /dev/null
+++ b/gio/src/dbuswatchname.ccg
@@ -0,0 +1,115 @@
+// -*- Mode: C++; indent-tabs-mode: nil; c-basic-offset: 2 -*-
+
+/* Copyright (C) 2010 The giomm Development Team
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * 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., 675 Mass Ave, Cambridge, MA 02139, USA.
+ */
+
+#include <gio/gio.h>
+
+namespace
+{
+
+// Structure to hold the slots registred with watch_name().
+struct WatchSlots
+{
+  Gio::DBus::SlotNameAppeared* name_appeared_slot;
+  Gio::DBus::SlotNameVanished* name_vanished_slot;
+};
+
+extern "C"
+{
+
+static void Bus_Name_Appeared_giomm_callback(GDBusConnection* connection,
+  const gchar* name, const char* name_owner, gpointer data)
+{
+  WatchSlots* slots = static_cast<WatchSlots*>(data);
+  Gio::DBus::SlotNameAppeared* the_slot = slots->name_appeared_slot;
+
+  try
+  {
+    (*the_slot)(Glib::wrap(connection, true), Glib::ustring(name),
+      Glib::ustring(name_owner));
+  }
+  catch(...)
+  {
+    Glib::exception_handlers_invoke();
+  }
+}
+
+static void Bus_Name_Vanished_giomm_callback(GDBusConnection* connection,
+  const gchar* name, gpointer data)
+{
+  WatchSlots* slots = static_cast<WatchSlots*>(data);
+  Gio::DBus::SlotNameVanished* the_slot = slots->name_vanished_slot;
+
+  try
+  {
+    (*the_slot)(Glib::wrap(connection, true), Glib::ustring(name));
+  }
+  catch(...)
+  {
+    Glib::exception_handlers_invoke();
+  }
+}
+
+static void Bus_Watch_Name_giomm_callback_destroy(void* data)
+{
+  WatchSlots* slots =  static_cast<WatchSlots*>(data);
+
+  if(slots->name_appeared_slot)
+    delete slots->name_appeared_slot;
+
+  if(slots->name_vanished_slot)
+    delete slots->name_vanished_slot;
+
+  delete slots;
+}
+
+} // extern "C"
+
+} // anonymous namespace
+
+
+namespace Gio
+{
+
+namespace DBus
+{
+
+guint watch_name(BusType bus_type, const Glib::ustring& name,
+  BusNameWatcherFlags flags, const SlotNameAppeared& name_appeared_slot,
+  const SlotNameVanished& name_vanished_slot)
+{
+  struct WatchSlots* slots = new WatchSlots;
+
+  // Make copies of the slots which will be deleted on destroy notification.
+  slots->name_appeared_slot = new SlotNameAppeared(name_appeared_slot);
+  slots->name_vanished_slot = new SlotNameVanished(name_vanished_slot);
+
+  return g_bus_watch_name(static_cast<GBusType>(bus_type), name.c_str(),
+    static_cast<GBusNameWatcherFlags>(flags), 
+    &Bus_Name_Appeared_giomm_callback, &Bus_Name_Vanished_giomm_callback,
+    slots, &Bus_Watch_Name_giomm_callback_destroy);
+}
+
+void unwatch_name(guint watcher_id)
+{
+  g_bus_unwatch_name(watcher_id);
+}
+
+} // namespace DBus
+
+} // namespace Gio
diff --git a/gio/src/dbuswatchname.hg b/gio/src/dbuswatchname.hg
new file mode 100644
index 0000000..8228641
--- /dev/null
+++ b/gio/src/dbuswatchname.hg
@@ -0,0 +1,119 @@
+// -*- Mode: C++; indent-tabs-mode: nil; c-basic-offset: 2 -*-
+
+/* Copyright (C) 2010 The giomm Development Team
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * 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., 675 Mass Ave, Cambridge, MA 02139, USA.
+ */
+
+#include <giomm/dbusconnection.h>
+
+_DEFS(giomm,gio)
+
+namespace Gio
+{
+
+namespace DBus
+{
+
+_WRAP_ENUM(BusNameWatcherFlags, GBusNameWatcherFlags)
+
+/** For example,
+ * void on_name_appeared(const Glib::RefPtr<Gio::DBusConnection>& connection,
+ * const Glib::ustring& name, const Glib::ustring& name_owner);
+ */
+typedef sigc::slot<void, const Glib::RefPtr<Gio::DBusConnection>&, Glib::ustring, const Glib::ustring&> SlotNameAppeared;
+
+/** For example,
+ * void on_name_vanished(const Glib::RefPtr<Gio::DBusConnection>& connection,
+ * const Glib::ustring& name);
+ */
+typedef sigc::slot<void, const Glib::RefPtr<Gio::DBusConnection>&, Glib::ustring> SlotNameVanished;
+
+//TODO: Add example from C API in class docs?
+/** Starts watching @a name on the bus specified by @a bus_type and calls
+ * @a name_appeared_slot and @a name_vanished_slot when the name is
+ * known to have a owner respectively known to lose its owner. Callbacks will
+ * be invoked in the thread-default main loop of the thread you are calling
+ * this function from.
+ *
+ * You are guaranteed that one of the slot will be invoked after calling
+ * this function. When you are done watching the name, just call
+ * unwatch_name() with the watcher id this function returns.
+ *
+ * If the name vanishes or appears (for example the application owning the
+ * name could restart), the slot are also invoked. If the DBusConnection
+ * that is used for watching the name disconnects, then @a
+ * name_vanished_slot is invoked since it is no longer possible to access
+ * the name.
+ *
+ * Another guarantee is that invocations of @a name_appeared_slot and @a
+ * name_vanished_slot are guaranteed to alternate; that is, if
+ * @a name_appeared_slot is invoked then you are guaranteed that the next
+ * time one of the slot is invoked, it will be @a name_vanished_slot.
+ * The reverse is also true.
+ *
+ * This behavior makes it very simple to write applications that wants to take
+ * action when a certain name exists, see the C API's Example 9, â??Simple
+ * application watching a nameâ?? for more information. Basically, the
+ * application should create object proxies in @a name_appeared_slot and
+ * destroy them again (if any) in @a name_vanished_slot.
+ *
+ * @param bus_type The type of bus to watch a name on.
+ * @param name The name (well-known or unique) to watch.
+ * @param flags Flags from the BusNameWatcherFlags enumeration.
+ * @param name_appeared_slot Slot to invoke when name is known to exist.
+ * @param name_vanished_slot Slot to invoke when name is known to not
+ * exist.
+ * @return An identifier (never 0) that can be used with unwatch_name() to
+ * stop watching the name.
+ *
+ * @newin{2,26}
+ */
+guint watch_name(BusType bus_type, const Glib::ustring& name,
+  BusNameWatcherFlags flags, const SlotNameAppeared& name_appeared_slot,
+  const SlotNameVanished& name_vanished_slot);
+_IGNORE(g_bus_watch_name)
+
+//TODO: Add overloads that don't require all the slots.
+
+/** A watch_name() function that takes a DBusConnection instead of a BusType.
+ *
+ * @param connection A DBusConnection.
+ * @param name The name (well-known or unique) to watch.
+ * @param flags Flags from the BusNameWatcherFlags enumeration.
+ * @param name_appeared_slot Slot to invoke when name is known to exist.
+ * @param name_vanished_slot Slot to invoke when name is known to not
+ * exist.
+ * @return An identifier (never 0) that can be used with unwatch_name() to
+ * stop watching the name.
+ *
+ * @newin{2,26}
+ */
+guint watch_name(const Glib::RefPtr<DBusConnection>& connection,
+  const Glib::ustring& name, BusNameWatcherFlags flags,
+  const SlotNameAppeared& name_appeared_slot,
+  const SlotNameVanished& name_vanished_slot);
+_IGNORE(g_bus_watch_name_on_connection)
+
+//TODO: Add overloads that don't require all the slots.
+
+/** Stops watching a name.
+ * @param watcher_id An identifier obtained from watch_name().
+ */
+void unwatch_name(guint watcher_id);
+_IGNORE(g_bus_unwatch_name)
+}
+
+} // namespace Gio
diff --git a/gio/src/filelist.am b/gio/src/filelist.am
index efbf97a..c55ed26 100644
--- a/gio/src/filelist.am
+++ b/gio/src/filelist.am
@@ -28,6 +28,7 @@ giomm_files_any_hg =			\
 	dbusmethodinvocation.hg \
 	dbusownname.hg \
 	dbusserver.hg \
+	dbuswatchname.hg \
 	drive.hg			\
 	emblem.hg			\
 	emblemedicon.hg			\