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