1 /* GDBus - GLib D-Bus Library
3 * Copyright (C) 2008-2010 Red Hat, Inc.
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.
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.
15 * You should have received a copy of the GNU Lesser General
16 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
18 * Author: David Zeuthen <davidz@redhat.com>
26 #include "gdbusutils.h"
27 #include "gdbusnamewatching.h"
28 #include "gdbuserror.h"
29 #include "gdbusprivate.h"
30 #include "gdbusconnection.h"
35 * SECTION:gdbusnamewatching
36 * @title: Watching Bus Names
37 * @short_description: Simple API for watching bus names
40 * Convenience API for watching bus names.
42 * A simple example for watching a name can be found in
43 * [gdbus-example-watch-name.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-watch-name.c)
46 G_LOCK_DEFINE_STATIC (lock);
48 /* ---------------------------------------------------------------------------------------------------- */
52 PREVIOUS_CALL_NONE = 0,
53 PREVIOUS_CALL_APPEARED,
54 PREVIOUS_CALL_VANISHED,
59 volatile gint ref_count;
62 GBusNameWatcherFlags flags;
64 GBusNameAppearedCallback name_appeared_handler;
65 GBusNameVanishedCallback name_vanished_handler;
67 GDestroyNotify user_data_free_func;
68 GMainContext *main_context;
70 GDBusConnection *connection;
71 gulong disconnected_signal_handler_id;
72 guint name_owner_changed_subscription_id;
74 PreviousCall previous_call;
80 /* Must be accessed atomically. */
81 static volatile guint next_global_id = 1;
83 /* Must be accessed with @lock held. */
84 static GHashTable *map_id_to_client = NULL;
87 client_ref (Client *client)
89 g_atomic_int_inc (&client->ref_count);
94 client_unref (Client *client)
96 if (g_atomic_int_dec_and_test (&client->ref_count))
98 if (client->connection != NULL)
100 if (client->name_owner_changed_subscription_id > 0)
101 g_dbus_connection_signal_unsubscribe (client->connection, client->name_owner_changed_subscription_id);
102 if (client->disconnected_signal_handler_id > 0)
103 g_signal_handler_disconnect (client->connection, client->disconnected_signal_handler_id);
104 g_object_unref (client->connection);
106 g_free (client->name);
107 g_free (client->name_owner);
108 g_main_context_unref (client->main_context);
109 if (client->user_data_free_func != NULL)
110 client->user_data_free_func (client->user_data);
115 /* ---------------------------------------------------------------------------------------------------- */
119 CALL_TYPE_NAME_APPEARED,
120 CALL_TYPE_NAME_VANISHED
127 /* keep this separate because client->connection may
128 * be set to NULL after scheduling the call
130 GDBusConnection *connection;
139 call_handler_data_free (CallHandlerData *data)
141 if (data->connection != NULL)
142 g_object_unref (data->connection);
143 g_free (data->name_owner);
144 client_unref (data->client);
149 actually_do_call (Client *client, GDBusConnection *connection, const gchar *name_owner, CallType call_type)
153 case CALL_TYPE_NAME_APPEARED:
154 if (client->name_appeared_handler != NULL)
156 client->name_appeared_handler (connection,
163 case CALL_TYPE_NAME_VANISHED:
164 if (client->name_vanished_handler != NULL)
166 client->name_vanished_handler (connection,
173 g_assert_not_reached ();
179 call_in_idle_cb (gpointer _data)
181 CallHandlerData *data = _data;
182 actually_do_call (data->client, data->connection, data->name_owner, data->call_type);
187 schedule_call_in_idle (Client *client, CallType call_type)
189 CallHandlerData *data;
190 GSource *idle_source;
192 data = g_new0 (CallHandlerData, 1);
193 data->client = client_ref (client);
194 data->connection = client->connection != NULL ? g_object_ref (client->connection) : NULL;
195 data->name_owner = g_strdup (client->name_owner);
196 data->call_type = call_type;
198 idle_source = g_idle_source_new ();
199 g_source_set_priority (idle_source, G_PRIORITY_HIGH);
200 g_source_set_callback (idle_source,
203 (GDestroyNotify) call_handler_data_free);
204 g_source_set_name (idle_source, "[gio] call_in_idle_cb");
205 g_source_attach (idle_source, client->main_context);
206 g_source_unref (idle_source);
210 do_call (Client *client, CallType call_type)
212 GMainContext *current_context;
214 /* only schedule in idle if we're not in the right thread */
215 current_context = g_main_context_ref_thread_default ();
216 if (current_context != client->main_context)
217 schedule_call_in_idle (client, call_type);
219 actually_do_call (client, client->connection, client->name_owner, call_type);
220 g_main_context_unref (current_context);
224 call_appeared_handler (Client *client)
226 if (client->previous_call != PREVIOUS_CALL_APPEARED)
228 client->previous_call = PREVIOUS_CALL_APPEARED;
229 if (!client->cancelled && client->name_appeared_handler != NULL)
231 do_call (client, CALL_TYPE_NAME_APPEARED);
237 call_vanished_handler (Client *client,
238 gboolean ignore_cancelled)
240 if (client->previous_call != PREVIOUS_CALL_VANISHED)
242 client->previous_call = PREVIOUS_CALL_VANISHED;
243 if (((!client->cancelled) || ignore_cancelled) && client->name_vanished_handler != NULL)
245 do_call (client, CALL_TYPE_NAME_VANISHED);
250 /* ---------------------------------------------------------------------------------------------------- */
252 /* Return a reference to the #Client for @watcher_id, or %NULL if it’s been
253 * unwatched. This is safe to call from any thread. */
255 dup_client (guint watcher_id)
261 g_assert (watcher_id != 0);
262 g_assert (map_id_to_client != NULL);
264 client = g_hash_table_lookup (map_id_to_client, GUINT_TO_POINTER (watcher_id));
274 /* Could be called from any thread, so it could be called after client_unref()
275 * has started finalising the #Client. Avoid that by looking up the #Client
278 on_connection_disconnected (GDBusConnection *connection,
279 gboolean remote_peer_vanished,
283 guint watcher_id = GPOINTER_TO_UINT (user_data);
284 Client *client = NULL;
286 client = dup_client (watcher_id);
290 if (client->name_owner_changed_subscription_id > 0)
291 g_dbus_connection_signal_unsubscribe (client->connection, client->name_owner_changed_subscription_id);
292 if (client->disconnected_signal_handler_id > 0)
293 g_signal_handler_disconnect (client->connection, client->disconnected_signal_handler_id);
294 g_object_unref (client->connection);
295 client->disconnected_signal_handler_id = 0;
296 client->name_owner_changed_subscription_id = 0;
297 client->connection = NULL;
299 call_vanished_handler (client, FALSE);
301 client_unref (client);
304 /* ---------------------------------------------------------------------------------------------------- */
306 /* Will always be called from the thread which acquired client->main_context. */
308 on_name_owner_changed (GDBusConnection *connection,
309 const gchar *sender_name,
310 const gchar *object_path,
311 const gchar *interface_name,
312 const gchar *signal_name,
313 GVariant *parameters,
316 guint watcher_id = GPOINTER_TO_UINT (user_data);
317 Client *client = NULL;
319 const gchar *old_owner;
320 const gchar *new_owner;
322 client = dup_client (watcher_id);
326 if (!client->initialized)
329 if (g_strcmp0 (object_path, "/org/freedesktop/DBus") != 0 ||
330 g_strcmp0 (interface_name, "org.freedesktop.DBus") != 0 ||
331 g_strcmp0 (sender_name, "org.freedesktop.DBus") != 0)
334 g_variant_get (parameters,
340 /* we only care about a specific name */
341 if (g_strcmp0 (name, client->name) != 0)
344 if ((old_owner != NULL && strlen (old_owner) > 0) && client->name_owner != NULL)
346 g_free (client->name_owner);
347 client->name_owner = NULL;
348 call_vanished_handler (client, FALSE);
351 if (new_owner != NULL && strlen (new_owner) > 0)
353 g_warn_if_fail (client->name_owner == NULL);
354 g_free (client->name_owner);
355 client->name_owner = g_strdup (new_owner);
356 call_appeared_handler (client);
360 client_unref (client);
363 /* ---------------------------------------------------------------------------------------------------- */
366 get_name_owner_cb (GObject *source_object,
370 Client *client = user_data;
372 const char *name_owner;
377 result = g_dbus_connection_call_finish (client->connection,
382 g_variant_get (result, "(&s)", &name_owner);
385 if (name_owner != NULL)
387 g_warn_if_fail (client->name_owner == NULL);
388 client->name_owner = g_strdup (name_owner);
389 call_appeared_handler (client);
393 call_vanished_handler (client, FALSE);
396 client->initialized = TRUE;
399 g_variant_unref (result);
400 client_unref (client);
403 /* ---------------------------------------------------------------------------------------------------- */
406 invoke_get_name_owner (Client *client)
408 g_dbus_connection_call (client->connection,
409 "org.freedesktop.DBus", /* bus name */
410 "/org/freedesktop/DBus", /* object path */
411 "org.freedesktop.DBus", /* interface name */
412 "GetNameOwner", /* method name */
413 g_variant_new ("(s)", client->name),
414 G_VARIANT_TYPE ("(s)"),
415 G_DBUS_CALL_FLAGS_NONE,
418 (GAsyncReadyCallback) get_name_owner_cb,
419 client_ref (client));
422 /* ---------------------------------------------------------------------------------------------------- */
425 start_service_by_name_cb (GObject *source_object,
429 Client *client = user_data;
434 result = g_dbus_connection_call_finish (client->connection,
439 guint32 start_service_result;
440 g_variant_get (result, "(u)", &start_service_result);
442 if (start_service_result == 1) /* DBUS_START_REPLY_SUCCESS */
444 invoke_get_name_owner (client);
446 else if (start_service_result == 2) /* DBUS_START_REPLY_ALREADY_RUNNING */
448 invoke_get_name_owner (client);
452 g_warning ("Unexpected reply %d from StartServiceByName() method", start_service_result);
453 call_vanished_handler (client, FALSE);
454 client->initialized = TRUE;
459 /* Errors are not unexpected; the bus will reply e.g.
461 * org.freedesktop.DBus.Error.ServiceUnknown: The name org.gnome.Epiphany2
462 * was not provided by any .service files
464 * This doesn't mean that the name doesn't have an owner, just
465 * that it's not provided by a .service file. So proceed to
466 * invoke GetNameOwner().
468 invoke_get_name_owner (client);
472 g_variant_unref (result);
473 client_unref (client);
476 /* ---------------------------------------------------------------------------------------------------- */
479 has_connection (Client *client)
481 /* listen for disconnection */
482 client->disconnected_signal_handler_id = g_signal_connect (client->connection,
484 G_CALLBACK (on_connection_disconnected),
485 GUINT_TO_POINTER (client->id));
487 /* start listening to NameOwnerChanged messages immediately */
488 client->name_owner_changed_subscription_id = g_dbus_connection_signal_subscribe (client->connection,
489 "org.freedesktop.DBus", /* name */
490 "org.freedesktop.DBus", /* if */
491 "NameOwnerChanged", /* signal */
492 "/org/freedesktop/DBus", /* path */
494 G_DBUS_SIGNAL_FLAGS_NONE,
495 on_name_owner_changed,
496 GUINT_TO_POINTER (client->id),
499 if (client->flags & G_BUS_NAME_WATCHER_FLAGS_AUTO_START)
501 g_dbus_connection_call (client->connection,
502 "org.freedesktop.DBus", /* bus name */
503 "/org/freedesktop/DBus", /* object path */
504 "org.freedesktop.DBus", /* interface name */
505 "StartServiceByName", /* method name */
506 g_variant_new ("(su)", client->name, 0),
507 G_VARIANT_TYPE ("(u)"),
508 G_DBUS_CALL_FLAGS_NONE,
511 (GAsyncReadyCallback) start_service_by_name_cb,
512 client_ref (client));
517 invoke_get_name_owner (client);
523 connection_get_cb (GObject *source_object,
527 Client *client = user_data;
529 client->connection = g_bus_get_finish (res, NULL);
530 if (client->connection == NULL)
532 call_vanished_handler (client, FALSE);
536 has_connection (client);
539 client_unref (client);
542 /* ---------------------------------------------------------------------------------------------------- */
546 * @bus_type: The type of bus to watch a name on.
547 * @name: The name (well-known or unique) to watch.
548 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
549 * @name_appeared_handler: (nullable): Handler to invoke when @name is known to exist or %NULL.
550 * @name_vanished_handler: (nullable): Handler to invoke when @name is known to not exist or %NULL.
551 * @user_data: User data to pass to handlers.
552 * @user_data_free_func: (nullable): Function for freeing @user_data or %NULL.
554 * Starts watching @name on the bus specified by @bus_type and calls
555 * @name_appeared_handler and @name_vanished_handler when the name is
556 * known to have a owner respectively known to lose its
557 * owner. Callbacks will be invoked in the
558 * [thread-default main context][g-main-context-push-thread-default]
559 * of the thread you are calling this function from.
561 * You are guaranteed that one of the handlers will be invoked after
562 * calling this function. When you are done watching the name, just
563 * call g_bus_unwatch_name() with the watcher id this function
566 * If the name vanishes or appears (for example the application owning
567 * the name could restart), the handlers are also invoked. If the
568 * #GDBusConnection that is used for watching the name disconnects, then
569 * @name_vanished_handler is invoked since it is no longer
570 * possible to access the name.
572 * Another guarantee is that invocations of @name_appeared_handler
573 * and @name_vanished_handler are guaranteed to alternate; that
574 * is, if @name_appeared_handler is invoked then you are
575 * guaranteed that the next time one of the handlers is invoked, it
576 * will be @name_vanished_handler. The reverse is also true.
578 * This behavior makes it very simple to write applications that want
579 * to take action when a certain [name exists][gdbus-watching-names].
580 * Basically, the application should create object proxies in
581 * @name_appeared_handler and destroy them again (if any) in
582 * @name_vanished_handler.
584 * Returns: An identifier (never 0) that an be used with
585 * g_bus_unwatch_name() to stop watching the name.
590 g_bus_watch_name (GBusType bus_type,
592 GBusNameWatcherFlags flags,
593 GBusNameAppearedCallback name_appeared_handler,
594 GBusNameVanishedCallback name_vanished_handler,
596 GDestroyNotify user_data_free_func)
600 g_return_val_if_fail (g_dbus_is_name (name), 0);
604 client = g_new0 (Client, 1);
605 client->ref_count = 1;
606 client->id = g_atomic_int_add (&next_global_id, 1); /* TODO: uh oh, handle overflow */
607 client->name = g_strdup (name);
608 client->flags = flags;
609 client->name_appeared_handler = name_appeared_handler;
610 client->name_vanished_handler = name_vanished_handler;
611 client->user_data = user_data;
612 client->user_data_free_func = user_data_free_func;
613 client->main_context = g_main_context_ref_thread_default ();
615 if (map_id_to_client == NULL)
617 map_id_to_client = g_hash_table_new (g_direct_hash, g_direct_equal);
619 g_hash_table_insert (map_id_to_client,
620 GUINT_TO_POINTER (client->id),
626 client_ref (client));
634 * g_bus_watch_name_on_connection:
635 * @connection: A #GDBusConnection.
636 * @name: The name (well-known or unique) to watch.
637 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
638 * @name_appeared_handler: (nullable): Handler to invoke when @name is known to exist or %NULL.
639 * @name_vanished_handler: (nullable): Handler to invoke when @name is known to not exist or %NULL.
640 * @user_data: User data to pass to handlers.
641 * @user_data_free_func: (nullable): Function for freeing @user_data or %NULL.
643 * Like g_bus_watch_name() but takes a #GDBusConnection instead of a
646 * Returns: An identifier (never 0) that an be used with
647 * g_bus_unwatch_name() to stop watching the name.
651 guint g_bus_watch_name_on_connection (GDBusConnection *connection,
653 GBusNameWatcherFlags flags,
654 GBusNameAppearedCallback name_appeared_handler,
655 GBusNameVanishedCallback name_vanished_handler,
657 GDestroyNotify user_data_free_func)
661 g_return_val_if_fail (G_IS_DBUS_CONNECTION (connection), 0);
662 g_return_val_if_fail (g_dbus_is_name (name), 0);
666 client = g_new0 (Client, 1);
667 client->ref_count = 1;
668 client->id = g_atomic_int_add (&next_global_id, 1); /* TODO: uh oh, handle overflow */
669 client->name = g_strdup (name);
670 client->flags = flags;
671 client->name_appeared_handler = name_appeared_handler;
672 client->name_vanished_handler = name_vanished_handler;
673 client->user_data = user_data;
674 client->user_data_free_func = user_data_free_func;
675 client->main_context = g_main_context_ref_thread_default ();
677 if (map_id_to_client == NULL)
678 map_id_to_client = g_hash_table_new (g_direct_hash, g_direct_equal);
680 g_hash_table_insert (map_id_to_client,
681 GUINT_TO_POINTER (client->id),
684 client->connection = g_object_ref (connection);
687 has_connection (client);
693 GClosure *name_appeared_closure;
694 GClosure *name_vanished_closure;
697 static WatchNameData *
698 watch_name_data_new (GClosure *name_appeared_closure,
699 GClosure *name_vanished_closure)
703 data = g_new0 (WatchNameData, 1);
705 if (name_appeared_closure != NULL)
707 data->name_appeared_closure = g_closure_ref (name_appeared_closure);
708 g_closure_sink (name_appeared_closure);
709 if (G_CLOSURE_NEEDS_MARSHAL (name_appeared_closure))
710 g_closure_set_marshal (name_appeared_closure, g_cclosure_marshal_generic);
713 if (name_vanished_closure != NULL)
715 data->name_vanished_closure = g_closure_ref (name_vanished_closure);
716 g_closure_sink (name_vanished_closure);
717 if (G_CLOSURE_NEEDS_MARSHAL (name_vanished_closure))
718 g_closure_set_marshal (name_vanished_closure, g_cclosure_marshal_generic);
725 watch_with_closures_on_name_appeared (GDBusConnection *connection,
727 const gchar *name_owner,
730 WatchNameData *data = user_data;
731 GValue params[3] = { G_VALUE_INIT, G_VALUE_INIT, G_VALUE_INIT };
733 g_value_init (¶ms[0], G_TYPE_DBUS_CONNECTION);
734 g_value_set_object (¶ms[0], connection);
736 g_value_init (¶ms[1], G_TYPE_STRING);
737 g_value_set_string (¶ms[1], name);
739 g_value_init (¶ms[2], G_TYPE_STRING);
740 g_value_set_string (¶ms[2], name_owner);
742 g_closure_invoke (data->name_appeared_closure, NULL, 3, params, NULL);
744 g_value_unset (params + 0);
745 g_value_unset (params + 1);
746 g_value_unset (params + 2);
750 watch_with_closures_on_name_vanished (GDBusConnection *connection,
754 WatchNameData *data = user_data;
755 GValue params[2] = { G_VALUE_INIT, G_VALUE_INIT };
757 g_value_init (¶ms[0], G_TYPE_DBUS_CONNECTION);
758 g_value_set_object (¶ms[0], connection);
760 g_value_init (¶ms[1], G_TYPE_STRING);
761 g_value_set_string (¶ms[1], name);
763 g_closure_invoke (data->name_vanished_closure, NULL, 2, params, NULL);
765 g_value_unset (params + 0);
766 g_value_unset (params + 1);
770 bus_watch_name_free_func (gpointer user_data)
772 WatchNameData *data = user_data;
774 if (data->name_appeared_closure != NULL)
775 g_closure_unref (data->name_appeared_closure);
777 if (data->name_vanished_closure != NULL)
778 g_closure_unref (data->name_vanished_closure);
784 * g_bus_watch_name_with_closures: (rename-to g_bus_watch_name)
785 * @bus_type: The type of bus to watch a name on.
786 * @name: The name (well-known or unique) to watch.
787 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
788 * @name_appeared_closure: (nullable): #GClosure to invoke when @name is known
790 * @name_vanished_closure: (nullable): #GClosure to invoke when @name is known
791 * to not exist or %NULL.
793 * Version of g_bus_watch_name() using closures instead of callbacks for
794 * easier binding in other languages.
796 * Returns: An identifier (never 0) that an be used with
797 * g_bus_unwatch_name() to stop watching the name.
802 g_bus_watch_name_with_closures (GBusType bus_type,
804 GBusNameWatcherFlags flags,
805 GClosure *name_appeared_closure,
806 GClosure *name_vanished_closure)
808 return g_bus_watch_name (bus_type,
811 name_appeared_closure != NULL ? watch_with_closures_on_name_appeared : NULL,
812 name_vanished_closure != NULL ? watch_with_closures_on_name_vanished : NULL,
813 watch_name_data_new (name_appeared_closure, name_vanished_closure),
814 bus_watch_name_free_func);
818 * g_bus_watch_name_on_connection_with_closures: (rename-to g_bus_watch_name_on_connection)
819 * @connection: A #GDBusConnection.
820 * @name: The name (well-known or unique) to watch.
821 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
822 * @name_appeared_closure: (nullable): #GClosure to invoke when @name is known
824 * @name_vanished_closure: (nullable): #GClosure to invoke when @name is known
825 * to not exist or %NULL.
827 * Version of g_bus_watch_name_on_connection() using closures instead of callbacks for
828 * easier binding in other languages.
830 * Returns: An identifier (never 0) that an be used with
831 * g_bus_unwatch_name() to stop watching the name.
835 guint g_bus_watch_name_on_connection_with_closures (
836 GDBusConnection *connection,
838 GBusNameWatcherFlags flags,
839 GClosure *name_appeared_closure,
840 GClosure *name_vanished_closure)
842 return g_bus_watch_name_on_connection (connection,
845 name_appeared_closure != NULL ? watch_with_closures_on_name_appeared : NULL,
846 name_vanished_closure != NULL ? watch_with_closures_on_name_vanished : NULL,
847 watch_name_data_new (name_appeared_closure, name_vanished_closure),
848 bus_watch_name_free_func);
852 * g_bus_unwatch_name:
853 * @watcher_id: An identifier obtained from g_bus_watch_name()
855 * Stops watching a name.
860 g_bus_unwatch_name (guint watcher_id)
864 g_return_if_fail (watcher_id > 0);
869 if (watcher_id == 0 ||
870 map_id_to_client == NULL ||
871 (client = g_hash_table_lookup (map_id_to_client, GUINT_TO_POINTER (watcher_id))) == NULL)
873 g_warning ("Invalid id %d passed to g_bus_unwatch_name()", watcher_id);
877 client->cancelled = TRUE;
878 g_warn_if_fail (g_hash_table_remove (map_id_to_client, GUINT_TO_POINTER (watcher_id)));
883 /* do callback without holding lock */
886 client_unref (client);