1 /* -*- mode: C; c-file-style: "gnu" -*- */
2 /* dbus-glib.c General GLib binding stuff
3 *
4 * Copyright (C) 2004 Red Hat, Inc.
5 *
6 * SPDX-License-Identifier: AFL-2.1 OR GPL-2.0-or-later
7 *
8 * Licensed under the Academic Free License version 2.1
9 *
10 * This program is free software; you can redistribute it and/or modify
11 * it under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; either version 2 of the License, or
13 * (at your option) any later version.
14 *
15 * This program is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 * GNU General Public License for more details.
19 *
20 * You should have received a copy of the GNU General Public License
21 * along with this program; if not, write to the Free Software
22 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
23 *
24 */
25
26 #include <config.h>
27 #include "dbus/dbus-glib.h"
28 #include "dbus/dbus-glib-lowlevel.h"
29 #include "dbus-gmain/dbus-gmain.h"
30 #include "dbus-gtest.h"
31 #include "dbus-gutils.h"
32 #include "dbus-gvalue.h"
33 #include "dbus-gobject.h"
34 #include <string.h>
35
36 /**
37 * SECTION:dbus-gconnection
38 * @title: DBusGConnection
39 * @short_description: DBus Connection
40 * @see_also: #DBusConnection
41 * @stability: Stable
42 *
43 * A #DBusGConnection is a boxed type abstracting a DBusConnection.
44 *
45 * Deprecated: New code should use #GDBusConnection from the GIO library,
46 * which is not based on libdbus or dbus-glib.
47 */
48
49 /**
50 * DBusGConnection:
51 *
52 * A #DBusGConnection is a boxed type abstracting a DBusConnection from
53 * libdbus.
54 *
55 * Deprecated: New code should use #GDBusConnection from the GIO library,
56 * which is not based on libdbus or dbus-glib.
57 */
58
59 /**
60 * dbus_g_connection_flush:
61 * @connection: the #DBusGConnection to flush
62 *
63 * Blocks until outgoing calls and signal emissions have been sent.
64 *
65 * Deprecated: The closest equivalent in GDBus is
66 * #g_dbus_connection_flush_sync().
67 */
68 void
dbus_g_connection_flush(DBusGConnection * connection)69 dbus_g_connection_flush (DBusGConnection *connection)
70 {
71 dbus_connection_flush (DBUS_CONNECTION_FROM_G_CONNECTION (connection));
72 }
73
74 /**
75 * dbus_g_connection_ref:
76 * @connection: the #DBusGConnection to ref
77 *
78 * Increment refcount on a #DBusGConnection
79 *
80 * Returns: the connection that was ref'd
81 *
82 * Deprecated: New code should use #GDBusConnection instead.
83 */
84 DBusGConnection*
dbus_g_connection_ref(DBusGConnection * connection)85 dbus_g_connection_ref (DBusGConnection *connection)
86 {
87 DBusConnection *c;
88
89 c = DBUS_CONNECTION_FROM_G_CONNECTION (connection);
90 dbus_connection_ref (c);
91 return connection;
92 }
93
94
95 /**
96 * dbus_g_connection_unref:
97 * @connection: the connection to unref
98 *
99 * Decrement refcount on a #DBusGConnection
100 *
101 * Deprecated: New code should use #GDBusConnection instead.
102 */
103 void
dbus_g_connection_unref(DBusGConnection * connection)104 dbus_g_connection_unref (DBusGConnection *connection)
105 {
106 DBusConnection *c;
107
108 c = DBUS_CONNECTION_FROM_G_CONNECTION (connection);
109 dbus_connection_unref (c);
110 }
111
112
113 /**
114 * SECTION:dbus-gmessage
115 * @title: DBusGMessage
116 * @short_description: DBus Message
117 * @see_also: #DBusMessage
118 * @stability: Stable
119 *
120 * A #DBusGMessage is a boxed type abstracting a DBusMessage.
121 *
122 * Deprecated: New code should use #GDBusMessage instead.
123 */
124
125 /**
126 * DBusGMessage:
127 *
128 * A #DBusGMessage is a boxed type abstracting a DBusMessage from
129 * libdbus.
130 *
131 * Deprecated: New code should use #GDBusMessage instead.
132 */
133
134 /**
135 * dbus_g_message_ref:
136 * @message: the message to ref
137 *
138 * Increment refcount on a #DBusGMessage
139 *
140 * Returns: the message that was ref'd
141 *
142 * Deprecated: New code should use #GDBusMessage instead.
143 */
144 DBusGMessage*
dbus_g_message_ref(DBusGMessage * message)145 dbus_g_message_ref (DBusGMessage *message)
146 {
147 DBusMessage *c;
148
149 c = DBUS_MESSAGE_FROM_G_MESSAGE (message);
150 dbus_message_ref (c);
151 return message;
152 }
153
154 /**
155 * dbus_g_message_unref:
156 * @message: the message to unref
157 *
158 * Decrement refcount on a #DBusGMessage
159 *
160 * Deprecated: New code should use #GDBusMessage instead.
161 */
162 void
dbus_g_message_unref(DBusGMessage * message)163 dbus_g_message_unref (DBusGMessage *message)
164 {
165 DBusMessage *c;
166
167 c = DBUS_MESSAGE_FROM_G_MESSAGE (message);
168 dbus_message_unref (c);
169 }
170
171 /**
172 * SECTION:dbus-gerror
173 * @title: DBusGError
174 * @short_description: DBus GError
175 * @see_also: #GError
176 * @stability: Stable
177 *
178 * #DBusGError is the #GError used by DBus.
179 *
180 * Deprecated: New code should use GDBus and its #GDBusError enum instead.
181 */
182
183 /**
184 * DBusGError:
185 *
186 * A #GError enumeration for the domain %DBUS_GERROR. The values' meanings
187 * can be found by looking at the comments for the corresponding constants
188 * in dbus-protocol.h.
189 *
190 * Deprecated: New code should use GDBus and its #GDBusError enum instead.
191 */
192
193 /**
194 * DBUS_GERROR:
195 *
196 * Expands to a function call returning the error domain quark for #DBusGError,
197 * for use with #GError.
198 *
199 * Deprecated: New code should use GDBus and its #GDBusError enum instead.
200 */
201 GQuark
dbus_g_error_quark(void)202 dbus_g_error_quark (void)
203 {
204 static GQuark quark = 0;
205 if (quark == 0)
206 quark = g_quark_from_static_string ("dbus-glib-error-quark");
207 return quark;
208 }
209
210 /**
211 * dbus_g_error_has_name:
212 * @error: the GError given from the remote method
213 * @name: the D-BUS error name
214 *
215 * Determine whether D-BUS error name for a remote exception matches
216 * the given name. This function is intended to be invoked on a
217 * #GError returned from an invocation of a remote method, e.g. via
218 * dbus_g_proxy_end_call(). It will silently return %FALSE for errors
219 * which are not remote D-BUS exceptions (i.e. with a domain other
220 * than %DBUS_GERROR or a code other than
221 * %DBUS_GERROR_REMOTE_EXCEPTION).
222 *
223 * Returns: %TRUE if and only if the remote error has the given name
224 *
225 * Deprecated: New code should use GDBus instead. The closest equivalent
226 * is g_dbus_error_get_remote_error().
227 */
228 gboolean
dbus_g_error_has_name(GError * error,const char * name)229 dbus_g_error_has_name (GError *error, const char *name)
230 {
231 g_return_val_if_fail (error != NULL, FALSE);
232
233 if (error->domain != DBUS_GERROR
234 || error->code != DBUS_GERROR_REMOTE_EXCEPTION)
235 return FALSE;
236
237 return !strcmp (dbus_g_error_get_name (error), name);
238 }
239
240 /**
241 * dbus_g_error_get_name:
242 * @error: the #GError given from the remote method
243 *
244 * This function may only be invoked on a #GError returned from an
245 * invocation of a remote method, e.g. via dbus_g_proxy_end_call().
246 * Moreover, you must ensure that the error's domain is %DBUS_GERROR,
247 * and the code is %DBUS_GERROR_REMOTE_EXCEPTION.
248 *
249 * Returns: the D-BUS name for a remote exception.
250 *
251 * Deprecated: New code should use GDBus instead. The closest equivalent
252 * is g_dbus_error_get_remote_error().
253 */
254 const char *
dbus_g_error_get_name(GError * error)255 dbus_g_error_get_name (GError *error)
256 {
257 g_return_val_if_fail (error != NULL, NULL);
258 g_return_val_if_fail (error->domain == DBUS_GERROR, NULL);
259 g_return_val_if_fail (error->code == DBUS_GERROR_REMOTE_EXCEPTION, NULL);
260
261 return error->message + strlen (error->message) + 1;
262 }
263
264 /**
265 * DBUS_TYPE_CONNECTION:
266 *
267 * Expands to a function call returning a boxed #GType representing a
268 * #DBusConnection pointer from libdbus. Not to be confused with
269 * %DBUS_TYPE_G_CONNECTION, which you should usually use instead.
270 *
271 * Returns: the GLib type
272 *
273 * Deprecated: New code should use GDBus instead.
274 */
275 GType
dbus_connection_get_g_type(void)276 dbus_connection_get_g_type (void)
277 {
278 static GType our_type = 0;
279
280 if (our_type == 0)
281 our_type = g_boxed_type_register_static ("DBusConnection",
282 (GBoxedCopyFunc) dbus_connection_ref,
283 (GBoxedFreeFunc) dbus_connection_unref);
284
285 return our_type;
286 }
287
288 /**
289 * DBUS_TYPE_MESSAGE:
290 *
291 * Expands to a function call returning a boxed #GType representing a
292 * #DBusMessage pointer from libdbus. Not to be confused with
293 * %DBUS_TYPE_G_MESSAGE, which you should usually use instead.
294 *
295 *
296 * Returns: the GLib type
297 *
298 * Deprecated: New code should use GDBus instead.
299 */
300 GType
dbus_message_get_g_type(void)301 dbus_message_get_g_type (void)
302 {
303 static GType our_type = 0;
304
305 if (our_type == 0)
306 our_type = g_boxed_type_register_static ("DBusMessage",
307 (GBoxedCopyFunc) dbus_message_ref,
308 (GBoxedFreeFunc) dbus_message_unref);
309
310 return our_type;
311 }
312
313 /**
314 * DBUS_TYPE_G_CONNECTION:
315 *
316 * Expands to a function call returning the boxed #GType of a #DBusGConnection.
317 *
318 * Returns: the GLib type
319 *
320 * Deprecated: New code should use GDBus instead.
321 */
322 GType
dbus_g_connection_get_g_type(void)323 dbus_g_connection_get_g_type (void)
324 {
325 static GType our_type = 0;
326
327 if (our_type == 0)
328 our_type = g_boxed_type_register_static ("DBusGConnection",
329 (GBoxedCopyFunc) dbus_g_connection_ref,
330 (GBoxedFreeFunc) dbus_g_connection_unref);
331
332 return our_type;
333 }
334
335 /**
336 * DBUS_TYPE_G_MESSAGE:
337 *
338 * Expands to a function call returning the boxed #GType of a #DBusGConnection.
339 *
340 * Returns: the GLib type
341 *
342 * Deprecated: New code should use GDBus instead.
343 */
344 GType
dbus_g_message_get_g_type(void)345 dbus_g_message_get_g_type (void)
346 {
347 static GType our_type = 0;
348
349 if (our_type == 0)
350 our_type = g_boxed_type_register_static ("DBusGMessage",
351 (GBoxedCopyFunc) dbus_g_message_ref,
352 (GBoxedFreeFunc) dbus_g_message_unref);
353
354 return our_type;
355 }
356
357 /**
358 * SECTION:dbus-glib-lowlevel
359 * @title: DBus GLib low level
360 * @short_description: DBus lower level functions
361 * @stability: Unstable
362 *
363 * These functions can be used to access lower level of DBus.
364 *
365 * Deprecated: New code should use GDBus instead.
366 */
367
368 /**
369 * dbus_g_connection_get_connection:
370 * @gconnection: a #DBusGConnection
371 *
372 * Get the #DBusConnection corresponding to this #DBusGConnection.
373 * The return value does not have its refcount incremented.
374 *
375 * Returns: #DBusConnection
376 *
377 * Deprecated: New code should use GDBus instead.
378 */
379 DBusConnection*
dbus_g_connection_get_connection(DBusGConnection * gconnection)380 dbus_g_connection_get_connection (DBusGConnection *gconnection)
381 {
382 g_return_val_if_fail (gconnection, NULL);
383 return DBUS_CONNECTION_FROM_G_CONNECTION (gconnection);
384 }
385
386 extern dbus_int32_t _dbus_gmain_connection_slot;
387
388 /**
389 * dbus_connection_get_g_connection:
390 * @connection: a #DBusConnection
391 *
392 * Get the #DBusGConnection corresponding to this #DBusConnection. This only
393 * makes sense if the #DBusConnection was originally a #DBusGConnection that was
394 * registered with the GLib main loop. The return value does not have its
395 * refcount incremented.
396 *
397 * Returns: #DBusGConnection
398 *
399 * Deprecated: New code should use GDBus instead.
400 */
401 DBusGConnection*
dbus_connection_get_g_connection(DBusConnection * connection)402 dbus_connection_get_g_connection (DBusConnection *connection)
403 {
404 g_return_val_if_fail (connection, NULL);
405 g_return_val_if_fail (dbus_connection_get_data (connection, _dbus_gmain_connection_slot), NULL);
406
407 return DBUS_G_CONNECTION_FROM_CONNECTION (connection);
408 }
409
410
411 /**
412 * dbus_g_message_get_message:
413 * @gmessage: a #DBusGMessage
414 *
415 * Get the #DBusMessage corresponding to this #DBusGMessage.
416 * The return value does not have its refcount incremented.
417 *
418 * Returns: #DBusMessage
419 *
420 * Deprecated: New code should use GDBus instead.
421 */
422 DBusMessage*
dbus_g_message_get_message(DBusGMessage * gmessage)423 dbus_g_message_get_message (DBusGMessage *gmessage)
424 {
425 return DBUS_MESSAGE_FROM_G_MESSAGE (gmessage);
426 }
427
428 /**
429 * dbus_g_connection_open:
430 * @address: address of the connection to open
431 * @error: address where an error can be returned.
432 *
433 * Returns a connection to the given address.
434 *
435 * (Internally, calls dbus_connection_open() then calls
436 * dbus_connection_setup_with_g_main() on the result.)
437 *
438 * Returns: a DBusConnection
439 *
440 * Deprecated: New code should use GDBus instead. The closest equivalent
441 * is g_dbus_connection_new_for_address_sync().
442 */
443 DBusGConnection*
dbus_g_connection_open(const gchar * address,GError ** error)444 dbus_g_connection_open (const gchar *address,
445 GError **error)
446 {
447 DBusConnection *connection;
448 DBusError derror;
449
450 g_return_val_if_fail (error == NULL || *error == NULL, NULL);
451
452 _dbus_g_value_types_init ();
453
454 dbus_error_init (&derror);
455
456 connection = dbus_connection_open (address, &derror);
457 if (connection == NULL)
458 {
459 dbus_set_g_error (error, &derror);
460 dbus_error_free (&derror);
461 return NULL;
462 }
463
464 /* does nothing if it's already been done */
465 dbus_connection_setup_with_g_main (connection, NULL);
466
467 return DBUS_G_CONNECTION_FROM_CONNECTION (connection);
468 }
469
470 /**
471 * dbus_g_connection_open_private:
472 * @address: address of the connection to open
473 * @context: the #GMainContext or %NULL for default context
474 * @error: address where an error can be returned.
475 *
476 * Returns a private connection to the given address; this
477 * connection does not talk to a bus daemon and thus the caller
478 * must set up any authentication by itself. If the address
479 * refers to a message bus, the caller must call dbus_bus_register().
480 *
481 * (Internally, calls dbus_connection_open_private() then calls
482 * dbus_connection_setup_with_g_main() on the result.)
483 *
484 * Returns: (transfer full): a #DBusGConnection
485 *
486 * Deprecated: New code should use GDBus instead. The closest equivalent
487 * is g_dbus_connection_new_for_address_sync().
488 */
489 DBusGConnection *
dbus_g_connection_open_private(const gchar * address,GMainContext * context,GError ** error)490 dbus_g_connection_open_private (const gchar *address,
491 GMainContext *context,
492 GError **error)
493 {
494 DBusConnection *connection;
495 DBusError derror;
496
497 g_return_val_if_fail (error == NULL || *error == NULL, NULL);
498
499 _dbus_g_value_types_init ();
500
501 dbus_error_init (&derror);
502
503 connection = dbus_connection_open_private (address, &derror);
504 if (connection == NULL)
505 {
506 dbus_set_g_error (error, &derror);
507 dbus_error_free (&derror);
508 return NULL;
509 }
510
511 dbus_connection_setup_with_g_main (connection, context);
512
513 return DBUS_G_CONNECTION_FROM_CONNECTION (connection);
514 }
515
516 /**
517 * dbus_g_bus_get:
518 * @type: bus type
519 * @error: address where an error can be returned.
520 *
521 * Returns a connection to the given bus. The connection is a global variable
522 * shared with other callers of this function.
523 *
524 * (Internally, calls dbus_bus_get() then calls
525 * dbus_connection_setup_with_g_main() on the result.)
526 *
527 * Returns: a DBusConnection
528 *
529 * Deprecated: New code should use GDBus instead. The closest equivalent
530 * is g_bus_get_sync().
531 */
532 DBusGConnection*
dbus_g_bus_get(DBusBusType type,GError ** error)533 dbus_g_bus_get (DBusBusType type,
534 GError **error)
535 {
536 DBusConnection *connection;
537 DBusError derror;
538
539 g_return_val_if_fail (error == NULL || *error == NULL, NULL);
540
541 _dbus_g_value_types_init ();
542
543 dbus_error_init (&derror);
544
545 connection = dbus_bus_get (type, &derror);
546 if (connection == NULL)
547 {
548 dbus_set_g_error (error, &derror);
549 dbus_error_free (&derror);
550 return NULL;
551 }
552
553 /* does nothing if it's already been done */
554 dbus_connection_setup_with_g_main (connection, NULL);
555
556 return DBUS_G_CONNECTION_FROM_CONNECTION (connection);
557 }
558
559 /**
560 * dbus_g_bus_get_private:
561 * @type: bus type
562 * @context: Mainloop context to attach to
563 * @error: address where an error can be returned.
564 *
565 * Returns a connection to the given bus. The connection will be a private
566 * non-shared connection and should be closed when usage is complete.
567 *
568 * Internally this function calls dbus_bus_get_private() then calls
569 * dbus_connection_setup_with_g_main() on the result; see the documentation
570 * of the former function for more information on private connections.
571 *
572 * Returns: a DBusConnection
573 *
574 * Deprecated: New code should use GDBus instead. The closest equivalent
575 * is g_bus_get_sync().
576 */
577 DBusGConnection*
dbus_g_bus_get_private(DBusBusType type,GMainContext * context,GError ** error)578 dbus_g_bus_get_private (DBusBusType type,
579 GMainContext *context,
580 GError **error)
581 {
582 DBusConnection *connection;
583 DBusError derror;
584
585 g_return_val_if_fail (error == NULL || *error == NULL, NULL);
586
587 _dbus_g_value_types_init ();
588
589 dbus_error_init (&derror);
590
591 connection = dbus_bus_get_private (type, &derror);
592 if (connection == NULL)
593 {
594 dbus_set_g_error (error, &derror);
595 dbus_error_free (&derror);
596 return NULL;
597 }
598
599 /* does nothing if it's already been done */
600 dbus_connection_setup_with_g_main (connection, context);
601
602 return DBUS_G_CONNECTION_FROM_CONNECTION (connection);
603 }
604
605 /**
606 * dbus_connection_setup_with_g_main:
607 * @connection: the connection
608 * @context: the #GMainContext or %NULL for default context
609 *
610 * Sets the watch and timeout functions of a #DBusConnection
611 * to integrate the connection with the GLib main loop.
612 * Pass in %NULL for the #GMainContext unless you're
613 * doing something specialized.
614 *
615 * If called twice for the same context, does nothing the second
616 * time. If called once with context A and once with context B,
617 * context B replaces context A as the context monitoring the
618 * connection.
619 *
620 * Deprecated: New code should use GDBus instead.
621 * Modules that need to connect `libdbus` to a GLib main loop should
622 * use the dbus-gmain submodule via `git subtree` or `git submodule`.
623 */
624 void
dbus_connection_setup_with_g_main(DBusConnection * connection,GMainContext * context)625 dbus_connection_setup_with_g_main (DBusConnection *connection,
626 GMainContext *context)
627 {
628 _dbus_g_set_up_connection (connection, context);
629 }
630
631 /**
632 * dbus_server_setup_with_g_main:
633 * @server: the server
634 * @context: the #GMainContext or %NULL for default
635 *
636 * Sets the watch and timeout functions of a #DBusServer
637 * to integrate the server with the GLib main loop.
638 * In most cases the context argument should be %NULL.
639 *
640 * If called twice for the same context, does nothing the second
641 * time. If called once with context A and once with context B,
642 * context B replaces context A as the context monitoring the
643 * connection.
644 *
645 * Deprecated: New code should use GDBus instead.
646 * Modules that need to connect `libdbus` to a GLib main loop should
647 * use the dbus-gmain submodule via `git subtree` or `git submodule`.
648 */
649 void
dbus_server_setup_with_g_main(DBusServer * server,GMainContext * context)650 dbus_server_setup_with_g_main (DBusServer *server,
651 GMainContext *context)
652 {
653 _dbus_g_set_up_server (server, context);
654 }
655