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>
27 #include "gdbusutils.h"
28 #include "gdbusconnection.h"
29 #include "gdbusnamewatching.h"
30 #include "gdbusproxywatching.h"
31 #include "gdbuserror.h"
32 #include "gdbusprivate.h"
33 #include "gdbusproxy.h"
34 #include "gcancellable.h"
40 * SECTION:gdbusproxywatching
41 * @title: Watching Proxies
42 * @short_description: Simple API for watching proxies
45 * Convenience API for watching bus proxies.
47 * <example id="gdbus-watching-proxy"><title>Simple application watching a proxy</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-watch-proxy.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
50 /* ---------------------------------------------------------------------------------------------------- */
52 G_LOCK_DEFINE_STATIC (lock);
54 static guint next_global_id = 1;
55 static GHashTable *map_id_to_client = NULL;
57 /* ---------------------------------------------------------------------------------------------------- */
62 GBusProxyAppearedCallback proxy_appeared_handler;
63 GBusProxyVanishedCallback proxy_vanished_handler;
65 GDestroyNotify user_data_free_func;
66 GMainContext *main_context;
70 GDBusConnection *connection;
71 guint name_watcher_id;
73 GCancellable *cancellable;
76 gchar *interface_name;
78 GDBusProxyFlags proxy_flags;
81 gboolean initial_construction;
85 client_unref (Client *client)
87 /* ensure we're only called from g_bus_unwatch_proxy */
88 g_assert (client->name_watcher_id == 0);
90 g_free (client->name_owner);
91 if (client->connection != NULL)
92 g_object_unref (client->connection);
93 if (client->proxy != NULL)
94 g_object_unref (client->proxy);
96 g_free (client->name);
97 g_free (client->object_path);
98 g_free (client->interface_name);
100 if (client->main_context != NULL)
101 g_main_context_unref (client->main_context);
103 if (client->user_data_free_func != NULL)
104 client->user_data_free_func (client->user_data);
108 /* ---------------------------------------------------------------------------------------------------- */
111 proxy_constructed_cb (GObject *source_object,
115 Client *client = user_data;
120 proxy = g_dbus_proxy_new_finish (res, &error);
123 /* g_warning ("error while constructing proxy: %s", error->message); */
124 g_error_free (error);
126 /* handle initial construction, send out vanished if the name
127 * is there but we constructing a proxy fails
129 if (client->initial_construction)
131 if (client->proxy_vanished_handler != NULL)
133 client->proxy_vanished_handler (client->connection,
137 client->initial_construction = FALSE;
142 g_assert (client->proxy == NULL);
143 g_assert (client->cancellable != NULL);
144 client->proxy = G_DBUS_PROXY (proxy);
146 g_object_unref (client->cancellable);
147 client->cancellable = NULL;
149 /* perform callback */
150 if (client->proxy_appeared_handler != NULL)
152 client->proxy_appeared_handler (client->connection,
158 client->initial_construction = FALSE;
163 on_name_appeared (GDBusConnection *connection,
165 const gchar *name_owner,
168 Client *client = user_data;
170 //g_debug ("\n\nname appeared (owner `%s')", name_owner);
173 g_assert (client->name_owner == NULL);
174 g_assert (client->connection == NULL);
175 g_assert (client->cancellable == NULL);
177 client->name_owner = g_strdup (name_owner);
178 client->connection = g_object_ref (connection);
179 client->cancellable = g_cancellable_new ();
181 g_dbus_proxy_new (client->connection,
182 client->interface_type,
184 NULL, /* GDBusInterfaceInfo */
187 client->interface_name,
189 proxy_constructed_cb,
194 on_name_vanished (GDBusConnection *connection,
198 Client *client = user_data;
200 /*g_debug ("\n\nname vanished");*/
202 g_free (client->name_owner);
203 if (client->connection != NULL)
204 g_object_unref (client->connection);
205 client->name_owner = NULL;
206 client->connection = NULL;
208 /* free the proxy if we have it */
209 if (client->proxy != NULL)
211 g_assert (client->cancellable == NULL);
213 g_object_unref (client->proxy);
214 client->proxy = NULL;
216 /* if we have the proxy, it means we last sent out a 'appeared'
217 * callback - so send out a 'vanished' callback
219 if (client->proxy_vanished_handler != NULL)
221 client->proxy_vanished_handler (client->connection,
225 client->initial_construction = FALSE;
229 /* otherwise cancel construction of the proxy if applicable */
230 if (client->cancellable != NULL)
232 g_cancellable_cancel (client->cancellable);
233 g_object_unref (client->cancellable);
234 client->cancellable = NULL;
238 /* handle initial construction, send out vanished if
239 * the name isn't there
241 if (client->initial_construction)
243 if (client->proxy_vanished_handler != NULL)
245 client->proxy_vanished_handler (client->connection,
249 client->initial_construction = FALSE;
257 * @bus_type: The type of bus to watch a name on.
258 * @name: The name (well-known or unique) to watch.
259 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
260 * @object_path: The object path of the remote object to watch.
261 * @interface_name: The D-Bus interface name for the proxy.
262 * @interface_type: The #GType for the kind of proxy to create. This must be a #GDBusProxy derived type.
263 * @proxy_flags: Flags from #GDBusProxyFlags to use when constructing the proxy.
264 * @proxy_appeared_handler: Handler to invoke when @name is known to exist and the
265 * requested proxy is available.
266 * @proxy_vanished_handler: Handler to invoke when @name is known to not exist
267 * and the previously created proxy is no longer available.
268 * @user_data: User data to pass to handlers.
269 * @user_data_free_func: Function for freeing @user_data or %NULL.
271 * Starts watching a remote object at @object_path owned by @name on
272 * the bus specified by @bus_type. When the object is available, a
273 * #GDBusProxy (or derived class cf. @interface_type) instance is
274 * constructed for the @interface_name D-Bus interface and then
275 * @proxy_appeared_handler will be called when the proxy is ready and
276 * all properties have been loaded. When @name vanishes,
277 * @proxy_vanished_handler is called.
279 * This function makes it very simple to write applications that wants
280 * to watch a well-known remote object on a well-known name, see <xref
281 * linkend="gdbus-watching-proxy"/>. Basically, the application simply
282 * starts using the proxy when @proxy_appeared_handler is called and
283 * stops using it when @proxy_vanished_handler is called. Callbacks
284 * will be invoked in the <link
285 * linkend="g-main-context-push-thread-default">thread-default main
286 * loop</link> of the thread you are calling this function from.
288 * Applications typically use this function to watch the
289 * <quote>manager</quote> object of a well-known name. Upon acquiring
290 * a proxy for the manager object, applications typically construct
291 * additional proxies in response to the result of enumeration methods
292 * on the manager object.
294 * Many of the comments that apply to g_bus_watch_name() also apply
295 * here. For example, you are guaranteed that one of the handlers will
296 * be invoked (on the main thread) after calling this function and
297 * also that the two handlers alternate. When you are done watching the
298 * proxy, just call g_bus_unwatch_proxy().
300 * Returns: An identifier (never 0) that can be used with
301 * g_bus_unwatch_proxy() to stop watching the remote object.
306 g_bus_watch_proxy (GBusType bus_type,
308 GBusNameWatcherFlags flags,
309 const gchar *object_path,
310 const gchar *interface_name,
311 GType interface_type,
312 GDBusProxyFlags proxy_flags,
313 GBusProxyAppearedCallback proxy_appeared_handler,
314 GBusProxyVanishedCallback proxy_vanished_handler,
316 GDestroyNotify user_data_free_func)
320 g_return_val_if_fail (g_dbus_is_name (name), 0);
321 g_return_val_if_fail (g_variant_is_object_path (object_path), 0);
322 g_return_val_if_fail (g_dbus_is_interface_name (interface_name), 0);
323 g_return_val_if_fail (g_type_is_a (interface_type, G_TYPE_DBUS_PROXY), 0);
327 client = g_new0 (Client, 1);
328 client->id = next_global_id++; /* TODO: uh oh, handle overflow */
329 client->name = g_strdup (name);
330 client->proxy_appeared_handler = proxy_appeared_handler;
331 client->proxy_vanished_handler = proxy_vanished_handler;
332 client->user_data = user_data;
333 client->user_data_free_func = user_data_free_func;
334 client->main_context = g_main_context_get_thread_default ();
335 if (client->main_context != NULL)
336 g_main_context_ref (client->main_context);
337 client->name_watcher_id = g_bus_watch_name (bus_type,
345 client->object_path = g_strdup (object_path);
346 client->interface_name = g_strdup (interface_name);
347 client->interface_type = interface_type;
348 client->proxy_flags = proxy_flags;
349 client->initial_construction = TRUE;
351 if (map_id_to_client == NULL)
353 map_id_to_client = g_hash_table_new (g_direct_hash, g_direct_equal);
355 g_hash_table_insert (map_id_to_client,
356 GUINT_TO_POINTER (client->id),
365 * g_bus_watch_proxy_on_connection:
366 * @connection: A #GDBusConnection that is not closed.
367 * @name: The name (well-known or unique) to watch.
368 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
369 * @object_path: The object path of the remote object to watch.
370 * @interface_name: The D-Bus interface name for the proxy.
371 * @interface_type: The #GType for the kind of proxy to create. This must be a #GDBusProxy derived type.
372 * @proxy_flags: Flags from #GDBusProxyFlags to use when constructing the proxy.
373 * @proxy_appeared_handler: Handler to invoke when @name is known to exist and the
374 * requested proxy is available.
375 * @proxy_vanished_handler: Handler to invoke when @name is known to not exist
376 * and the previously created proxy is no longer available.
377 * @user_data: User data to pass to handlers.
378 * @user_data_free_func: Function for freeing @user_data or %NULL.
380 * Like g_bus_watch_proxy() but takes a #GDBusConnection instead of a
383 * Returns: An identifier (never 0) that can be used with
384 * g_bus_unwatch_proxy() to stop watching the remote object.
389 g_bus_watch_proxy_on_connection (GDBusConnection *connection,
391 GBusNameWatcherFlags flags,
392 const gchar *object_path,
393 const gchar *interface_name,
394 GType interface_type,
395 GDBusProxyFlags proxy_flags,
396 GBusProxyAppearedCallback proxy_appeared_handler,
397 GBusProxyVanishedCallback proxy_vanished_handler,
399 GDestroyNotify user_data_free_func)
403 g_return_val_if_fail (G_IS_DBUS_CONNECTION (connection), 0);
404 g_return_val_if_fail (g_dbus_is_name (name), 0);
405 g_return_val_if_fail (g_variant_is_object_path (object_path), 0);
406 g_return_val_if_fail (g_dbus_is_interface_name (interface_name), 0);
407 g_return_val_if_fail (g_type_is_a (interface_type, G_TYPE_DBUS_PROXY), 0);
411 client = g_new0 (Client, 1);
412 client->id = next_global_id++; /* TODO: uh oh, handle overflow */
413 client->name = g_strdup (name);
414 client->proxy_appeared_handler = proxy_appeared_handler;
415 client->proxy_vanished_handler = proxy_vanished_handler;
416 client->user_data = user_data;
417 client->user_data_free_func = user_data_free_func;
418 client->main_context = g_main_context_get_thread_default ();
419 if (client->main_context != NULL)
420 g_main_context_ref (client->main_context);
421 client->name_watcher_id = g_bus_watch_name_on_connection (connection,
429 client->object_path = g_strdup (object_path);
430 client->interface_name = g_strdup (interface_name);
431 client->interface_type = interface_type;
432 client->proxy_flags = proxy_flags;
433 client->initial_construction = TRUE;
435 if (map_id_to_client == NULL)
437 map_id_to_client = g_hash_table_new (g_direct_hash, g_direct_equal);
439 g_hash_table_insert (map_id_to_client,
440 GUINT_TO_POINTER (client->id),
450 * g_bus_unwatch_proxy:
451 * @watcher_id: An identifier obtained from g_bus_watch_proxy()
453 * Stops watching proxy.
458 g_bus_unwatch_proxy (guint watcher_id)
462 g_return_if_fail (watcher_id > 0);
467 if (watcher_id == 0 ||
468 map_id_to_client == NULL ||
469 (client = g_hash_table_lookup (map_id_to_client, GUINT_TO_POINTER (watcher_id))) == NULL)
471 g_warning ("Invalid id %d passed to g_bus_unwatch_proxy()", watcher_id);
475 g_warn_if_fail (g_hash_table_remove (map_id_to_client, GUINT_TO_POINTER (watcher_id)));
482 g_bus_unwatch_name (client->name_watcher_id);
483 client->name_watcher_id = 0;
484 client_unref (client);
488 #define __G_DBUS_PROXY_WATCHING_C__
489 #include "gioaliasdef.c"