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 <gobject/gvaluecollector.h>
30 #include "gdbusutils.h"
31 #include "gdbusproxy.h"
32 #include "gioenumtypes.h"
33 #include "gdbusconnection.h"
34 #include "gdbuserror.h"
35 #include "gdbusprivate.h"
36 #include "gio-marshal.h"
37 #include "ginitable.h"
38 #include "gasyncinitable.h"
40 #include "gasyncresult.h"
41 #include "gsimpleasyncresult.h"
48 * @short_description: Base class for proxies
51 * #GDBusProxy is a base class used for proxies to access a D-Bus
52 * interface on a remote object. A #GDBusProxy can only be constructed
53 * for unique name bus and does not track whether the name
54 * vanishes. Use g_bus_watch_proxy() to construct #GDBusProxy proxies
55 * for owners of a well-known names.
57 * By default, #GDBusProxy will cache all properties (and listen for
58 * their changes) of the remote object, and proxy all signals that gets
59 * emitted. This behaviour can be changed by passing suitable
60 * #GDBusProxyFlags when the proxy is created.
62 * The generic #GDBusProxy::g-properties-changed and #GDBusProxy::g-signal
63 * signals are not very convenient to work with. Therefore, the recommended
64 * way of working with proxies is to subclass #GDBusProxy, and have
65 * more natural properties and signals in your derived class. The
66 * @interface_type argument of g_bus_watch_proxy() lets you obtain
67 * instances of your derived class when using the high-level API.
69 * See <xref linkend="gdbus-example-proxy-subclass"/> for an example.
72 struct _GDBusProxyPrivate
74 GDBusConnection *connection;
75 GDBusProxyFlags flags;
76 gchar *unique_bus_name;
78 gchar *interface_name;
81 /* gchar* -> GVariant* */
82 GHashTable *properties;
84 GDBusInterfaceInfo *expected_interface;
86 guint properties_changed_subscriber_id;
87 guint signals_subscriber_id;
96 PROP_G_UNIQUE_BUS_NAME,
99 PROP_G_INTERFACE_NAME,
100 PROP_G_DEFAULT_TIMEOUT,
101 PROP_G_INTERFACE_INFO
106 PROPERTIES_CHANGED_SIGNAL,
111 static void g_dbus_proxy_constructed (GObject *object);
113 guint signals[LAST_SIGNAL] = {0};
115 static void initable_iface_init (GInitableIface *initable_iface);
116 static void async_initable_iface_init (GAsyncInitableIface *async_initable_iface);
118 G_DEFINE_TYPE_WITH_CODE (GDBusProxy, g_dbus_proxy, G_TYPE_OBJECT,
119 G_IMPLEMENT_INTERFACE (G_TYPE_INITABLE, initable_iface_init)
120 G_IMPLEMENT_INTERFACE (G_TYPE_ASYNC_INITABLE, async_initable_iface_init)
124 g_dbus_proxy_finalize (GObject *object)
126 GDBusProxy *proxy = G_DBUS_PROXY (object);
128 if (proxy->priv->properties_changed_subscriber_id > 0)
129 g_dbus_connection_signal_unsubscribe (proxy->priv->connection,
130 proxy->priv->properties_changed_subscriber_id);
132 if (proxy->priv->signals_subscriber_id > 0)
133 g_dbus_connection_signal_unsubscribe (proxy->priv->connection,
134 proxy->priv->signals_subscriber_id);
136 g_object_unref (proxy->priv->connection);
137 g_free (proxy->priv->unique_bus_name);
138 g_free (proxy->priv->object_path);
139 g_free (proxy->priv->interface_name);
140 if (proxy->priv->properties != NULL)
141 g_hash_table_unref (proxy->priv->properties);
143 if (proxy->priv->expected_interface != NULL)
144 g_dbus_interface_info_unref (proxy->priv->expected_interface);
146 G_OBJECT_CLASS (g_dbus_proxy_parent_class)->finalize (object);
150 g_dbus_proxy_get_property (GObject *object,
155 GDBusProxy *proxy = G_DBUS_PROXY (object);
159 case PROP_G_CONNECTION:
160 g_value_set_object (value, proxy->priv->connection);
164 g_value_set_flags (value, proxy->priv->flags);
167 case PROP_G_UNIQUE_BUS_NAME:
168 g_value_set_string (value, proxy->priv->unique_bus_name);
171 case PROP_G_OBJECT_PATH:
172 g_value_set_string (value, proxy->priv->object_path);
175 case PROP_G_INTERFACE_NAME:
176 g_value_set_string (value, proxy->priv->interface_name);
179 case PROP_G_DEFAULT_TIMEOUT:
180 g_value_set_int (value, proxy->priv->timeout_msec);
183 case PROP_G_INTERFACE_INFO:
184 g_value_set_boxed (value, g_dbus_proxy_get_interface_info (proxy));
188 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
194 g_dbus_proxy_set_property (GObject *object,
199 GDBusProxy *proxy = G_DBUS_PROXY (object);
203 case PROP_G_CONNECTION:
204 proxy->priv->connection = g_value_dup_object (value);
208 proxy->priv->flags = g_value_get_flags (value);
211 case PROP_G_UNIQUE_BUS_NAME:
212 proxy->priv->unique_bus_name = g_value_dup_string (value);
215 case PROP_G_OBJECT_PATH:
216 proxy->priv->object_path = g_value_dup_string (value);
219 case PROP_G_INTERFACE_NAME:
220 proxy->priv->interface_name = g_value_dup_string (value);
223 case PROP_G_DEFAULT_TIMEOUT:
224 g_dbus_proxy_set_default_timeout (proxy, g_value_get_int (value));
227 case PROP_G_INTERFACE_INFO:
228 g_dbus_proxy_set_interface_info (proxy, g_value_get_boxed (value));
232 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
238 g_dbus_proxy_class_init (GDBusProxyClass *klass)
240 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
242 gobject_class->finalize = g_dbus_proxy_finalize;
243 gobject_class->set_property = g_dbus_proxy_set_property;
244 gobject_class->get_property = g_dbus_proxy_get_property;
245 gobject_class->constructed = g_dbus_proxy_constructed;
247 /* Note that all property names are prefixed to avoid collisions with D-Bus property names
248 * in derived classes */
251 * GDBusProxy:g-interface-info:
253 * Ensure that interactions with this proxy conform to the given
254 * interface. For example, when completing a method call, if the
255 * type signature of the message isn't what's expected, the given
256 * #GError is set. Signals that have a type signature mismatch are
261 g_object_class_install_property (gobject_class,
262 PROP_G_INTERFACE_INFO,
263 g_param_spec_boxed ("g-interface-info",
264 P_("Interface Information"),
265 P_("Interface Information"),
266 G_TYPE_DBUS_INTERFACE_INFO,
269 G_PARAM_STATIC_NAME |
270 G_PARAM_STATIC_BLURB |
271 G_PARAM_STATIC_NICK));
274 * GDBusProxy:g-connection:
276 * The #GDBusConnection the proxy is for.
280 g_object_class_install_property (gobject_class,
282 g_param_spec_object ("g-connection",
284 P_("The connection the proxy is for"),
285 G_TYPE_DBUS_CONNECTION,
288 G_PARAM_CONSTRUCT_ONLY |
289 G_PARAM_STATIC_NAME |
290 G_PARAM_STATIC_BLURB |
291 G_PARAM_STATIC_NICK));
294 * GDBusProxy:g-flags:
296 * Flags from the #GDBusProxyFlags enumeration.
300 g_object_class_install_property (gobject_class,
302 g_param_spec_flags ("g-flags",
304 P_("Flags for the proxy"),
305 G_TYPE_DBUS_PROXY_FLAGS,
306 G_DBUS_PROXY_FLAGS_NONE,
309 G_PARAM_CONSTRUCT_ONLY |
310 G_PARAM_STATIC_NAME |
311 G_PARAM_STATIC_BLURB |
312 G_PARAM_STATIC_NICK));
315 * GDBusProxy:g-unique-bus-name:
317 * The unique bus name the proxy is for.
321 g_object_class_install_property (gobject_class,
322 PROP_G_UNIQUE_BUS_NAME,
323 g_param_spec_string ("g-unique-bus-name",
324 P_("g-unique-bus-name"),
325 P_("The unique bus name the proxy is for"),
329 G_PARAM_CONSTRUCT_ONLY |
330 G_PARAM_STATIC_NAME |
331 G_PARAM_STATIC_BLURB |
332 G_PARAM_STATIC_NICK));
335 * GDBusProxy:g-object-path:
337 * The object path the proxy is for.
341 g_object_class_install_property (gobject_class,
343 g_param_spec_string ("g-object-path",
345 P_("The object path the proxy is for"),
349 G_PARAM_CONSTRUCT_ONLY |
350 G_PARAM_STATIC_NAME |
351 G_PARAM_STATIC_BLURB |
352 G_PARAM_STATIC_NICK));
355 * GDBusProxy:g-interface-name:
357 * The D-Bus interface name the proxy is for.
361 g_object_class_install_property (gobject_class,
362 PROP_G_INTERFACE_NAME,
363 g_param_spec_string ("g-interface-name",
364 P_("g-interface-name"),
365 P_("The D-Bus interface name the proxy is for"),
369 G_PARAM_CONSTRUCT_ONLY |
370 G_PARAM_STATIC_NAME |
371 G_PARAM_STATIC_BLURB |
372 G_PARAM_STATIC_NICK));
375 * GDBusProxy:g-default-timeout:
377 * The timeout to use if -1 (specifying default timeout) is passed
378 * as @timeout_msec in the g_dbus_proxy_call() and
379 * g_dbus_proxy_call_sync() functions.
381 * This allows applications to set a proxy-wide timeout for all
382 * remote method invocations on the proxy. If this property is -1,
383 * the default timeout (typically 25 seconds) is used. If set to
384 * %G_MAXINT, then no timeout is used.
388 g_object_class_install_property (gobject_class,
389 PROP_G_DEFAULT_TIMEOUT,
390 g_param_spec_int ("g-default-timeout",
391 P_("Default Timeout"),
392 P_("Timeout for remote method invocation"),
399 G_PARAM_STATIC_NAME |
400 G_PARAM_STATIC_BLURB |
401 G_PARAM_STATIC_NICK));
404 * GDBusProxy::g-properties-changed:
405 * @proxy: The #GDBusProxy emitting the signal.
406 * @changed_properties: A #GVariant containing the properties that changed
407 * @invalidated_properties: A %NULL terminated array of properties that was invalidated
409 * Emitted when one or more D-Bus properties on @proxy changes. The
410 * local cache has already been updated when this signal fires. Note
411 * that both @changed_properties and @invalidated_properties are
412 * guaranteed to never be %NULL (either may be empty though).
414 * This signal corresponds to the
415 * <literal>PropertiesChanged</literal> D-Bus signal on the
416 * <literal>org.freedesktop.DBus.Properties</literal> interface.
420 signals[PROPERTIES_CHANGED_SIGNAL] = g_signal_new ("g-properties-changed",
423 G_STRUCT_OFFSET (GDBusProxyClass, g_properties_changed),
426 _gio_marshal_VOID__BOXED_BOXED,
430 G_TYPE_STRV | G_SIGNAL_TYPE_STATIC_SCOPE);
433 * GDBusProxy::g-signal:
434 * @proxy: The #GDBusProxy emitting the signal.
435 * @sender_name: The sender of the signal or %NULL if the connection is not a bus connection.
436 * @signal_name: The name of the signal.
437 * @parameters: A #GVariant tuple with parameters for the signal.
439 * Emitted when a signal from the remote object and interface that @proxy is for, has been received.
443 signals[SIGNAL_SIGNAL] = g_signal_new ("g-signal",
446 G_STRUCT_OFFSET (GDBusProxyClass, g_signal),
449 _gio_marshal_VOID__STRING_STRING_BOXED,
457 g_type_class_add_private (klass, sizeof (GDBusProxyPrivate));
461 g_dbus_proxy_init (GDBusProxy *proxy)
463 proxy->priv = G_TYPE_INSTANCE_GET_PRIVATE (proxy, G_TYPE_DBUS_PROXY, GDBusProxyPrivate);
464 proxy->priv->properties = g_hash_table_new_full (g_str_hash,
467 (GDestroyNotify) g_variant_unref);
470 /* ---------------------------------------------------------------------------------------------------- */
473 * g_dbus_proxy_get_cached_property_names:
474 * @proxy: A #GDBusProxy.
476 * Gets the names of all cached properties on @proxy.
478 * Returns: A %NULL-terminated array of strings or %NULL if @proxy has
479 * no cached properties. Free the returned array with g_strfreev().
484 g_dbus_proxy_get_cached_property_names (GDBusProxy *proxy)
491 g_return_val_if_fail (G_IS_DBUS_PROXY (proxy), NULL);
494 if (g_hash_table_size (proxy->priv->properties) == 0)
497 p = g_ptr_array_new ();
499 g_hash_table_iter_init (&iter, proxy->priv->properties);
500 while (g_hash_table_iter_next (&iter, (gpointer) &key, NULL))
501 g_ptr_array_add (p, g_strdup (key));
502 g_ptr_array_sort (p, (GCompareFunc) g_strcmp0);
503 g_ptr_array_add (p, NULL);
505 names = (gchar **) g_ptr_array_free (p, FALSE);
511 static const GDBusPropertyInfo *
512 lookup_property_info_or_warn (GDBusProxy *proxy,
513 const gchar *property_name)
515 const GDBusPropertyInfo *info;
517 if (proxy->priv->expected_interface == NULL)
520 info = g_dbus_interface_info_lookup_property (proxy->priv->expected_interface, property_name);
523 g_warning ("Trying to lookup property %s which isn't in expected interface %s",
525 proxy->priv->expected_interface->name);
532 * g_dbus_proxy_get_cached_property:
533 * @proxy: A #GDBusProxy.
534 * @property_name: Property name.
536 * Looks up the value for a property from the cache. This call does no
539 * If @proxy has an expected interface (see
540 * #GDBusProxy:g-interface-info), then @property_name (for existence)
541 * is checked against it.
543 * Returns: A reference to the #GVariant instance that holds the value
544 * for @property_name or %NULL if the value is not in the cache. The
545 * returned reference must be freed with g_variant_unref().
550 g_dbus_proxy_get_cached_property (GDBusProxy *proxy,
551 const gchar *property_name)
555 g_return_val_if_fail (G_IS_DBUS_PROXY (proxy), NULL);
556 g_return_val_if_fail (property_name != NULL, NULL);
558 value = g_hash_table_lookup (proxy->priv->properties, property_name);
561 const GDBusPropertyInfo *info;
562 info = lookup_property_info_or_warn (proxy, property_name);
567 g_variant_ref (value);
574 * g_dbus_proxy_set_cached_property:
575 * @proxy: A #GDBusProxy
576 * @property_name: Property name.
577 * @value: Value for the property or %NULL to remove it from the cache.
579 * If @value is not %NULL, sets the cached value for the property with
580 * name @property_name to the value in @value.
582 * If @value is %NULL, then the cached value is removed from the
585 * If @proxy has an expected interface (see
586 * #GDBusProxy:g-interface-info), then @property_name (for existence)
587 * and @value (for the type) is checked against it.
589 * If the @value #GVariant is floating, it is consumed. This allows
590 * convenient 'inline' use of g_variant_new(), e.g.
592 * g_dbus_proxy_set_cached_property (proxy,
594 * g_variant_new ("(si)",
599 * Normally you will not need to use this method since @proxy is
600 * tracking changes using the
601 * <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
602 * D-Bus signal. However, for performance reasons an object may decide
603 * to not use this signal for some properties and instead use a
604 * proprietary out-of-band mechanism to transmit changes.
606 * As a concrete example, consider an object with a property
607 * <literal>ChatroomParticipants</literal> which is an array of
608 * strings. Instead of transmitting the same (long) array every time
609 * the property changes, it is more efficient to only transmit the
610 * delta using e.g. signals <literal>ChatroomParticipantJoined(String
611 * name)</literal> and <literal>ChatroomParticipantParted(String
617 g_dbus_proxy_set_cached_property (GDBusProxy *proxy,
618 const gchar *property_name,
621 const GDBusPropertyInfo *info;
623 g_return_if_fail (G_IS_DBUS_PROXY (proxy));
624 g_return_if_fail (property_name != NULL);
628 info = lookup_property_info_or_warn (proxy, property_name);
631 if (g_strcmp0 (info->signature, g_variant_get_type_string (value)) != 0)
633 g_warning (_("Trying to set property %s of type %s but according to the expected "
634 "interface the type is %s"),
636 g_variant_get_type_string (value),
641 g_hash_table_insert (proxy->priv->properties,
642 g_strdup (property_name),
643 g_variant_ref_sink (value));
647 g_hash_table_remove (proxy->priv->properties, property_name);
654 /* ---------------------------------------------------------------------------------------------------- */
657 on_signal_received (GDBusConnection *connection,
658 const gchar *sender_name,
659 const gchar *object_path,
660 const gchar *interface_name,
661 const gchar *signal_name,
662 GVariant *parameters,
665 GDBusProxy *proxy = G_DBUS_PROXY (user_data);
667 if (!proxy->priv->initialized)
670 g_signal_emit (proxy,
671 signals[SIGNAL_SIGNAL],
680 /* ---------------------------------------------------------------------------------------------------- */
683 on_properties_changed (GDBusConnection *connection,
684 const gchar *sender_name,
685 const gchar *object_path,
686 const gchar *interface_name,
687 const gchar *signal_name,
688 GVariant *parameters,
691 GDBusProxy *proxy = G_DBUS_PROXY (user_data);
693 const gchar *interface_name_for_signal;
694 GVariant *changed_properties;
695 gchar **invalidated_properties;
702 changed_properties = NULL;
703 invalidated_properties = NULL;
705 if (!proxy->priv->initialized)
708 if (!g_variant_is_of_type (parameters, G_VARIANT_TYPE ("(sa{sv}as)")))
710 g_warning ("Value for PropertiesChanged signal with type `%s' does not match `(sa{sv}as)'",
711 g_variant_get_type_string (parameters));
715 g_variant_get (parameters,
717 &interface_name_for_signal,
719 &invalidated_properties);
721 if (g_strcmp0 (interface_name_for_signal, proxy->priv->interface_name) != 0)
724 g_variant_iter_init (&iter, changed_properties);
725 while (g_variant_iter_next (&iter, "{sv}", &key, &value))
727 g_hash_table_insert (proxy->priv->properties,
728 key, /* adopts string */
729 value); /* adopts value */
732 for (n = 0; invalidated_properties[n] != NULL; n++)
734 g_hash_table_remove (proxy->priv->properties, invalidated_properties[n]);
738 g_signal_emit (proxy, signals[PROPERTIES_CHANGED_SIGNAL],
741 invalidated_properties);
744 if (changed_properties != NULL)
745 g_variant_unref (changed_properties);
746 g_free (invalidated_properties);
749 /* ---------------------------------------------------------------------------------------------------- */
752 g_dbus_proxy_constructed (GObject *object)
754 if (G_OBJECT_CLASS (g_dbus_proxy_parent_class)->constructed != NULL)
755 G_OBJECT_CLASS (g_dbus_proxy_parent_class)->constructed (object);
758 /* ---------------------------------------------------------------------------------------------------- */
761 subscribe_to_signals (GDBusProxy *proxy)
763 if (!(proxy->priv->flags & G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES))
765 /* subscribe to PropertiesChanged() */
766 proxy->priv->properties_changed_subscriber_id =
767 g_dbus_connection_signal_subscribe (proxy->priv->connection,
768 proxy->priv->unique_bus_name,
769 "org.freedesktop.DBus.Properties",
771 proxy->priv->object_path,
772 proxy->priv->interface_name,
773 on_properties_changed,
778 if (!(proxy->priv->flags & G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS))
780 /* subscribe to all signals for the object */
781 proxy->priv->signals_subscriber_id =
782 g_dbus_connection_signal_subscribe (proxy->priv->connection,
783 proxy->priv->unique_bus_name,
784 proxy->priv->interface_name,
786 proxy->priv->object_path,
794 /* ---------------------------------------------------------------------------------------------------- */
797 process_get_all_reply (GDBusProxy *proxy,
804 if (strcmp (g_variant_get_type_string (result), "(a{sv})") != 0)
806 g_warning ("Value for GetAll reply with type `%s' does not match `(a{sv})'",
807 g_variant_get_type_string (result));
811 g_variant_get (result, "(a{sv})", &iter);
812 while (g_variant_iter_next (iter, "{sv}", &key, &value))
814 //g_print ("got %s -> %s\n", key, g_variant_markup_print (value, FALSE, 0, 0));
816 g_hash_table_insert (proxy->priv->properties,
817 key, /* adopts string */
818 value); /* adopts value */
820 g_variant_iter_free (iter);
827 initable_init (GInitable *initable,
828 GCancellable *cancellable,
831 GDBusProxy *proxy = G_DBUS_PROXY (initable);
837 subscribe_to_signals (proxy);
839 if (!(proxy->priv->flags & G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES))
841 /* load all properties synchronously */
842 result = g_dbus_connection_call_sync (proxy->priv->connection,
843 proxy->priv->unique_bus_name,
844 proxy->priv->object_path,
845 "org.freedesktop.DBus.Properties",
847 g_variant_new ("(s)", proxy->priv->interface_name),
848 G_VARIANT_TYPE ("(a{sv})"),
849 G_DBUS_CALL_FLAGS_NONE,
855 /* We just ignore if GetAll() is failing. Because this might happen
856 * if the object has no properties at all. Or if the caller is
857 * not authorized to see the properties.
859 * Either way, apps can know about this by using
860 * get_cached_property_names() or get_cached_property().
862 * TODO: handle G_DBUS_DEBUG flag 'proxy' and, if enabled, log the
863 * fact that GetAll() failed
865 //g_debug ("error: %d %d %s", error->domain, error->code, error->message);
868 g_error_free (*error);
875 process_get_all_reply (proxy, result);
877 g_variant_unref (result);
883 proxy->priv->initialized = TRUE;
888 initable_iface_init (GInitableIface *initable_iface)
890 initable_iface->init = initable_init;
893 /* ---------------------------------------------------------------------------------------------------- */
896 get_all_cb (GDBusConnection *connection,
900 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (user_data);
905 result = g_dbus_connection_call_finish (connection,
910 /* We just ignore if GetAll() is failing. Because this might happen
911 * if the object has no properties at all. Or if the caller is
912 * not authorized to see the properties.
914 * Either way, apps can know about this by using
915 * get_cached_property_names() or get_cached_property().
917 * TODO: handle G_DBUS_DEBUG flag 'proxy' and, if enabled, log the
918 * fact that GetAll() failed
920 //g_debug ("error: %d %d %s", error->domain, error->code, error->message);
921 g_error_free (error);
925 g_simple_async_result_set_op_res_gpointer (simple,
927 (GDestroyNotify) g_variant_unref);
930 g_simple_async_result_complete_in_idle (simple);
931 g_object_unref (simple);
935 async_initable_init_async (GAsyncInitable *initable,
937 GCancellable *cancellable,
938 GAsyncReadyCallback callback,
941 GDBusProxy *proxy = G_DBUS_PROXY (initable);
942 GSimpleAsyncResult *simple;
944 simple = g_simple_async_result_new (G_OBJECT (proxy),
949 subscribe_to_signals (proxy);
951 if (!(proxy->priv->flags & G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES))
953 /* load all properties asynchronously */
954 g_dbus_connection_call (proxy->priv->connection,
955 proxy->priv->unique_bus_name,
956 proxy->priv->object_path,
957 "org.freedesktop.DBus.Properties",
959 g_variant_new ("(s)", proxy->priv->interface_name),
960 G_VARIANT_TYPE ("(a{sv})"),
961 G_DBUS_CALL_FLAGS_NONE,
964 (GAsyncReadyCallback) get_all_cb,
969 g_simple_async_result_complete_in_idle (simple);
970 g_object_unref (simple);
975 async_initable_init_finish (GAsyncInitable *initable,
979 GDBusProxy *proxy = G_DBUS_PROXY (initable);
980 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (res);
986 if (g_simple_async_result_propagate_error (simple, error))
989 result = g_simple_async_result_get_op_res_gpointer (simple);
992 process_get_all_reply (proxy, result);
998 proxy->priv->initialized = TRUE;
1003 async_initable_iface_init (GAsyncInitableIface *async_initable_iface)
1005 async_initable_iface->init_async = async_initable_init_async;
1006 async_initable_iface->init_finish = async_initable_init_finish;
1009 /* ---------------------------------------------------------------------------------------------------- */
1013 * @connection: A #GDBusConnection.
1014 * @object_type: Either #G_TYPE_DBUS_PROXY or the #GType for the #GDBusProxy<!-- -->-derived type of proxy to create.
1015 * @flags: Flags used when constructing the proxy.
1016 * @info: A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
1017 * @unique_bus_name: A unique bus name or %NULL if @connection is not a message bus connection.
1018 * @object_path: An object path.
1019 * @interface_name: A D-Bus interface name.
1020 * @cancellable: A #GCancellable or %NULL.
1021 * @callback: Callback function to invoke when the proxy is ready.
1022 * @user_data: User data to pass to @callback.
1024 * Creates a proxy for accessing @interface_name on the remote object at @object_path
1025 * owned by @unique_bus_name at @connection and asynchronously loads D-Bus properties unless the
1026 * #G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. Connect to the
1027 * #GDBusProxy::g-properties-changed signal to get notified about property changes.
1029 * If the #G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
1030 * match rules for signals. Connect to the #GDBusProxy::g-signal signal
1031 * to handle signals from the remote object.
1033 * This is a failable asynchronous constructor - when the proxy is
1034 * ready, @callback will be invoked and you can use
1035 * g_dbus_proxy_new_finish() to get the result.
1037 * See g_dbus_proxy_new_sync() and for a synchronous version of this constructor.
1042 g_dbus_proxy_new (GDBusConnection *connection,
1044 GDBusProxyFlags flags,
1045 GDBusInterfaceInfo *info,
1046 const gchar *unique_bus_name,
1047 const gchar *object_path,
1048 const gchar *interface_name,
1049 GCancellable *cancellable,
1050 GAsyncReadyCallback callback,
1053 g_return_if_fail (G_IS_DBUS_CONNECTION (connection));
1054 g_return_if_fail (g_type_is_a (object_type, G_TYPE_DBUS_PROXY));
1055 g_return_if_fail ((unique_bus_name == NULL && g_dbus_connection_get_unique_name (connection) == NULL) ||
1056 g_dbus_is_unique_name (unique_bus_name));
1057 g_return_if_fail (g_variant_is_object_path (object_path));
1058 g_return_if_fail (g_dbus_is_interface_name (interface_name));
1060 g_async_initable_new_async (object_type,
1066 "g-interface-info", info,
1067 "g-unique-bus-name", unique_bus_name,
1068 "g-connection", connection,
1069 "g-object-path", object_path,
1070 "g-interface-name", interface_name,
1075 * g_dbus_proxy_new_finish:
1076 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new().
1077 * @error: Return location for error or %NULL.
1079 * Finishes creating a #GDBusProxy.
1081 * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
1086 g_dbus_proxy_new_finish (GAsyncResult *res,
1090 GObject *source_object;
1092 source_object = g_async_result_get_source_object (res);
1093 g_assert (source_object != NULL);
1095 object = g_async_initable_new_finish (G_ASYNC_INITABLE (source_object),
1098 g_object_unref (source_object);
1101 return G_DBUS_PROXY (object);
1107 /* ---------------------------------------------------------------------------------------------------- */
1110 * g_dbus_proxy_new_sync:
1111 * @connection: A #GDBusConnection.
1112 * @object_type: Either #G_TYPE_DBUS_PROXY or the #GType for the #GDBusProxy<!-- -->-derived type of proxy to create.
1113 * @flags: Flags used when constructing the proxy.
1114 * @info: A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
1115 * @unique_bus_name: A unique bus name or %NULL if @connection is not a message bus connection.
1116 * @object_path: An object path.
1117 * @interface_name: A D-Bus interface name.
1118 * @cancellable: A #GCancellable or %NULL.
1119 * @error: Return location for error or %NULL.
1121 * Creates a proxy for accessing @interface_name on the remote object at @object_path
1122 * owned by @unique_bus_name at @connection and synchronously loads D-Bus properties unless the
1123 * #G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used.
1125 * If the #G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
1126 * match rules for signals. Connect to the #GDBusProxy::g-signal signal
1127 * to handle signals from the remote object.
1129 * This is a synchronous failable constructor. See g_dbus_proxy_new()
1130 * and g_dbus_proxy_new_finish() for the asynchronous version.
1132 * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
1137 g_dbus_proxy_new_sync (GDBusConnection *connection,
1139 GDBusProxyFlags flags,
1140 GDBusInterfaceInfo *info,
1141 const gchar *unique_bus_name,
1142 const gchar *object_path,
1143 const gchar *interface_name,
1144 GCancellable *cancellable,
1147 GInitable *initable;
1149 g_return_val_if_fail (G_IS_DBUS_CONNECTION (connection), NULL);
1150 g_return_val_if_fail (g_type_is_a (object_type, G_TYPE_DBUS_PROXY), NULL);
1151 g_return_val_if_fail ((unique_bus_name == NULL && g_dbus_connection_get_unique_name (connection) == NULL) ||
1152 g_dbus_is_unique_name (unique_bus_name), NULL);
1153 g_return_val_if_fail (g_variant_is_object_path (object_path), NULL);
1154 g_return_val_if_fail (g_dbus_is_interface_name (interface_name), NULL);
1156 initable = g_initable_new (object_type,
1160 "g-interface-info", info,
1161 "g-unique-bus-name", unique_bus_name,
1162 "g-connection", connection,
1163 "g-object-path", object_path,
1164 "g-interface-name", interface_name,
1166 if (initable != NULL)
1167 return G_DBUS_PROXY (initable);
1172 /* ---------------------------------------------------------------------------------------------------- */
1175 * g_dbus_proxy_get_connection:
1176 * @proxy: A #GDBusProxy.
1178 * Gets the connection @proxy is for.
1180 * Returns: A #GDBusConnection owned by @proxy. Do not free.
1185 g_dbus_proxy_get_connection (GDBusProxy *proxy)
1187 g_return_val_if_fail (G_IS_DBUS_PROXY (proxy), NULL);
1188 return proxy->priv->connection;
1192 * g_dbus_proxy_get_flags:
1193 * @proxy: A #GDBusProxy.
1195 * Gets the flags that @proxy was constructed with.
1197 * Returns: Flags from the #GDBusProxyFlags enumeration.
1202 g_dbus_proxy_get_flags (GDBusProxy *proxy)
1204 g_return_val_if_fail (G_IS_DBUS_PROXY (proxy), 0);
1205 return proxy->priv->flags;
1209 * g_dbus_proxy_get_unique_bus_name:
1210 * @proxy: A #GDBusProxy.
1212 * Gets the unique bus name @proxy is for.
1214 * Returns: A string owned by @proxy. Do not free.
1219 g_dbus_proxy_get_unique_bus_name (GDBusProxy *proxy)
1221 g_return_val_if_fail (G_IS_DBUS_PROXY (proxy), NULL);
1222 return proxy->priv->unique_bus_name;
1226 * g_dbus_proxy_get_object_path:
1227 * @proxy: A #GDBusProxy.
1229 * Gets the object path @proxy is for.
1231 * Returns: A string owned by @proxy. Do not free.
1236 g_dbus_proxy_get_object_path (GDBusProxy *proxy)
1238 g_return_val_if_fail (G_IS_DBUS_PROXY (proxy), NULL);
1239 return proxy->priv->object_path;
1243 * g_dbus_proxy_get_interface_name:
1244 * @proxy: A #GDBusProxy.
1246 * Gets the D-Bus interface name @proxy is for.
1248 * Returns: A string owned by @proxy. Do not free.
1253 g_dbus_proxy_get_interface_name (GDBusProxy *proxy)
1255 g_return_val_if_fail (G_IS_DBUS_PROXY (proxy), NULL);
1256 return proxy->priv->interface_name;
1260 * g_dbus_proxy_get_default_timeout:
1261 * @proxy: A #GDBusProxy.
1263 * Gets the timeout to use if -1 (specifying default timeout) is
1264 * passed as @timeout_msec in the g_dbus_proxy_call() and
1265 * g_dbus_proxy_call_sync() functions.
1267 * See the #GDBusProxy:g-default-timeout property for more details.
1269 * Returns: Timeout to use for @proxy.
1274 g_dbus_proxy_get_default_timeout (GDBusProxy *proxy)
1276 g_return_val_if_fail (G_IS_DBUS_PROXY (proxy), -1);
1277 return proxy->priv->timeout_msec;
1281 * g_dbus_proxy_set_default_timeout:
1282 * @proxy: A #GDBusProxy.
1283 * @timeout_msec: Timeout in milliseconds.
1285 * Sets the timeout to use if -1 (specifying default timeout) is
1286 * passed as @timeout_msec in the g_dbus_proxy_call() and
1287 * g_dbus_proxy_call_sync() functions.
1289 * See the #GDBusProxy:g-default-timeout property for more details.
1294 g_dbus_proxy_set_default_timeout (GDBusProxy *proxy,
1297 g_return_if_fail (G_IS_DBUS_PROXY (proxy));
1298 g_return_if_fail (timeout_msec == -1 || timeout_msec >= 0);
1300 /* TODO: locking? */
1301 if (proxy->priv->timeout_msec != timeout_msec)
1303 proxy->priv->timeout_msec = timeout_msec;
1304 g_object_notify (G_OBJECT (proxy), "g-default-timeout");
1309 * g_dbus_proxy_get_interface_info:
1310 * @proxy: A #GDBusProxy
1312 * Returns the #GDBusInterfaceInfo, if any, specifying the minimal
1313 * interface that @proxy conforms to.
1315 * See the #GDBusProxy:g-interface-info property for more details.
1317 * Returns: A #GDBusInterfaceInfo or %NULL. Do not unref the returned
1318 * object, it is owned by @proxy.
1322 GDBusInterfaceInfo *
1323 g_dbus_proxy_get_interface_info (GDBusProxy *proxy)
1325 g_return_val_if_fail (G_IS_DBUS_PROXY (proxy), NULL);
1326 return proxy->priv->expected_interface;
1330 * g_dbus_proxy_set_interface_info:
1331 * @proxy: A #GDBusProxy
1332 * @info: Minimum interface this proxy conforms to or %NULL to unset.
1334 * Ensure that interactions with @proxy conform to the given
1335 * interface. For example, when completing a method call, if the type
1336 * signature of the message isn't what's expected, the given #GError
1337 * is set. Signals that have a type signature mismatch are simply
1340 * See the #GDBusProxy:g-interface-info property for more details.
1345 g_dbus_proxy_set_interface_info (GDBusProxy *proxy,
1346 GDBusInterfaceInfo *info)
1348 g_return_if_fail (G_IS_DBUS_PROXY (proxy));
1349 if (proxy->priv->expected_interface != NULL)
1350 g_dbus_interface_info_unref (proxy->priv->expected_interface);
1351 proxy->priv->expected_interface = info != NULL ? g_dbus_interface_info_ref (info) : NULL;
1354 /* ---------------------------------------------------------------------------------------------------- */
1357 maybe_split_method_name (const gchar *method_name,
1358 gchar **out_interface_name,
1359 const gchar **out_method_name)
1364 g_assert (out_interface_name != NULL);
1365 g_assert (out_method_name != NULL);
1366 *out_interface_name = NULL;
1367 *out_method_name = NULL;
1369 if (strchr (method_name, '.') != NULL)
1374 p = g_strdup (method_name);
1375 last_dot = strrchr (p, '.');
1378 *out_interface_name = p;
1379 *out_method_name = last_dot + 1;
1389 reply_cb (GDBusConnection *connection,
1393 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (user_data);
1398 value = g_dbus_connection_call_finish (connection,
1403 g_simple_async_result_set_from_error (simple,
1405 g_error_free (error);
1409 g_simple_async_result_set_op_res_gpointer (simple,
1411 (GDestroyNotify) g_variant_unref);
1414 /* no need to complete in idle since the method GDBusConnection already does */
1415 g_simple_async_result_complete (simple);
1418 static const GDBusMethodInfo *
1419 lookup_method_info_or_warn (GDBusProxy *proxy,
1420 const gchar *method_name)
1422 const GDBusMethodInfo *info;
1424 if (proxy->priv->expected_interface == NULL)
1427 info = g_dbus_interface_info_lookup_method (proxy->priv->expected_interface, method_name);
1430 g_warning ("Trying to invoke method %s which isn't in expected interface %s",
1431 method_name, proxy->priv->expected_interface->name);
1438 * g_dbus_proxy_call:
1439 * @proxy: A #GDBusProxy.
1440 * @method_name: Name of method to invoke.
1441 * @parameters: A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
1442 * @flags: Flags from the #GDBusCallFlags enumeration.
1443 * @timeout_msec: The timeout in milliseconds or -1 to use the proxy default timeout.
1444 * @cancellable: A #GCancellable or %NULL.
1445 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't
1446 * care about the result of the method invocation.
1447 * @user_data: The data to pass to @callback.
1449 * Asynchronously invokes the @method_name method on @proxy.
1451 * If @method_name contains any dots, then @name is split into interface and
1452 * method name parts. This allows using @proxy for invoking methods on
1455 * If the #GDBusConnection associated with @proxy is closed then
1456 * the operation will fail with %G_IO_ERROR_CLOSED. If
1457 * @cancellable is canceled, the operation will fail with
1458 * %G_IO_ERROR_CANCELLED. If @parameters contains a value not
1459 * compatible with the D-Bus protocol, the operation fails with
1460 * %G_IO_ERROR_INVALID_ARGUMENT.
1462 * If the @parameters #GVariant is floating, it is consumed. This allows
1463 * convenient 'inline' use of g_variant_new(), e.g.:
1465 * g_dbus_proxy_call (proxy,
1467 * g_variant_new ("(ss)",
1470 * G_DBUS_CALL_FLAGS_NONE,
1473 * (GAsyncReadyCallback) two_strings_done,
1477 * This is an asynchronous method. When the operation is finished,
1478 * @callback will be invoked in the
1479 * <link linkend="g-main-context-push-thread-default">thread-default
1480 * main loop</link> of the thread you are calling this method from.
1481 * You can then call g_dbus_proxy_call_finish() to get the result of
1482 * the operation. See g_dbus_proxy_call_sync() for the synchronous
1483 * version of this method.
1488 g_dbus_proxy_call (GDBusProxy *proxy,
1489 const gchar *method_name,
1490 GVariant *parameters,
1491 GDBusCallFlags flags,
1493 GCancellable *cancellable,
1494 GAsyncReadyCallback callback,
1497 GSimpleAsyncResult *simple;
1499 gchar *split_interface_name;
1500 const gchar *split_method_name;
1501 const GDBusMethodInfo *expected_method_info;
1502 const gchar *target_method_name;
1503 const gchar *target_interface_name;
1504 GVariantType *reply_type;
1506 g_return_if_fail (G_IS_DBUS_PROXY (proxy));
1507 g_return_if_fail (g_dbus_is_member_name (method_name) || g_dbus_is_interface_name (method_name));
1508 g_return_if_fail (parameters == NULL || g_variant_is_of_type (parameters, G_VARIANT_TYPE_TUPLE));
1509 g_return_if_fail (timeout_msec == -1 || timeout_msec >= 0);
1511 simple = g_simple_async_result_new (G_OBJECT (proxy),
1516 was_split = maybe_split_method_name (method_name, &split_interface_name, &split_method_name);
1517 target_method_name = was_split ? split_method_name : method_name;
1518 target_interface_name = was_split ? split_interface_name : proxy->priv->interface_name;
1520 g_object_set_data_full (G_OBJECT (simple), "-gdbus-proxy-method-name", g_strdup (target_method_name), g_free);
1522 /* Just warn here */
1523 expected_method_info = lookup_method_info_or_warn (proxy, target_method_name);
1525 if (expected_method_info)
1526 reply_type = _g_dbus_compute_complete_signature (expected_method_info->out_args);
1530 g_dbus_connection_call (proxy->priv->connection,
1531 proxy->priv->unique_bus_name,
1532 proxy->priv->object_path,
1533 target_interface_name,
1538 timeout_msec == -1 ? proxy->priv->timeout_msec : timeout_msec,
1540 (GAsyncReadyCallback) reply_cb,
1543 if (reply_type != NULL)
1544 g_variant_type_free (reply_type);
1546 g_free (split_interface_name);
1550 * g_dbus_proxy_call_finish:
1551 * @proxy: A #GDBusProxy.
1552 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call().
1553 * @error: Return location for error or %NULL.
1555 * Finishes an operation started with g_dbus_proxy_call().
1557 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
1558 * return values. Free with g_variant_unref().
1563 g_dbus_proxy_call_finish (GDBusProxy *proxy,
1567 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (res);
1569 const char *method_name;
1571 g_return_val_if_fail (G_IS_DBUS_PROXY (proxy), NULL);
1572 g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
1573 g_return_val_if_fail (error == NULL || *error == NULL, NULL);
1575 g_warn_if_fail (g_simple_async_result_get_source_tag (simple) == g_dbus_proxy_call);
1579 if (g_simple_async_result_propagate_error (simple, error))
1582 value = g_simple_async_result_get_op_res_gpointer (simple);
1583 method_name = g_object_get_data (G_OBJECT (simple), "-gdbus-proxy-method-name");
1590 * g_dbus_proxy_call_sync:
1591 * @proxy: A #GDBusProxy.
1592 * @method_name: Name of method to invoke.
1593 * @parameters: A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
1594 * @flags: Flags from the #GDBusCallFlags enumeration.
1595 * @timeout_msec: The timeout in milliseconds or -1 to use the proxy default timeout.
1596 * @cancellable: A #GCancellable or %NULL.
1597 * @error: Return location for error or %NULL.
1599 * Synchronously invokes the @method_name method on @proxy.
1601 * If @method_name contains any dots, then @name is split into interface and
1602 * method name parts. This allows using @proxy for invoking methods on
1605 * If the #GDBusConnection associated with @proxy is disconnected then
1606 * the operation will fail with %G_IO_ERROR_CLOSED. If
1607 * @cancellable is canceled, the operation will fail with
1608 * %G_IO_ERROR_CANCELLED. If @parameters contains a value not
1609 * compatible with the D-Bus protocol, the operation fails with
1610 * %G_IO_ERROR_INVALID_ARGUMENT.
1612 * If the @parameters #GVariant is floating, it is consumed. This allows
1613 * convenient 'inline' use of g_variant_new(), e.g.:
1615 * g_dbus_proxy_call_sync (proxy,
1617 * g_variant_new ("(ss)",
1620 * G_DBUS_CALL_FLAGS_NONE,
1626 * The calling thread is blocked until a reply is received. See
1627 * g_dbus_proxy_call() for the asynchronous version of this
1630 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
1631 * return values. Free with g_variant_unref().
1636 g_dbus_proxy_call_sync (GDBusProxy *proxy,
1637 const gchar *method_name,
1638 GVariant *parameters,
1639 GDBusCallFlags flags,
1641 GCancellable *cancellable,
1646 gchar *split_interface_name;
1647 const gchar *split_method_name;
1648 const GDBusMethodInfo *expected_method_info;
1649 const gchar *target_method_name;
1650 const gchar *target_interface_name;
1651 GVariantType *reply_type;
1653 g_return_val_if_fail (G_IS_DBUS_PROXY (proxy), NULL);
1654 g_return_val_if_fail (g_dbus_is_member_name (method_name) || g_dbus_is_interface_name (method_name), NULL);
1655 g_return_val_if_fail (parameters == NULL || g_variant_is_of_type (parameters, G_VARIANT_TYPE_TUPLE), NULL);
1656 g_return_val_if_fail (timeout_msec == -1 || timeout_msec >= 0, NULL);
1657 g_return_val_if_fail (error == NULL || *error == NULL, NULL);
1659 was_split = maybe_split_method_name (method_name, &split_interface_name, &split_method_name);
1660 target_method_name = was_split ? split_method_name : method_name;
1661 target_interface_name = was_split ? split_interface_name : proxy->priv->interface_name;
1663 if (proxy->priv->expected_interface)
1665 expected_method_info = g_dbus_interface_info_lookup_method (proxy->priv->expected_interface, target_method_name);
1666 if (expected_method_info == NULL)
1668 g_warning ("Trying to invoke method `%s' which isn't in expected interface `%s'",
1670 target_interface_name);
1675 expected_method_info = NULL;
1678 if (expected_method_info)
1679 reply_type = _g_dbus_compute_complete_signature (expected_method_info->out_args);
1683 ret = g_dbus_connection_call_sync (proxy->priv->connection,
1684 proxy->priv->unique_bus_name,
1685 proxy->priv->object_path,
1686 target_interface_name,
1691 timeout_msec == -1 ? proxy->priv->timeout_msec : timeout_msec,
1695 if (reply_type != NULL)
1696 g_variant_type_free (reply_type);
1698 g_free (split_interface_name);
1703 /* ---------------------------------------------------------------------------------------------------- */
1705 #define __G_DBUS_PROXY_C__
1706 #include "gioaliasdef.c"