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 if (client
->main_context
!= NULL
)
107 g_main_context_unref (client
->main_context
);
108 if (client
->user_data_free_func
!= NULL
)
109 client
->user_data_free_func (client
->user_data
);
114 /* ---------------------------------------------------------------------------------------------------- */
118 CALL_TYPE_NAME_APPEARED
,
119 CALL_TYPE_NAME_VANISHED
126 /* keep this separate because client->connection may
127 * be set to NULL after scheduling the call
129 GDBusConnection
*connection
;
138 call_handler_data_free (CallHandlerData
*data
)
140 if (data
->connection
!= NULL
)
141 g_object_unref (data
->connection
);
142 g_free (data
->name_owner
);
143 client_unref (data
->client
);
148 actually_do_call (Client
*client
, GDBusConnection
*connection
, const gchar
*name_owner
, CallType call_type
)
152 case CALL_TYPE_NAME_APPEARED
:
153 if (client
->name_appeared_handler
!= NULL
)
155 client
->name_appeared_handler (connection
,
162 case CALL_TYPE_NAME_VANISHED
:
163 if (client
->name_vanished_handler
!= NULL
)
165 client
->name_vanished_handler (connection
,
172 g_assert_not_reached ();
178 call_in_idle_cb (gpointer _data
)
180 CallHandlerData
*data
= _data
;
181 actually_do_call (data
->client
, data
->connection
, data
->name_owner
, data
->call_type
);
186 schedule_call_in_idle (Client
*client
, CallType call_type
)
188 CallHandlerData
*data
;
189 GSource
*idle_source
;
191 data
= g_new0 (CallHandlerData
, 1);
192 data
->client
= client_ref (client
);
193 data
->connection
= client
->connection
!= NULL
? g_object_ref (client
->connection
) : NULL
;
194 data
->name_owner
= g_strdup (client
->name_owner
);
195 data
->call_type
= call_type
;
197 idle_source
= g_idle_source_new ();
198 g_source_set_priority (idle_source
, G_PRIORITY_HIGH
);
199 g_source_set_callback (idle_source
,
202 (GDestroyNotify
) call_handler_data_free
);
203 g_source_attach (idle_source
, client
->main_context
);
204 g_source_unref (idle_source
);
208 do_call (Client
*client
, CallType call_type
)
210 /* only schedule in idle if we're not in the right thread */
211 if (g_main_context_get_thread_default () != client
->main_context
)
212 schedule_call_in_idle (client
, call_type
);
214 actually_do_call (client
, client
->connection
, client
->name_owner
, call_type
);
218 call_appeared_handler (Client
*client
)
220 if (client
->previous_call
!= PREVIOUS_CALL_APPEARED
)
222 client
->previous_call
= PREVIOUS_CALL_APPEARED
;
223 if (!client
->cancelled
&& client
->name_appeared_handler
!= NULL
)
225 do_call (client
, CALL_TYPE_NAME_APPEARED
);
231 call_vanished_handler (Client
*client
,
232 gboolean ignore_cancelled
)
234 if (client
->previous_call
!= PREVIOUS_CALL_VANISHED
)
236 client
->previous_call
= PREVIOUS_CALL_VANISHED
;
237 if (((!client
->cancelled
) || ignore_cancelled
) && client
->name_vanished_handler
!= NULL
)
239 do_call (client
, CALL_TYPE_NAME_VANISHED
);
244 /* ---------------------------------------------------------------------------------------------------- */
247 on_connection_disconnected (GDBusConnection
*connection
,
248 gboolean remote_peer_vanished
,
252 Client
*client
= user_data
;
254 if (client
->name_owner_changed_subscription_id
> 0)
255 g_dbus_connection_signal_unsubscribe (client
->connection
, client
->name_owner_changed_subscription_id
);
256 if (client
->disconnected_signal_handler_id
> 0)
257 g_signal_handler_disconnect (client
->connection
, client
->disconnected_signal_handler_id
);
258 g_object_unref (client
->connection
);
259 client
->disconnected_signal_handler_id
= 0;
260 client
->name_owner_changed_subscription_id
= 0;
261 client
->connection
= NULL
;
263 call_vanished_handler (client
, FALSE
);
266 /* ---------------------------------------------------------------------------------------------------- */
269 on_name_owner_changed (GDBusConnection
*connection
,
270 const gchar
*sender_name
,
271 const gchar
*object_path
,
272 const gchar
*interface_name
,
273 const gchar
*signal_name
,
274 GVariant
*parameters
,
277 Client
*client
= user_data
;
279 const gchar
*old_owner
;
280 const gchar
*new_owner
;
282 if (!client
->initialized
)
285 if (g_strcmp0 (object_path
, "/org/freedesktop/DBus") != 0 ||
286 g_strcmp0 (interface_name
, "org.freedesktop.DBus") != 0 ||
287 g_strcmp0 (sender_name
, "org.freedesktop.DBus") != 0)
290 g_variant_get (parameters
,
296 /* we only care about a specific name */
297 if (g_strcmp0 (name
, client
->name
) != 0)
300 if ((old_owner
!= NULL
&& strlen (old_owner
) > 0) && client
->name_owner
!= NULL
)
302 g_free (client
->name_owner
);
303 client
->name_owner
= NULL
;
304 call_vanished_handler (client
, FALSE
);
307 if (new_owner
!= NULL
&& strlen (new_owner
) > 0)
309 g_warn_if_fail (client
->name_owner
== NULL
);
310 g_free (client
->name_owner
);
311 client
->name_owner
= g_strdup (new_owner
);
312 call_appeared_handler (client
);
319 /* ---------------------------------------------------------------------------------------------------- */
322 get_name_owner_cb (GObject
*source_object
,
326 Client
*client
= user_data
;
328 const char *name_owner
;
333 result
= g_dbus_connection_call_finish (client
->connection
,
338 g_variant_get (result
, "(&s)", &name_owner
);
341 if (name_owner
!= NULL
)
343 g_warn_if_fail (client
->name_owner
== NULL
);
344 client
->name_owner
= g_strdup (name_owner
);
345 call_appeared_handler (client
);
349 call_vanished_handler (client
, FALSE
);
352 client
->initialized
= TRUE
;
355 g_variant_unref (result
);
356 client_unref (client
);
359 /* ---------------------------------------------------------------------------------------------------- */
362 invoke_get_name_owner (Client
*client
)
364 g_dbus_connection_call (client
->connection
,
365 "org.freedesktop.DBus", /* bus name */
366 "/org/freedesktop/DBus", /* object path */
367 "org.freedesktop.DBus", /* interface name */
368 "GetNameOwner", /* method name */
369 g_variant_new ("(s)", client
->name
),
370 G_VARIANT_TYPE ("(s)"),
371 G_DBUS_CALL_FLAGS_NONE
,
374 (GAsyncReadyCallback
) get_name_owner_cb
,
375 client_ref (client
));
378 /* ---------------------------------------------------------------------------------------------------- */
381 start_service_by_name_cb (GObject
*source_object
,
385 Client
*client
= user_data
;
390 result
= g_dbus_connection_call_finish (client
->connection
,
395 guint32 start_service_result
;
396 g_variant_get (result
, "(u)", &start_service_result
);
398 if (start_service_result
== 1) /* DBUS_START_REPLY_SUCCESS */
400 invoke_get_name_owner (client
);
402 else if (start_service_result
== 2) /* DBUS_START_REPLY_ALREADY_RUNNING */
404 invoke_get_name_owner (client
);
408 g_warning ("Unexpected reply %d from StartServiceByName() method", start_service_result
);
409 call_vanished_handler (client
, FALSE
);
410 client
->initialized
= TRUE
;
415 /* Errors are not unexpected; the bus will reply e.g.
417 * org.freedesktop.DBus.Error.ServiceUnknown: The name org.gnome.Epiphany2
418 * was not provided by any .service files
420 * This doesn't mean that the name doesn't have an owner, just
421 * that it's not provided by a .service file. So proceed to
422 * invoke GetNameOwner().
424 invoke_get_name_owner (client
);
428 g_variant_unref (result
);
429 client_unref (client
);
432 /* ---------------------------------------------------------------------------------------------------- */
435 has_connection (Client
*client
)
437 /* listen for disconnection */
438 client
->disconnected_signal_handler_id
= g_signal_connect (client
->connection
,
440 G_CALLBACK (on_connection_disconnected
),
443 /* start listening to NameOwnerChanged messages immediately */
444 client
->name_owner_changed_subscription_id
= g_dbus_connection_signal_subscribe (client
->connection
,
445 "org.freedesktop.DBus", /* name */
446 "org.freedesktop.DBus", /* if */
447 "NameOwnerChanged", /* signal */
448 "/org/freedesktop/DBus", /* path */
450 G_DBUS_SIGNAL_FLAGS_NONE
,
451 on_name_owner_changed
,
455 if (client
->flags
& G_BUS_NAME_WATCHER_FLAGS_AUTO_START
)
457 g_dbus_connection_call (client
->connection
,
458 "org.freedesktop.DBus", /* bus name */
459 "/org/freedesktop/DBus", /* object path */
460 "org.freedesktop.DBus", /* interface name */
461 "StartServiceByName", /* method name */
462 g_variant_new ("(su)", client
->name
, 0),
463 G_VARIANT_TYPE ("(u)"),
464 G_DBUS_CALL_FLAGS_NONE
,
467 (GAsyncReadyCallback
) start_service_by_name_cb
,
468 client_ref (client
));
473 invoke_get_name_owner (client
);
479 connection_get_cb (GObject
*source_object
,
483 Client
*client
= user_data
;
485 client
->connection
= g_bus_get_finish (res
, NULL
);
486 if (client
->connection
== NULL
)
488 call_vanished_handler (client
, FALSE
);
492 has_connection (client
);
495 client_unref (client
);
498 /* ---------------------------------------------------------------------------------------------------- */
502 * @bus_type: The type of bus to watch a name on.
503 * @name: The name (well-known or unique) to watch.
504 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
505 * @name_appeared_handler: Handler to invoke when @name is known to exist or %NULL.
506 * @name_vanished_handler: Handler to invoke when @name is known to not exist or %NULL.
507 * @user_data: User data to pass to handlers.
508 * @user_data_free_func: Function for freeing @user_data or %NULL.
510 * Starts watching @name on the bus specified by @bus_type and calls
511 * @name_appeared_handler and @name_vanished_handler when the name is
512 * known to have a owner respectively known to lose its
513 * owner. Callbacks will be invoked in the <link
514 * linkend="g-main-context-push-thread-default">thread-default main
515 * loop</link> of the thread you are calling this function from.
517 * You are guaranteed that one of the handlers will be invoked after
518 * calling this function. When you are done watching the name, just
519 * call g_bus_unwatch_name() with the watcher id this function
522 * If the name vanishes or appears (for example the application owning
523 * the name could restart), the handlers are also invoked. If the
524 * #GDBusConnection that is used for watching the name disconnects, then
525 * @name_vanished_handler is invoked since it is no longer
526 * possible to access the name.
528 * Another guarantee is that invocations of @name_appeared_handler
529 * and @name_vanished_handler are guaranteed to alternate; that
530 * is, if @name_appeared_handler is invoked then you are
531 * guaranteed that the next time one of the handlers is invoked, it
532 * will be @name_vanished_handler. The reverse is also true.
534 * This behavior makes it very simple to write applications that wants
535 * to take action when a certain name exists, see <xref
536 * linkend="gdbus-watching-names"/>. Basically, the application
537 * should create object proxies in @name_appeared_handler and destroy
538 * them again (if any) in @name_vanished_handler.
540 * Returns: An identifier (never 0) that an be used with
541 * g_bus_unwatch_name() to stop watching the name.
546 g_bus_watch_name (GBusType bus_type
,
548 GBusNameWatcherFlags flags
,
549 GBusNameAppearedCallback name_appeared_handler
,
550 GBusNameVanishedCallback name_vanished_handler
,
552 GDestroyNotify user_data_free_func
)
556 g_return_val_if_fail (g_dbus_is_name (name
), 0);
560 client
= g_new0 (Client
, 1);
561 client
->ref_count
= 1;
562 client
->id
= next_global_id
++; /* TODO: uh oh, handle overflow */
563 client
->name
= g_strdup (name
);
564 client
->flags
= flags
;
565 client
->name_appeared_handler
= name_appeared_handler
;
566 client
->name_vanished_handler
= name_vanished_handler
;
567 client
->user_data
= user_data
;
568 client
->user_data_free_func
= user_data_free_func
;
569 client
->main_context
= g_main_context_get_thread_default ();
570 if (client
->main_context
!= NULL
)
571 g_main_context_ref (client
->main_context
);
573 if (map_id_to_client
== NULL
)
575 map_id_to_client
= g_hash_table_new (g_direct_hash
, g_direct_equal
);
577 g_hash_table_insert (map_id_to_client
,
578 GUINT_TO_POINTER (client
->id
),
584 client_ref (client
));
592 * g_bus_watch_name_on_connection:
593 * @connection: A #GDBusConnection.
594 * @name: The name (well-known or unique) to watch.
595 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
596 * @name_appeared_handler: Handler to invoke when @name is known to exist or %NULL.
597 * @name_vanished_handler: Handler to invoke when @name is known to not exist or %NULL.
598 * @user_data: User data to pass to handlers.
599 * @user_data_free_func: Function for freeing @user_data or %NULL.
601 * Like g_bus_watch_name() but takes a #GDBusConnection instead of a
604 * Returns: An identifier (never 0) that an be used with
605 * g_bus_unwatch_name() to stop watching the name.
609 guint
g_bus_watch_name_on_connection (GDBusConnection
*connection
,
611 GBusNameWatcherFlags flags
,
612 GBusNameAppearedCallback name_appeared_handler
,
613 GBusNameVanishedCallback name_vanished_handler
,
615 GDestroyNotify user_data_free_func
)
619 g_return_val_if_fail (G_IS_DBUS_CONNECTION (connection
), 0);
620 g_return_val_if_fail (g_dbus_is_name (name
), 0);
624 client
= g_new0 (Client
, 1);
625 client
->ref_count
= 1;
626 client
->id
= next_global_id
++; /* TODO: uh oh, handle overflow */
627 client
->name
= g_strdup (name
);
628 client
->flags
= flags
;
629 client
->name_appeared_handler
= name_appeared_handler
;
630 client
->name_vanished_handler
= name_vanished_handler
;
631 client
->user_data
= user_data
;
632 client
->user_data_free_func
= user_data_free_func
;
633 client
->main_context
= g_main_context_get_thread_default ();
634 if (client
->main_context
!= NULL
)
635 g_main_context_ref (client
->main_context
);
637 if (map_id_to_client
== NULL
)
638 map_id_to_client
= g_hash_table_new (g_direct_hash
, g_direct_equal
);
640 g_hash_table_insert (map_id_to_client
,
641 GUINT_TO_POINTER (client
->id
),
644 client
->connection
= g_object_ref (connection
);
647 has_connection (client
);
653 GClosure
*name_appeared_closure
;
654 GClosure
*name_vanished_closure
;
657 static WatchNameData
*
658 watch_name_data_new (GClosure
*name_appeared_closure
,
659 GClosure
*name_vanished_closure
)
663 data
= g_new0 (WatchNameData
, 1);
665 if (name_appeared_closure
!= NULL
)
667 data
->name_appeared_closure
= g_closure_ref (name_appeared_closure
);
668 g_closure_sink (name_appeared_closure
);
669 if (G_CLOSURE_NEEDS_MARSHAL (name_appeared_closure
))
670 g_closure_set_marshal (name_appeared_closure
, g_cclosure_marshal_generic
);
673 if (name_vanished_closure
!= NULL
)
675 data
->name_vanished_closure
= g_closure_ref (name_vanished_closure
);
676 g_closure_sink (name_vanished_closure
);
677 if (G_CLOSURE_NEEDS_MARSHAL (name_vanished_closure
))
678 g_closure_set_marshal (name_vanished_closure
, g_cclosure_marshal_generic
);
685 watch_with_closures_on_name_appeared (GDBusConnection
*connection
,
687 const gchar
*name_owner
,
690 WatchNameData
*data
= user_data
;
691 GValue params
[3] = { { 0, }, { 0, }, { 0, } };
693 g_value_init (¶ms
[0], G_TYPE_DBUS_CONNECTION
);
694 g_value_set_object (¶ms
[0], connection
);
696 g_value_init (¶ms
[1], G_TYPE_STRING
);
697 g_value_set_string (¶ms
[1], name
);
699 g_value_init (¶ms
[2], G_TYPE_STRING
);
700 g_value_set_string (¶ms
[2], name_owner
);
702 g_closure_invoke (data
->name_appeared_closure
, NULL
, 3, params
, NULL
);
704 g_value_unset (params
+ 0);
705 g_value_unset (params
+ 1);
706 g_value_unset (params
+ 2);
710 watch_with_closures_on_name_vanished (GDBusConnection
*connection
,
714 WatchNameData
*data
= user_data
;
715 GValue params
[2] = { { 0, }, { 0, } };
717 g_value_init (¶ms
[0], G_TYPE_DBUS_CONNECTION
);
718 g_value_set_object (¶ms
[0], connection
);
720 g_value_init (¶ms
[1], G_TYPE_STRING
);
721 g_value_set_string (¶ms
[1], name
);
723 g_closure_invoke (data
->name_vanished_closure
, NULL
, 2, params
, NULL
);
725 g_value_unset (params
+ 0);
726 g_value_unset (params
+ 1);
730 bus_watch_name_free_func (gpointer user_data
)
732 WatchNameData
*data
= user_data
;
734 if (data
->name_appeared_closure
!= NULL
)
735 g_closure_unref (data
->name_appeared_closure
);
737 if (data
->name_vanished_closure
!= NULL
)
738 g_closure_unref (data
->name_vanished_closure
);
744 * g_bus_watch_name_with_closures:
745 * @bus_type: The type of bus to watch a name on.
746 * @name: The name (well-known or unique) to watch.
747 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
748 * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known
750 * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known
751 * to not exist or %NULL.
753 * Version of g_bus_watch_name() using closures instead of callbacks for
754 * easier binding in other languages.
756 * Returns: An identifier (never 0) that an be used with
757 * g_bus_unwatch_name() to stop watching the name.
759 * Rename to: g_bus_watch_name
764 g_bus_watch_name_with_closures (GBusType bus_type
,
766 GBusNameWatcherFlags flags
,
767 GClosure
*name_appeared_closure
,
768 GClosure
*name_vanished_closure
)
770 return g_bus_watch_name (bus_type
,
773 name_appeared_closure
!= NULL
? watch_with_closures_on_name_appeared
: NULL
,
774 name_vanished_closure
!= NULL
? watch_with_closures_on_name_vanished
: NULL
,
775 watch_name_data_new (name_appeared_closure
, name_vanished_closure
),
776 bus_watch_name_free_func
);
780 * g_bus_watch_name_on_connection_with_closures:
781 * @connection: A #GDBusConnection.
782 * @name: The name (well-known or unique) to watch.
783 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
784 * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known
786 * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known
787 * to not exist or %NULL.
789 * Version of g_bus_watch_name_on_connection() using closures instead of callbacks for
790 * easier binding in other languages.
792 * Returns: An identifier (never 0) that an be used with
793 * g_bus_unwatch_name() to stop watching the name.
795 * Rename to: g_bus_watch_name_on_connection
799 guint
g_bus_watch_name_on_connection_with_closures (
800 GDBusConnection
*connection
,
802 GBusNameWatcherFlags flags
,
803 GClosure
*name_appeared_closure
,
804 GClosure
*name_vanished_closure
)
806 return g_bus_watch_name_on_connection (connection
,
809 name_appeared_closure
!= NULL
? watch_with_closures_on_name_appeared
: NULL
,
810 name_vanished_closure
!= NULL
? watch_with_closures_on_name_vanished
: NULL
,
811 watch_name_data_new (name_appeared_closure
, name_vanished_closure
),
812 bus_watch_name_free_func
);
816 * g_bus_unwatch_name:
817 * @watcher_id: An identifier obtained from g_bus_watch_name()
819 * Stops watching a name.
824 g_bus_unwatch_name (guint watcher_id
)
828 g_return_if_fail (watcher_id
> 0);
833 if (watcher_id
== 0 ||
834 map_id_to_client
== NULL
||
835 (client
= g_hash_table_lookup (map_id_to_client
, GUINT_TO_POINTER (watcher_id
))) == NULL
)
837 g_warning ("Invalid id %d passed to g_bus_unwatch_name()", watcher_id
);
841 client
->cancelled
= TRUE
;
842 g_warn_if_fail (g_hash_table_remove (map_id_to_client
, GUINT_TO_POINTER (watcher_id
)));
847 /* do callback without holding lock */
850 client_unref (client
);