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 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, write to the
17 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
18 * Boston, MA 02111-1307, USA.
20 * Author: David Zeuthen <davidz@redhat.com>
28 #include "gdbusutils.h"
29 #include "gdbusnamewatching.h"
30 #include "gdbuserror.h"
31 #include "gdbusprivate.h"
32 #include "gdbusconnection.h"
37 * SECTION:gdbusnamewatching
38 * @title: Watching Bus Names
39 * @short_description: Simple API for watching bus names
42 * Convenience API for watching bus names.
44 * <example id="gdbus-watching-names"><title>Simple application watching a name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-watch-name.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
47 G_LOCK_DEFINE_STATIC (lock
);
49 /* ---------------------------------------------------------------------------------------------------- */
53 PREVIOUS_CALL_NONE
= 0,
54 PREVIOUS_CALL_APPEARED
,
55 PREVIOUS_CALL_VANISHED
,
60 volatile gint ref_count
;
63 GBusNameWatcherFlags flags
;
65 GBusNameAppearedCallback name_appeared_handler
;
66 GBusNameVanishedCallback name_vanished_handler
;
68 GDestroyNotify user_data_free_func
;
69 GMainContext
*main_context
;
71 GDBusConnection
*connection
;
72 gulong disconnected_signal_handler_id
;
73 guint name_owner_changed_subscription_id
;
75 PreviousCall previous_call
;
81 static guint next_global_id
= 1;
82 static GHashTable
*map_id_to_client
= NULL
;
85 client_ref (Client
*client
)
87 g_atomic_int_inc (&client
->ref_count
);
92 client_unref (Client
*client
)
94 if (g_atomic_int_dec_and_test (&client
->ref_count
))
96 if (client
->connection
!= NULL
)
98 if (client
->name_owner_changed_subscription_id
> 0)
99 g_dbus_connection_signal_unsubscribe (client
->connection
, client
->name_owner_changed_subscription_id
);
100 if (client
->disconnected_signal_handler_id
> 0)
101 g_signal_handler_disconnect (client
->connection
, client
->disconnected_signal_handler_id
);
102 g_object_unref (client
->connection
);
104 g_free (client
->name
);
105 g_free (client
->name_owner
);
106 g_main_context_unref (client
->main_context
);
107 if (client
->user_data_free_func
!= NULL
)
108 client
->user_data_free_func (client
->user_data
);
113 /* ---------------------------------------------------------------------------------------------------- */
117 CALL_TYPE_NAME_APPEARED
,
118 CALL_TYPE_NAME_VANISHED
125 /* keep this separate because client->connection may
126 * be set to NULL after scheduling the call
128 GDBusConnection
*connection
;
137 call_handler_data_free (CallHandlerData
*data
)
139 if (data
->connection
!= NULL
)
140 g_object_unref (data
->connection
);
141 g_free (data
->name_owner
);
142 client_unref (data
->client
);
147 actually_do_call (Client
*client
, GDBusConnection
*connection
, const gchar
*name_owner
, CallType call_type
)
151 case CALL_TYPE_NAME_APPEARED
:
152 if (client
->name_appeared_handler
!= NULL
)
154 client
->name_appeared_handler (connection
,
161 case CALL_TYPE_NAME_VANISHED
:
162 if (client
->name_vanished_handler
!= NULL
)
164 client
->name_vanished_handler (connection
,
171 g_assert_not_reached ();
177 call_in_idle_cb (gpointer _data
)
179 CallHandlerData
*data
= _data
;
180 actually_do_call (data
->client
, data
->connection
, data
->name_owner
, data
->call_type
);
185 schedule_call_in_idle (Client
*client
, CallType call_type
)
187 CallHandlerData
*data
;
188 GSource
*idle_source
;
190 data
= g_new0 (CallHandlerData
, 1);
191 data
->client
= client_ref (client
);
192 data
->connection
= client
->connection
!= NULL
? g_object_ref (client
->connection
) : NULL
;
193 data
->name_owner
= g_strdup (client
->name_owner
);
194 data
->call_type
= call_type
;
196 idle_source
= g_idle_source_new ();
197 g_source_set_priority (idle_source
, G_PRIORITY_HIGH
);
198 g_source_set_callback (idle_source
,
201 (GDestroyNotify
) call_handler_data_free
);
202 g_source_attach (idle_source
, client
->main_context
);
203 g_source_unref (idle_source
);
207 do_call (Client
*client
, CallType call_type
)
209 GMainContext
*current_context
;
211 /* only schedule in idle if we're not in the right thread */
212 current_context
= g_main_context_ref_thread_default ();
213 if (current_context
!= client
->main_context
)
214 schedule_call_in_idle (client
, call_type
);
216 actually_do_call (client
, client
->connection
, client
->name_owner
, call_type
);
217 g_main_context_unref (current_context
);
221 call_appeared_handler (Client
*client
)
223 if (client
->previous_call
!= PREVIOUS_CALL_APPEARED
)
225 client
->previous_call
= PREVIOUS_CALL_APPEARED
;
226 if (!client
->cancelled
&& client
->name_appeared_handler
!= NULL
)
228 do_call (client
, CALL_TYPE_NAME_APPEARED
);
234 call_vanished_handler (Client
*client
,
235 gboolean ignore_cancelled
)
237 if (client
->previous_call
!= PREVIOUS_CALL_VANISHED
)
239 client
->previous_call
= PREVIOUS_CALL_VANISHED
;
240 if (((!client
->cancelled
) || ignore_cancelled
) && client
->name_vanished_handler
!= NULL
)
242 do_call (client
, CALL_TYPE_NAME_VANISHED
);
247 /* ---------------------------------------------------------------------------------------------------- */
250 on_connection_disconnected (GDBusConnection
*connection
,
251 gboolean remote_peer_vanished
,
255 Client
*client
= user_data
;
257 if (client
->name_owner_changed_subscription_id
> 0)
258 g_dbus_connection_signal_unsubscribe (client
->connection
, client
->name_owner_changed_subscription_id
);
259 if (client
->disconnected_signal_handler_id
> 0)
260 g_signal_handler_disconnect (client
->connection
, client
->disconnected_signal_handler_id
);
261 g_object_unref (client
->connection
);
262 client
->disconnected_signal_handler_id
= 0;
263 client
->name_owner_changed_subscription_id
= 0;
264 client
->connection
= NULL
;
266 call_vanished_handler (client
, FALSE
);
269 /* ---------------------------------------------------------------------------------------------------- */
272 on_name_owner_changed (GDBusConnection
*connection
,
273 const gchar
*sender_name
,
274 const gchar
*object_path
,
275 const gchar
*interface_name
,
276 const gchar
*signal_name
,
277 GVariant
*parameters
,
280 Client
*client
= user_data
;
282 const gchar
*old_owner
;
283 const gchar
*new_owner
;
285 if (!client
->initialized
)
288 if (g_strcmp0 (object_path
, "/org/freedesktop/DBus") != 0 ||
289 g_strcmp0 (interface_name
, "org.freedesktop.DBus") != 0 ||
290 g_strcmp0 (sender_name
, "org.freedesktop.DBus") != 0)
293 g_variant_get (parameters
,
299 /* we only care about a specific name */
300 if (g_strcmp0 (name
, client
->name
) != 0)
303 if ((old_owner
!= NULL
&& strlen (old_owner
) > 0) && client
->name_owner
!= NULL
)
305 g_free (client
->name_owner
);
306 client
->name_owner
= NULL
;
307 call_vanished_handler (client
, FALSE
);
310 if (new_owner
!= NULL
&& strlen (new_owner
) > 0)
312 g_warn_if_fail (client
->name_owner
== NULL
);
313 g_free (client
->name_owner
);
314 client
->name_owner
= g_strdup (new_owner
);
315 call_appeared_handler (client
);
322 /* ---------------------------------------------------------------------------------------------------- */
325 get_name_owner_cb (GObject
*source_object
,
329 Client
*client
= user_data
;
331 const char *name_owner
;
336 result
= g_dbus_connection_call_finish (client
->connection
,
341 g_variant_get (result
, "(&s)", &name_owner
);
344 if (name_owner
!= NULL
)
346 g_warn_if_fail (client
->name_owner
== NULL
);
347 client
->name_owner
= g_strdup (name_owner
);
348 call_appeared_handler (client
);
352 call_vanished_handler (client
, FALSE
);
355 client
->initialized
= TRUE
;
358 g_variant_unref (result
);
359 client_unref (client
);
362 /* ---------------------------------------------------------------------------------------------------- */
365 invoke_get_name_owner (Client
*client
)
367 g_dbus_connection_call (client
->connection
,
368 "org.freedesktop.DBus", /* bus name */
369 "/org/freedesktop/DBus", /* object path */
370 "org.freedesktop.DBus", /* interface name */
371 "GetNameOwner", /* method name */
372 g_variant_new ("(s)", client
->name
),
373 G_VARIANT_TYPE ("(s)"),
374 G_DBUS_CALL_FLAGS_NONE
,
377 (GAsyncReadyCallback
) get_name_owner_cb
,
378 client_ref (client
));
381 /* ---------------------------------------------------------------------------------------------------- */
384 start_service_by_name_cb (GObject
*source_object
,
388 Client
*client
= user_data
;
393 result
= g_dbus_connection_call_finish (client
->connection
,
398 guint32 start_service_result
;
399 g_variant_get (result
, "(u)", &start_service_result
);
401 if (start_service_result
== 1) /* DBUS_START_REPLY_SUCCESS */
403 invoke_get_name_owner (client
);
405 else if (start_service_result
== 2) /* DBUS_START_REPLY_ALREADY_RUNNING */
407 invoke_get_name_owner (client
);
411 g_warning ("Unexpected reply %d from StartServiceByName() method", start_service_result
);
412 call_vanished_handler (client
, FALSE
);
413 client
->initialized
= TRUE
;
418 /* Errors are not unexpected; the bus will reply e.g.
420 * org.freedesktop.DBus.Error.ServiceUnknown: The name org.gnome.Epiphany2
421 * was not provided by any .service files
423 * This doesn't mean that the name doesn't have an owner, just
424 * that it's not provided by a .service file. So proceed to
425 * invoke GetNameOwner().
427 invoke_get_name_owner (client
);
431 g_variant_unref (result
);
432 client_unref (client
);
435 /* ---------------------------------------------------------------------------------------------------- */
438 has_connection (Client
*client
)
440 /* listen for disconnection */
441 client
->disconnected_signal_handler_id
= g_signal_connect (client
->connection
,
443 G_CALLBACK (on_connection_disconnected
),
446 /* start listening to NameOwnerChanged messages immediately */
447 client
->name_owner_changed_subscription_id
= g_dbus_connection_signal_subscribe (client
->connection
,
448 "org.freedesktop.DBus", /* name */
449 "org.freedesktop.DBus", /* if */
450 "NameOwnerChanged", /* signal */
451 "/org/freedesktop/DBus", /* path */
453 G_DBUS_SIGNAL_FLAGS_NONE
,
454 on_name_owner_changed
,
458 if (client
->flags
& G_BUS_NAME_WATCHER_FLAGS_AUTO_START
)
460 g_dbus_connection_call (client
->connection
,
461 "org.freedesktop.DBus", /* bus name */
462 "/org/freedesktop/DBus", /* object path */
463 "org.freedesktop.DBus", /* interface name */
464 "StartServiceByName", /* method name */
465 g_variant_new ("(su)", client
->name
, 0),
466 G_VARIANT_TYPE ("(u)"),
467 G_DBUS_CALL_FLAGS_NONE
,
470 (GAsyncReadyCallback
) start_service_by_name_cb
,
471 client_ref (client
));
476 invoke_get_name_owner (client
);
482 connection_get_cb (GObject
*source_object
,
486 Client
*client
= user_data
;
488 client
->connection
= g_bus_get_finish (res
, NULL
);
489 if (client
->connection
== NULL
)
491 call_vanished_handler (client
, FALSE
);
495 has_connection (client
);
498 client_unref (client
);
501 /* ---------------------------------------------------------------------------------------------------- */
505 * @bus_type: The type of bus to watch a name on.
506 * @name: The name (well-known or unique) to watch.
507 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
508 * @name_appeared_handler: Handler to invoke when @name is known to exist or %NULL.
509 * @name_vanished_handler: Handler to invoke when @name is known to not exist or %NULL.
510 * @user_data: User data to pass to handlers.
511 * @user_data_free_func: Function for freeing @user_data or %NULL.
513 * Starts watching @name on the bus specified by @bus_type and calls
514 * @name_appeared_handler and @name_vanished_handler when the name is
515 * known to have a owner respectively known to lose its
516 * owner. Callbacks will be invoked in the <link
517 * linkend="g-main-context-push-thread-default">thread-default main
518 * loop</link> of the thread you are calling this function from.
520 * You are guaranteed that one of the handlers will be invoked after
521 * calling this function. When you are done watching the name, just
522 * call g_bus_unwatch_name() with the watcher id this function
525 * If the name vanishes or appears (for example the application owning
526 * the name could restart), the handlers are also invoked. If the
527 * #GDBusConnection that is used for watching the name disconnects, then
528 * @name_vanished_handler is invoked since it is no longer
529 * possible to access the name.
531 * Another guarantee is that invocations of @name_appeared_handler
532 * and @name_vanished_handler are guaranteed to alternate; that
533 * is, if @name_appeared_handler is invoked then you are
534 * guaranteed that the next time one of the handlers is invoked, it
535 * will be @name_vanished_handler. The reverse is also true.
537 * This behavior makes it very simple to write applications that wants
538 * to take action when a certain name exists, see <xref
539 * linkend="gdbus-watching-names"/>. Basically, the application
540 * should create object proxies in @name_appeared_handler and destroy
541 * them again (if any) in @name_vanished_handler.
543 * Returns: An identifier (never 0) that an be used with
544 * g_bus_unwatch_name() to stop watching the name.
549 g_bus_watch_name (GBusType bus_type
,
551 GBusNameWatcherFlags flags
,
552 GBusNameAppearedCallback name_appeared_handler
,
553 GBusNameVanishedCallback name_vanished_handler
,
555 GDestroyNotify user_data_free_func
)
559 g_return_val_if_fail (g_dbus_is_name (name
), 0);
563 client
= g_new0 (Client
, 1);
564 client
->ref_count
= 1;
565 client
->id
= next_global_id
++; /* TODO: uh oh, handle overflow */
566 client
->name
= g_strdup (name
);
567 client
->flags
= flags
;
568 client
->name_appeared_handler
= name_appeared_handler
;
569 client
->name_vanished_handler
= name_vanished_handler
;
570 client
->user_data
= user_data
;
571 client
->user_data_free_func
= user_data_free_func
;
572 client
->main_context
= g_main_context_ref_thread_default ();
574 if (map_id_to_client
== NULL
)
576 map_id_to_client
= g_hash_table_new (g_direct_hash
, g_direct_equal
);
578 g_hash_table_insert (map_id_to_client
,
579 GUINT_TO_POINTER (client
->id
),
585 client_ref (client
));
593 * g_bus_watch_name_on_connection:
594 * @connection: A #GDBusConnection.
595 * @name: The name (well-known or unique) to watch.
596 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
597 * @name_appeared_handler: Handler to invoke when @name is known to exist or %NULL.
598 * @name_vanished_handler: Handler to invoke when @name is known to not exist or %NULL.
599 * @user_data: User data to pass to handlers.
600 * @user_data_free_func: Function for freeing @user_data or %NULL.
602 * Like g_bus_watch_name() but takes a #GDBusConnection instead of a
605 * Returns: An identifier (never 0) that an be used with
606 * g_bus_unwatch_name() to stop watching the name.
610 guint
g_bus_watch_name_on_connection (GDBusConnection
*connection
,
612 GBusNameWatcherFlags flags
,
613 GBusNameAppearedCallback name_appeared_handler
,
614 GBusNameVanishedCallback name_vanished_handler
,
616 GDestroyNotify user_data_free_func
)
620 g_return_val_if_fail (G_IS_DBUS_CONNECTION (connection
), 0);
621 g_return_val_if_fail (g_dbus_is_name (name
), 0);
625 client
= g_new0 (Client
, 1);
626 client
->ref_count
= 1;
627 client
->id
= next_global_id
++; /* TODO: uh oh, handle overflow */
628 client
->name
= g_strdup (name
);
629 client
->flags
= flags
;
630 client
->name_appeared_handler
= name_appeared_handler
;
631 client
->name_vanished_handler
= name_vanished_handler
;
632 client
->user_data
= user_data
;
633 client
->user_data_free_func
= user_data_free_func
;
634 client
->main_context
= g_main_context_ref_thread_default ();
636 if (map_id_to_client
== NULL
)
637 map_id_to_client
= g_hash_table_new (g_direct_hash
, g_direct_equal
);
639 g_hash_table_insert (map_id_to_client
,
640 GUINT_TO_POINTER (client
->id
),
643 client
->connection
= g_object_ref (connection
);
646 has_connection (client
);
652 GClosure
*name_appeared_closure
;
653 GClosure
*name_vanished_closure
;
656 static WatchNameData
*
657 watch_name_data_new (GClosure
*name_appeared_closure
,
658 GClosure
*name_vanished_closure
)
662 data
= g_new0 (WatchNameData
, 1);
664 if (name_appeared_closure
!= NULL
)
666 data
->name_appeared_closure
= g_closure_ref (name_appeared_closure
);
667 g_closure_sink (name_appeared_closure
);
668 if (G_CLOSURE_NEEDS_MARSHAL (name_appeared_closure
))
669 g_closure_set_marshal (name_appeared_closure
, g_cclosure_marshal_generic
);
672 if (name_vanished_closure
!= NULL
)
674 data
->name_vanished_closure
= g_closure_ref (name_vanished_closure
);
675 g_closure_sink (name_vanished_closure
);
676 if (G_CLOSURE_NEEDS_MARSHAL (name_vanished_closure
))
677 g_closure_set_marshal (name_vanished_closure
, g_cclosure_marshal_generic
);
684 watch_with_closures_on_name_appeared (GDBusConnection
*connection
,
686 const gchar
*name_owner
,
689 WatchNameData
*data
= user_data
;
690 GValue params
[3] = { G_VALUE_INIT
, G_VALUE_INIT
, G_VALUE_INIT
};
692 g_value_init (¶ms
[0], G_TYPE_DBUS_CONNECTION
);
693 g_value_set_object (¶ms
[0], connection
);
695 g_value_init (¶ms
[1], G_TYPE_STRING
);
696 g_value_set_string (¶ms
[1], name
);
698 g_value_init (¶ms
[2], G_TYPE_STRING
);
699 g_value_set_string (¶ms
[2], name_owner
);
701 g_closure_invoke (data
->name_appeared_closure
, NULL
, 3, params
, NULL
);
703 g_value_unset (params
+ 0);
704 g_value_unset (params
+ 1);
705 g_value_unset (params
+ 2);
709 watch_with_closures_on_name_vanished (GDBusConnection
*connection
,
713 WatchNameData
*data
= user_data
;
714 GValue params
[2] = { G_VALUE_INIT
, G_VALUE_INIT
};
716 g_value_init (¶ms
[0], G_TYPE_DBUS_CONNECTION
);
717 g_value_set_object (¶ms
[0], connection
);
719 g_value_init (¶ms
[1], G_TYPE_STRING
);
720 g_value_set_string (¶ms
[1], name
);
722 g_closure_invoke (data
->name_vanished_closure
, NULL
, 2, params
, NULL
);
724 g_value_unset (params
+ 0);
725 g_value_unset (params
+ 1);
729 bus_watch_name_free_func (gpointer user_data
)
731 WatchNameData
*data
= user_data
;
733 if (data
->name_appeared_closure
!= NULL
)
734 g_closure_unref (data
->name_appeared_closure
);
736 if (data
->name_vanished_closure
!= NULL
)
737 g_closure_unref (data
->name_vanished_closure
);
743 * g_bus_watch_name_with_closures:
744 * @bus_type: The type of bus to watch a name on.
745 * @name: The name (well-known or unique) to watch.
746 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
747 * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known
749 * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known
750 * to not exist or %NULL.
752 * Version of g_bus_watch_name() using closures instead of callbacks for
753 * easier binding in other languages.
755 * Returns: An identifier (never 0) that an be used with
756 * g_bus_unwatch_name() to stop watching the name.
758 * Rename to: g_bus_watch_name
763 g_bus_watch_name_with_closures (GBusType bus_type
,
765 GBusNameWatcherFlags flags
,
766 GClosure
*name_appeared_closure
,
767 GClosure
*name_vanished_closure
)
769 return g_bus_watch_name (bus_type
,
772 name_appeared_closure
!= NULL
? watch_with_closures_on_name_appeared
: NULL
,
773 name_vanished_closure
!= NULL
? watch_with_closures_on_name_vanished
: NULL
,
774 watch_name_data_new (name_appeared_closure
, name_vanished_closure
),
775 bus_watch_name_free_func
);
779 * g_bus_watch_name_on_connection_with_closures:
780 * @connection: A #GDBusConnection.
781 * @name: The name (well-known or unique) to watch.
782 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
783 * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known
785 * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known
786 * to not exist or %NULL.
788 * Version of g_bus_watch_name_on_connection() using closures instead of callbacks for
789 * easier binding in other languages.
791 * Returns: An identifier (never 0) that an be used with
792 * g_bus_unwatch_name() to stop watching the name.
794 * Rename to: g_bus_watch_name_on_connection
798 guint
g_bus_watch_name_on_connection_with_closures (
799 GDBusConnection
*connection
,
801 GBusNameWatcherFlags flags
,
802 GClosure
*name_appeared_closure
,
803 GClosure
*name_vanished_closure
)
805 return g_bus_watch_name_on_connection (connection
,
808 name_appeared_closure
!= NULL
? watch_with_closures_on_name_appeared
: NULL
,
809 name_vanished_closure
!= NULL
? watch_with_closures_on_name_vanished
: NULL
,
810 watch_name_data_new (name_appeared_closure
, name_vanished_closure
),
811 bus_watch_name_free_func
);
815 * g_bus_unwatch_name:
816 * @watcher_id: An identifier obtained from g_bus_watch_name()
818 * Stops watching a name.
823 g_bus_unwatch_name (guint watcher_id
)
827 g_return_if_fail (watcher_id
> 0);
832 if (watcher_id
== 0 ||
833 map_id_to_client
== NULL
||
834 (client
= g_hash_table_lookup (map_id_to_client
, GUINT_TO_POINTER (watcher_id
))) == NULL
)
836 g_warning ("Invalid id %d passed to g_bus_unwatch_name()", watcher_id
);
840 client
->cancelled
= TRUE
;
841 g_warn_if_fail (g_hash_table_remove (map_id_to_client
, GUINT_TO_POINTER (watcher_id
)));
846 /* do callback without holding lock */
849 client_unref (client
);