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
|
/* 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, see <http://www.gnu.org/licenses/>.
*/
#include <giomm/dbusconnection.h>
_DEFS(giomm,gio)
namespace Gio
{
namespace DBus
{
_WRAP_ENUM(BusNameOwnerFlags, GBusNameOwnerFlags)
/** For example,
* void on_bus_acquired(const Glib::RefPtr<Gio::DBus::Connection>& connection,
* const Glib::ustring& name);
* @newin{2,28}
* @ingroup DBus
*/
using SlotBusAcquired = sigc::slot<void(const Glib::RefPtr<Gio::DBus::Connection>&, Glib::ustring)>;
/** For example,
* void on_name_acquired(const Glib::RefPtr<Gio::DBus::Connection>& connection,
* const Glib::ustring& name);
* @ingroup DBus
*/
using SlotNameAcquired = sigc::slot<void(const Glib::RefPtr<Gio::DBus::Connection>&, Glib::ustring)>;
/** For example,
* void on_name_lost(const Glib::RefPtr<Gio::DBus::Connection>& connection,
* const Glib::ustring& name);
* @ingroup DBus
*/
using SlotNameLost = sigc::slot<void(const Glib::RefPtr<Gio::DBus::Connection>&, Glib::ustring)>;
//TODO: See https://bugzilla.gnome.org/show_bug.cgi?id=646427 about the apparent uselessness of SlotNameAcquired.
//TODO: Add example from C API in class docs.
/** Starts acquiring @a name on the bus specified by @a bus_type and calls @a
* name_acquired_slot and name_@a lost_slot when the name is acquired
* respectively lost. Slots 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 @a name_acquired_slot and @a
* name_lost_slot slots will be invoked after calling this function - there
* are three possible cases:
*
* - @a name_lost_slot with a nullptr connection (if a connection to the bus
* can't be made).
* - @a bus_acquired_slot then @a name_lost_slot (if the name can't be
* obtained)
* - @a bus_acquired_slot then @a name_acquired_slot (if the name was
* obtained).
*
* When you are done owning the name, just call unown_name() with the owner id
* this function returns.
*
* If the name is acquired or lost (for example another application could
* acquire the name if you allow replacement or the application currently
* owning the name exits), the slots are also invoked. If the
* Connection that is used for attempting to own the name closes, then
* @a name_lost_slot is invoked since it is no longer possible for other
* processes to access the process.
*
* You cannot use own_name() several times for the same name (unless
* interleaved with calls to unown_name()) - only the first call will work.
*
* Another guarantee is that invocations of name_@a acquired_slot and
* @a name_lost_slot are guaranteed to alternate; that is, if
* @a name_acquired_slot is invoked then you are guaranteed that the next
* time one of the slots is invoked, it will be @a name_lost_slot. The
* reverse is also true.
*
* If you plan on exporting objects (using e.g.
* Gio::DbusConnection::register_object()), note that it is generally too late
* to export the objects in @a name_acquired_slot. Instead, you can do this
* in @a bus_acquired_slot since you are guaranteed that this will run
* before name is requested from the bus.
*
* This behavior makes it very simple to write applications that wants to own
* names and export objects.
*
* @param bus_type The type of bus to own a name on.
* @param name The well-known name to own.
* @param bus_acquired_slot Slot to invoke when connected to the bus of
* type bus_type.
* @param name_acquired_slot Slot to invoke when name is acquired.
* @param name_lost_slot Slot to invoke when name is lost.
* @param flags A set of flags from the BusNameOwnerFlags enumeration.
* @return An identifier (never 0) that an be used with unown_name() to stop
* owning the name.
*
* @newin{2,28}
* @ingroup DBus
*/
guint own_name(
BusType bus_type,
const Glib::ustring& name,
const SlotBusAcquired& bus_acquired_slot = SlotBusAcquired(),
const SlotNameAcquired& name_acquired_slot = SlotNameAcquired(),
const SlotNameLost& name_lost_slot = SlotNameLost(),
BusNameOwnerFlags flags = Gio::DBus::BusNameOwnerFlags::NONE
);
_IGNORE(g_bus_own_name)
/** Stops owning a name.
* @param owner_id An identifier obtained from own_name().
*/
void unown_name(guint owner_id);
_IGNORE(g_bus_unown_name)
} // namespace DBus
} // namespace Gio
|
