1// -*- Mode: C++; indent-tabs-mode: nil; c-basic-offset: 2 -*- 2 3/* Copyright (C) 2010 The giomm Development Team 4 * 5 * This library is free software; you can redistribute it and/or 6 * modify it under the terms of the GNU Lesser General Public 7 * License as published by the Free Software Foundation; either 8 * version 2.1 of the License, or (at your option) any later version. 9 * 10 * This library is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 * Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public 16 * License along with this library. If not, see <http://www.gnu.org/licenses/>. 17 */ 18 19#include <giomm/dbusconnection.h> 20 21_DEFS(giomm,gio) 22 23namespace Gio 24{ 25 26namespace DBus 27{ 28 29_WRAP_ENUM(BusNameWatcherFlags, GBusNameWatcherFlags, s#^DBUS_##, NO_GTYPE) 30 31/** For example, 32 * void on_name_appeared(const Glib::RefPtr<Gio::DBus::Connection>& connection, 33 * const Glib::ustring& name, const Glib::ustring& name_owner); 34 * @ingroup DBus 35 */ 36using SlotNameAppeared = sigc::slot<void, const Glib::RefPtr<Gio::DBus::Connection>&, Glib::ustring, const Glib::ustring&>; 37 38/** For example, 39 * void on_name_vanished(const Glib::RefPtr<Gio::DBus::Connection>& connection, 40 * const Glib::ustring& name); 41 * @ingroup DBus 42 */ 43using SlotNameVanished = sigc::slot<void, const Glib::RefPtr<Gio::DBus::Connection>&, Glib::ustring>; 44 45//TODO: Add example from C API in class docs? 46/** Starts watching @a name on the bus specified by @a bus_type and calls 47 * @a name_appeared_slot and @a name_vanished_slot when the name is 48 * known to have a owner respectively known to lose its owner. Callbacks will 49 * be invoked in the thread-default main loop of the thread you are calling 50 * this function from. 51 * 52 * You are guaranteed that one of the slot will be invoked after calling 53 * this function. When you are done watching the name, just call 54 * unwatch_name() with the watcher id this function returns. 55 * 56 * If the name vanishes or appears (for example the application owning the 57 * name could restart), the slot are also invoked. If the Connection 58 * that is used for watching the name disconnects, then @a 59 * name_vanished_slot is invoked since it is no longer possible to access 60 * the name. 61 * 62 * Another guarantee is that invocations of @a name_appeared_slot and @a 63 * name_vanished_slot are guaranteed to alternate; that is, if 64 * @a name_appeared_slot is invoked then you are guaranteed that the next 65 * time one of the slot is invoked, it will be @a name_vanished_slot. 66 * The reverse is also true. 67 * 68 * This behavior makes it very simple to write applications that wants to take 69 * action when a certain name exists, see the C API's Example 9, “Simple 70 * application watching a name” for more information. Basically, the 71 * application should create object proxies in @a name_appeared_slot and 72 * destroy them again (if any) in @a name_vanished_slot. 73 * 74 * @param bus_type The type of bus to watch a name on. 75 * @param name The name (well-known or unique) to watch. 76 * @param name_appeared_slot Slot to invoke when name is known to exist. 77 * @param name_vanished_slot Slot to invoke when name is known to not 78 * exist. 79 * @param flags Flags from the BusNameWatcherFlags enumeration. 80 * @return An identifier (never 0) that can be used with unwatch_name() to 81 * stop watching the name. 82 * 83 * @newin{2,28} 84 * @ingroup DBus 85 */ 86GIOMM_API 87guint watch_name( 88 BusType bus_type, 89 const Glib::ustring& name, 90 const SlotNameAppeared& name_appeared_slot = SlotNameAppeared(), 91 const SlotNameVanished& name_vanished_slot = SlotNameVanished(), 92 BusNameWatcherFlags flags = Gio::DBus::BUS_NAME_WATCHER_FLAGS_NONE 93); 94_IGNORE(g_bus_watch_name) 95 96/** A watch_name() function that takes a Connection instead of a BusType. 97 * 98 * @param connection A Connection. 99 * @param name The name (well-known or unique) to watch. 100 * @param name_appeared_slot Slot to invoke when name is known to exist. 101 * @param name_vanished_slot Slot to invoke when name is known to not 102 * exist. 103 * @param flags Flags from the BusNameWatcherFlags enumeration. 104 * @return An identifier (never 0) that can be used with unwatch_name() to 105 * stop watching the name. 106 * 107 * @newin{2,28} 108 * @ingroup DBus 109 */ 110GIOMM_API 111guint watch_name( 112 const Glib::RefPtr<Connection>& connection, 113 const Glib::ustring& name, 114 const SlotNameAppeared& name_appeared_slot = SlotNameAppeared(), 115 const SlotNameVanished& name_vanished_slot = SlotNameVanished(), 116 BusNameWatcherFlags flags = Gio::DBus::BUS_NAME_WATCHER_FLAGS_NONE 117); 118_IGNORE(g_bus_watch_name_on_connection) 119 120/** Stops watching a name. 121 * @param watcher_id An identifier obtained from watch_name(). 122 * @ingroup DBus 123 */ 124GIOMM_API 125void unwatch_name(guint watcher_id); 126_IGNORE(g_bus_unwatch_name) 127 128} // namespace DBus 129 130} // namespace Gio 131