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
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
|
<chapter>
<title>Migrating from dbus-glib to GDBus</title>
<section>
<title>Conceptual differences</title>
<para>
The central concepts of D-Bus are modelled in a very similar way
in dbus-glib and GDBus. Both have a objects representing connections,
proxies and method invocations. But there are some important
differences:
<itemizedlist>
<listitem><para>
dbus-glib uses libdbus, GDBus doesn't. Instead, it relies on GIO
streams as transport layer, and has its own implementation for the
the D-Bus connection setup and authentication. Apart from using
streams as transport, avoiding libdbus also lets GDBus avoid some
thorny multithreading issues.
</para></listitem>
<listitem><para>
dbus-glib uses the GObject type system for method arguments and
return values, including a homegrown container specialization
mechanism. GDBus relies uses the #GVariant type system which is
explicitly designed to match D-Bus types.
</para></listitem>
<listitem><para>
The typical way to export an object in dbus-glib involves generating
glue code from XML introspection data using <command>dbus-binding-tool</command>. GDBus does not (yet?) use code generation; you are expected to
embed the introspection data in your application code.
</para></listitem>
</itemizedlist>
</para>
</section>
<section>
<title>API comparison</title>
<table id="dbus-glib-vs-gdbus">
<title>dbus-glib APIs and their GDBus counterparts</title>
<tgroup cols="2">
<thead>
<row><entry>dbus-glib</entry><entry>GDBus</entry></row>
</thead>
<tbody>
<row><entry>#DBusGConnection</entry><entry>#GDBusConnection</entry></row>
<row><entry>#DBusGProxy</entry><entry>#GDBusProxy</entry></row>
<row><entry>#DBusGMethodInvocation</entry><entry>#GDBusMethodInvocation</entry></row>
<row><entry>dbus_g_bus_get()</entry><entry>g_bus_get_sync(), also see
g_bus_get()</entry></row>
<row><entry>dbus_g_proxy_new_for_name()</entry><entry>g_dbus_proxy_new_sync(), also see
g_dbus_proxy_new()</entry></row>
<row><entry>dbus_g_proxy_add_signal()</entry><entry>not needed, use the generic #GDBusProxy::g-signal</entry></row>
<row><entry>dbus_g_proxy_connect_signal()</entry><entry>use g_signal_connect() with #GDBusProxy::g-signal</entry></row>
<row><entry>dbus_g_connection_register_g_object()</entry><entry>g_dbus_connection_register_object()</entry></row>
<row><entry>dbus_g_connection_unregister_g_object()</entry><entry>g_dbus_connection_unregister_object()</entry></row>
<row><entry>dbus_g_object_type_install_info()</entry><entry>introspection data is installed while registering
an object, see g_dbus_connection_register_object()</entry></row>
<row><entry>dbus_g_proxy_begin_call()</entry><entry>g_dbus_proxy_call()</entry></row>
<row><entry>dbus_g_proxy_end_call()</entry><entry>g_dbus_proxy_call_finish()</entry></row>
<row><entry>dbus_g_proxy_call()</entry><entry>g_dbus_proxy_call_sync()</entry></row>
<row><entry>dbus_g_error_domain_register()</entry><entry>g_dbus_error_register_error_domain()</entry></row>
<row><entry>dbus_g_error_has_name()</entry><entry>no direct equivalent, see g_dbus_error_get_remote_error()</entry></row>
<row><entry>dbus_g_method_return()</entry><entry>g_dbus_method_invocation_return_value()</entry></row>
<row><entry>dbus_g_method_return_error()</entry><entry>g_dbus_method_invocation_return_error() and variants</entry></row>
<row><entry>dbus_g_method_get_sender()</entry><entry>g_dbus_method_invocation_get_sender()</entry></row>
</tbody>
</tgroup>
</table>
</section>
<section>
<title>Owning bus names</title>
<para>
Using dbus-glib, you typically call RequestName manually
to own a name, like in the following excerpt:
<informalexample><programlisting><![CDATA[
error = NULL;
res = dbus_g_proxy_call (system_bus_proxy,
"RequestName",
&error,
G_TYPE_STRING, NAME_TO_CLAIM,
G_TYPE_UINT, DBUS_NAME_FLAG_ALLOW_REPLACEMENT,
G_TYPE_INVALID,
G_TYPE_UINT, &result,
G_TYPE_INVALID);
if (!res)
{
if (error != NULL)
{
g_warning ("Failed to acquire %s: %s",
NAME_TO_CLAIM, error->message);
g_error_free (error);
}
else
{
g_warning ("Failed to acquire %s", NAME_TO_CLAIM);
}
goto out;
}
if (result != DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER)
{
if (error != NULL)
{
g_warning ("Failed to acquire %s: %s",
NAME_TO_CLAIM, error->message);
g_error_free (error);
}
else
{
g_warning ("Failed to acquire %s", NAME_TO_CLAIM);
}
exit (1);
}
dbus_g_proxy_add_signal (system_bus_proxy, "NameLost",
G_TYPE_STRING, G_TYPE_INVALID);
dbus_g_proxy_connect_signal (system_bus_proxy, "NameLost",
G_CALLBACK (on_name_lost), NULL, NULL);
/* further setup ... */
]]>
</programlisting></informalexample>
</para>
<para>
While you can do things this way with GDBus too, using
g_dbus_proxy_call_sync(), it is much nicer to use the high-level API
for this:
<informalexample><programlisting><![CDATA[
static void
on_name_acquired (GDBusConnection *connection,
const gchar *name,
gpointer user_data)
{
/* further setup ... */
}
/* ... */
owner_id = g_bus_own_name (G_BUS_TYPE_SYSTEM,
NAME_TO_CLAIM,
G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT,
on_bus_acquired,
on_name_acquired,
on_name_lost,
NULL,
NULL);
g_main_loop_run (loop);
g_bus_unown_name (owner_id);
]]>
</programlisting></informalexample>
Note that g_bus_own_name() works asynchronously and requires
you to enter your mainloop to await the on_name_aquired()
callback. Also note that in order to avoid race conditions (e.g.
when your service is activated by a method call), you have to export
your manager object <emphasis>before</emphasis> acquiring the
name. The on_bus_acquired() callback is the right place to do
such preparations.
</para>
</section>
<section>
<title>Creating proxies for well-known names</title>
<para>
dbus-glib lets you create proxy objects for well-known names, like the
following example:
<informalexample><programlisting><![CDATA[
proxy = dbus_g_proxy_new_for_name (system_bus_connection,
"org.freedesktop.Accounts",
"/org/freedesktop/Accounts",
"org.freedesktop.Accounts");
]]>
</programlisting></informalexample>
For a #DBusGProxy constructed like this, method calls will be sent to
the current owner of the name, and that owner can change over time.
</para>
<para>
In contrast, #GDBusProxy instances are always bound to a unique name.
To get a proxy for a well-known name, you either have to call
GetNameOwner yourself and construct a proxy for the unique name
of the current name owner, or use the high-level API. The latter
option is highly recommended:
<informalexample><programlisting><![CDATA[
static void
on_proxy_appeared (GDBusConnection *connection,
const gchar *name,
const gchar *name_owner,
GDBusProxy *proxy,
gpointer user_data)
{
/* start to use proxy */
}
/* ... */
watcher_id = g_bus_watch_proxy (G_BUS_TYPE_SYSTEM,
"org.freedesktop.Accounts",
G_BUS_NAME_WATCHER_FLAGS_NONE,
"/org/freedesktop/Accounts",
"org.freedesktop.Accounts",
G_TYPE_DBUS_PROXY,
G_BUS_PROXY_FLAGS_NONE,
on_proxy_appeared,
on_proxy_vanished,
NULL,
NULL);
g_main_loop_run (loop);
g_bus_unwatch_proxy (watcher_id);
]]>
</programlisting></informalexample>
Like g_bus_own_name(), g_bus_watch_proxy() is asynchronous and
you are expected to enter your mainloop to await the on_proxy_appeared()
callback. Note that GDBus also does all the setup operations for the
proxy asynchronously, and only calls your callback when the proxy
is ready for use.
</para>
</section>
</chapter>
|
