1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
|
// -*- 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, s#^DBUS_##, NO_GTYPE)
/** For example,
* void on_name_appeared(const Glib::RefPtr<Gio::DBus::Connection>& connection,
* const Glib::ustring& name, const Glib::ustring& name_owner);
* @ingroup DBus
*/
typedef sigc::slot<void, const Glib::RefPtr<Gio::DBus::Connection>&, Glib::ustring, const Glib::ustring&> SlotNameAppeared;
/** For example,
* void on_name_vanished(const Glib::RefPtr<Gio::DBus::Connection>& connection,
* const Glib::ustring& name);
* @ingroup DBus
*/
typedef sigc::slot<void, const Glib::RefPtr<Gio::DBus::Connection>&, 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 Connection
* 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 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.
* @param flags Flags from the BusNameWatcherFlags enumeration.
* @return An identifier (never 0) that can be used with unwatch_name() to
* stop watching the name.
*
* @newin{2,28}
* @ingroup DBus
*/
guint watch_name(
BusType bus_type,
const Glib::ustring& name,
const SlotNameAppeared& name_appeared_slot = SlotNameAppeared(),
const SlotNameVanished& name_vanished_slot = SlotNameVanished(),
BusNameWatcherFlags flags = Gio::DBus::BUS_NAME_WATCHER_FLAGS_NONE
);
_IGNORE(g_bus_watch_name)
/** A watch_name() function that takes a Connection instead of a BusType.
*
* @param connection A Connection.
* @param name The name (well-known or unique) to watch.
* @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.
* @param flags Flags from the BusNameWatcherFlags enumeration.
* @return An identifier (never 0) that can be used with unwatch_name() to
* stop watching the name.
*
* @newin{2,28}
* @ingroup DBus
*/
guint watch_name(
const Glib::RefPtr<Connection>& connection,
const Glib::ustring& name,
const SlotNameAppeared& name_appeared_slot = SlotNameAppeared(),
const SlotNameVanished& name_vanished_slot = SlotNameVanished(),
BusNameWatcherFlags flags = Gio::DBus::BUS_NAME_WATCHER_FLAGS_NONE
);
_IGNORE(g_bus_watch_name_on_connection)
/** Stops watching a name.
* @param watcher_id An identifier obtained from watch_name().
* @ingroup DBus
*/
void unwatch_name(guint watcher_id);
_IGNORE(g_bus_unwatch_name)
} // namespace DBus
} // namespace Gio
|
