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.
58 struct _GDBusProxyPrivate
60 GDBusConnection *connection;
61 GDBusProxyFlags flags;
62 gchar *unique_bus_name;
64 gchar *interface_name;
67 /* gchar* -> GVariant* */
68 GHashTable *properties;
70 GDBusInterfaceInfo *expected_interface;
72 guint properties_changed_subscriber_id;
73 guint signals_subscriber_id;
80 PROP_G_UNIQUE_BUS_NAME,
83 PROP_G_INTERFACE_NAME,
84 PROP_G_DEFAULT_TIMEOUT,
90 PROPERTIES_CHANGED_SIGNAL,
95 static void g_dbus_proxy_constructed (GObject *object);
97 guint signals[LAST_SIGNAL] = {0};
99 static void initable_iface_init (GInitableIface *initable_iface);
100 static void async_initable_iface_init (GAsyncInitableIface *async_initable_iface);
102 G_DEFINE_TYPE_WITH_CODE (GDBusProxy, g_dbus_proxy, G_TYPE_OBJECT,
103 G_IMPLEMENT_INTERFACE (G_TYPE_INITABLE, initable_iface_init)
104 G_IMPLEMENT_INTERFACE (G_TYPE_ASYNC_INITABLE, async_initable_iface_init)
108 g_dbus_proxy_finalize (GObject *object)
110 GDBusProxy *proxy = G_DBUS_PROXY (object);
112 if (proxy->priv->properties_changed_subscriber_id > 0)
113 g_dbus_connection_signal_unsubscribe (proxy->priv->connection,
114 proxy->priv->properties_changed_subscriber_id);
116 if (proxy->priv->signals_subscriber_id > 0)
117 g_dbus_connection_signal_unsubscribe (proxy->priv->connection,
118 proxy->priv->signals_subscriber_id);
120 g_object_unref (proxy->priv->connection);
121 g_free (proxy->priv->unique_bus_name);
122 g_free (proxy->priv->object_path);
123 g_free (proxy->priv->interface_name);
124 if (proxy->priv->properties != NULL)
125 g_hash_table_unref (proxy->priv->properties);
127 if (proxy->priv->expected_interface != NULL)
128 g_dbus_interface_info_unref (proxy->priv->expected_interface);
130 G_OBJECT_CLASS (g_dbus_proxy_parent_class)->finalize (object);
134 g_dbus_proxy_get_property (GObject *object,
139 GDBusProxy *proxy = G_DBUS_PROXY (object);
143 case PROP_G_CONNECTION:
144 g_value_set_object (value, proxy->priv->connection);
148 g_value_set_flags (value, proxy->priv->flags);
151 case PROP_G_UNIQUE_BUS_NAME:
152 g_value_set_string (value, proxy->priv->unique_bus_name);
155 case PROP_G_OBJECT_PATH:
156 g_value_set_string (value, proxy->priv->object_path);
159 case PROP_G_INTERFACE_NAME:
160 g_value_set_string (value, proxy->priv->interface_name);
163 case PROP_G_DEFAULT_TIMEOUT:
164 g_value_set_int (value, proxy->priv->timeout_msec);
167 case PROP_G_INTERFACE_INFO:
168 g_value_set_boxed (value, g_dbus_proxy_get_interface_info (proxy));
172 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
178 g_dbus_proxy_set_property (GObject *object,
183 GDBusProxy *proxy = G_DBUS_PROXY (object);
187 case PROP_G_CONNECTION:
188 proxy->priv->connection = g_value_dup_object (value);
192 proxy->priv->flags = g_value_get_flags (value);
195 case PROP_G_UNIQUE_BUS_NAME:
196 proxy->priv->unique_bus_name = g_value_dup_string (value);
199 case PROP_G_OBJECT_PATH:
200 proxy->priv->object_path = g_value_dup_string (value);
203 case PROP_G_INTERFACE_NAME:
204 proxy->priv->interface_name = g_value_dup_string (value);
207 case PROP_G_DEFAULT_TIMEOUT:
208 g_dbus_proxy_set_default_timeout (proxy, g_value_get_int (value));
211 case PROP_G_INTERFACE_INFO:
212 g_dbus_proxy_set_interface_info (proxy, g_value_get_boxed (value));
216 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
222 g_dbus_proxy_class_init (GDBusProxyClass *klass)
224 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
226 gobject_class->finalize = g_dbus_proxy_finalize;
227 gobject_class->set_property = g_dbus_proxy_set_property;
228 gobject_class->get_property = g_dbus_proxy_get_property;
229 gobject_class->constructed = g_dbus_proxy_constructed;
231 /* Note that all property names are prefixed to avoid collisions with D-Bus property names
232 * in derived classes */
235 * GDBusProxy:g-interface-info:
237 * Ensure that interactions with this proxy conform to the given
238 * interface. For example, when completing a method call, if the
239 * type signature of the message isn't what's expected, the given
240 * #GError is set. Signals that have a type signature mismatch are
245 g_object_class_install_property (gobject_class,
246 PROP_G_INTERFACE_INFO,
247 g_param_spec_boxed ("g-interface-info",
248 P_("Interface Information"),
249 P_("Interface Information"),
250 G_TYPE_DBUS_INTERFACE_INFO,
253 G_PARAM_STATIC_NAME |
254 G_PARAM_STATIC_BLURB |
255 G_PARAM_STATIC_NICK));
258 * GDBusProxy:g-connection:
260 * The #GDBusConnection the proxy is for.
264 g_object_class_install_property (gobject_class,
266 g_param_spec_object ("g-connection",
268 P_("The connection the proxy is for"),
269 G_TYPE_DBUS_CONNECTION,
272 G_PARAM_CONSTRUCT_ONLY |
273 G_PARAM_STATIC_NAME |
274 G_PARAM_STATIC_BLURB |
275 G_PARAM_STATIC_NICK));
278 * GDBusProxy:g-flags:
280 * Flags from the #GDBusProxyFlags enumeration.
284 g_object_class_install_property (gobject_class,
286 g_param_spec_flags ("g-flags",
288 P_("Flags for the proxy"),
289 G_TYPE_DBUS_PROXY_FLAGS,
290 G_DBUS_PROXY_FLAGS_NONE,
293 G_PARAM_CONSTRUCT_ONLY |
294 G_PARAM_STATIC_NAME |
295 G_PARAM_STATIC_BLURB |
296 G_PARAM_STATIC_NICK));
299 * GDBusProxy:g-unique-bus-name:
301 * The unique bus name the proxy is for.
305 g_object_class_install_property (gobject_class,
306 PROP_G_UNIQUE_BUS_NAME,
307 g_param_spec_string ("g-unique-bus-name",
308 P_("g-unique-bus-name"),
309 P_("The unique bus name the proxy is for"),
313 G_PARAM_CONSTRUCT_ONLY |
314 G_PARAM_STATIC_NAME |
315 G_PARAM_STATIC_BLURB |
316 G_PARAM_STATIC_NICK));
319 * GDBusProxy:g-object-path:
321 * The object path the proxy is for.
325 g_object_class_install_property (gobject_class,
327 g_param_spec_string ("g-object-path",
329 P_("The object path the proxy is for"),
333 G_PARAM_CONSTRUCT_ONLY |
334 G_PARAM_STATIC_NAME |
335 G_PARAM_STATIC_BLURB |
336 G_PARAM_STATIC_NICK));
339 * GDBusProxy:g-interface-name:
341 * The D-Bus interface name the proxy is for.
345 g_object_class_install_property (gobject_class,
346 PROP_G_INTERFACE_NAME,
347 g_param_spec_string ("g-interface-name",
348 P_("g-interface-name"),
349 P_("The D-Bus interface name the proxy is for"),
353 G_PARAM_CONSTRUCT_ONLY |
354 G_PARAM_STATIC_NAME |
355 G_PARAM_STATIC_BLURB |
356 G_PARAM_STATIC_NICK));
359 * GDBusProxy:g-default-timeout:
361 * The timeout to use if -1 (specifying default timeout) is passed
362 * as @timeout_msec in the g_dbus_proxy_call() and
363 * g_dbus_proxy_call_sync() functions.
365 * This allows applications to set a proxy-wide timeout for all
366 * remote method invocations on the proxy. If this property is -1,
367 * the default timeout (typically 25 seconds) is used. If set to
368 * %G_MAXINT, then no timeout is used.
372 g_object_class_install_property (gobject_class,
373 PROP_G_DEFAULT_TIMEOUT,
374 g_param_spec_int ("g-default-timeout",
375 P_("Default Timeout"),
376 P_("Timeout for remote method invocation"),
383 G_PARAM_STATIC_NAME |
384 G_PARAM_STATIC_BLURB |
385 G_PARAM_STATIC_NICK));
388 * GDBusProxy::g-properties-changed:
389 * @proxy: The #GDBusProxy emitting the signal.
390 * @changed_properties: A #GVariant containing the properties that changed
391 * @invalidated_properties: A %NULL terminated array of properties that was invalidated
393 * Emitted when one or more D-Bus properties on @proxy changes. The
394 * local cache has already been updated when this signal fires. Note
395 * that both @changed_properties and @invalidated_properties are
396 * guaranteed to never be %NULL (either may be empty though).
398 * This signal corresponds to the
399 * <literal>PropertiesChanged</literal> D-Bus signal on the
400 * <literal>org.freedesktop.DBus.Properties</literal> interface.
404 signals[PROPERTIES_CHANGED_SIGNAL] = g_signal_new ("g-properties-changed",
407 G_STRUCT_OFFSET (GDBusProxyClass, g_properties_changed),
410 _gio_marshal_VOID__BOXED_BOXED,
414 G_TYPE_STRV | G_SIGNAL_TYPE_STATIC_SCOPE);
417 * GDBusProxy::g-signal:
418 * @proxy: The #GDBusProxy emitting the signal.
419 * @sender_name: The sender of the signal or %NULL if the connection is not a bus connection.
420 * @signal_name: The name of the signal.
421 * @parameters: A #GVariant tuple with parameters for the signal.
423 * Emitted when a signal from the remote object and interface that @proxy is for, has been received.
427 signals[SIGNAL_SIGNAL] = g_signal_new ("g-signal",
430 G_STRUCT_OFFSET (GDBusProxyClass, g_signal),
433 _gio_marshal_VOID__STRING_STRING_BOXED,
441 g_type_class_add_private (klass, sizeof (GDBusProxyPrivate));
445 g_dbus_proxy_init (GDBusProxy *proxy)
447 proxy->priv = G_TYPE_INSTANCE_GET_PRIVATE (proxy, G_TYPE_DBUS_PROXY, GDBusProxyPrivate);
450 /* ---------------------------------------------------------------------------------------------------- */
453 * g_dbus_proxy_get_cached_property_names:
454 * @proxy: A #GDBusProxy.
455 * @error: Return location for error or %NULL.
457 * Gets the names of all cached properties on @proxy.
459 * Returns: A %NULL-terminated array of strings or %NULL if @error is set. Free with
465 g_dbus_proxy_get_cached_property_names (GDBusProxy *proxy,
473 g_return_val_if_fail (G_IS_DBUS_PROXY (proxy), NULL);
474 g_return_val_if_fail (error == NULL || *error == NULL, NULL);
478 if (proxy->priv->flags & G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES)
483 _("Properties are not available (proxy created with G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES)"));
487 p = g_ptr_array_new ();
489 g_hash_table_iter_init (&iter, proxy->priv->properties);
490 while (g_hash_table_iter_next (&iter, (gpointer) &key, NULL))
491 g_ptr_array_add (p, g_strdup (key));
492 g_ptr_array_sort (p, (GCompareFunc) g_strcmp0);
493 g_ptr_array_add (p, NULL);
495 names = (gchar **) g_ptr_array_free (p, FALSE);
501 static const GDBusPropertyInfo *
502 lookup_property_info_or_warn (GDBusProxy *proxy,
503 const gchar *property_name)
505 const GDBusPropertyInfo *info;
507 if (proxy->priv->expected_interface == NULL)
510 info = g_dbus_interface_info_lookup_property (proxy->priv->expected_interface, property_name);
513 g_warning ("Trying to lookup property %s which isn't in expected interface %s",
515 proxy->priv->expected_interface->name);
522 * g_dbus_proxy_get_cached_property:
523 * @proxy: A #GDBusProxy.
524 * @property_name: Property name.
526 * Looks up the value for a property from the cache. This call does no
529 * If @proxy has an expected interface (see
530 * #GDBusProxy:g-interface-info), then @property_name (for existence)
531 * is checked against it.
533 * Returns: A reference to the #GVariant instance that holds the value
534 * for @property_name or %NULL if the value is not in the cache. The
535 * returned reference must be freed with g_variant_unref().
540 g_dbus_proxy_get_cached_property (GDBusProxy *proxy,
541 const gchar *property_name)
545 g_return_val_if_fail (G_IS_DBUS_PROXY (proxy), NULL);
546 g_return_val_if_fail (property_name != NULL, NULL);
548 value = g_hash_table_lookup (proxy->priv->properties, property_name);
551 const GDBusPropertyInfo *info;
552 info = lookup_property_info_or_warn (proxy, property_name);
557 g_variant_ref (value);
564 * g_dbus_proxy_set_cached_property:
565 * @proxy: A #GDBusProxy
566 * @property_name: Property name.
567 * @value: Value for the property or %NULL to remove it from the cache.
569 * If @value is not %NULL, sets the cached value for the property with
570 * name @property_name to the value in @value.
572 * If @value is %NULL, then the cached value is removed from the
575 * If @proxy has an expected interface (see
576 * #GDBusProxy:g-interface-info), then @property_name (for existence)
577 * and @value (for the type) is checked against it.
579 * If the @value #GVariant is floating, it is consumed. This allows
580 * convenient 'inline' use of g_variant_new(), e.g.
582 * g_dbus_proxy_set_cached_property (proxy,
584 * g_variant_new ("(si)",
589 * Normally you will not need to use this method since @proxy is
590 * tracking changes using the
591 * <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
592 * D-Bus signal. However, for performance reasons an object may decide
593 * to not use this signal for some properties and instead use a
594 * proprietary out-of-band mechanism to transmit changes.
596 * As a concrete example, consider an object with a property
597 * <literal>ChatroomParticipants</literal> which is an array of
598 * strings. Instead of transmitting the same (long) array every time
599 * the property changes, it is more efficient to only transmit the
600 * delta using e.g. signals <literal>ChatroomParticipantJoined(String
601 * name)</literal> and <literal>ChatroomParticipantParted(String
607 g_dbus_proxy_set_cached_property (GDBusProxy *proxy,
608 const gchar *property_name,
611 const GDBusPropertyInfo *info;
613 g_return_if_fail (G_IS_DBUS_PROXY (proxy));
614 g_return_if_fail (property_name != NULL);
618 info = lookup_property_info_or_warn (proxy, property_name);
621 if (g_strcmp0 (info->signature, g_variant_get_type_string (value)) != 0)
623 g_warning (_("Trying to set property %s of type %s but according to the expected "
624 "interface the type is %s"),
626 g_variant_get_type_string (value),
631 g_hash_table_insert (proxy->priv->properties,
632 g_strdup (property_name),
633 g_variant_ref_sink (value));
637 g_hash_table_remove (proxy->priv->properties, property_name);
644 /* ---------------------------------------------------------------------------------------------------- */
647 on_signal_received (GDBusConnection *connection,
648 const gchar *sender_name,
649 const gchar *object_path,
650 const gchar *interface_name,
651 const gchar *signal_name,
652 GVariant *parameters,
655 GDBusProxy *proxy = G_DBUS_PROXY (user_data);
657 g_signal_emit (proxy,
658 signals[SIGNAL_SIGNAL],
665 /* ---------------------------------------------------------------------------------------------------- */
668 on_properties_changed (GDBusConnection *connection,
669 const gchar *sender_name,
670 const gchar *object_path,
671 const gchar *interface_name,
672 const gchar *signal_name,
673 GVariant *parameters,
676 GDBusProxy *proxy = G_DBUS_PROXY (user_data);
678 const gchar *interface_name_for_signal;
679 GVariant *changed_properties;
680 gchar **invalidated_properties;
688 /* Ignore this signal if properties are not yet available
690 * (can happen in the window between subscribing to PropertiesChanged() and until
691 * org.freedesktop.DBus.Properties.GetAll() returns)
693 if (!proxy->priv->properties_available)
697 if (!g_variant_is_of_type (parameters, G_VARIANT_TYPE ("(sa{sv}as)")))
699 g_warning ("Value for PropertiesChanged signal with type `%s' does not match `(sa{sv}as)'",
700 g_variant_get_type_string (parameters));
704 g_variant_get (parameters,
706 &interface_name_for_signal,
708 &invalidated_properties);
710 if (g_strcmp0 (interface_name_for_signal, proxy->priv->interface_name) != 0)
713 g_variant_iter_init (&iter, changed_properties);
714 while (g_variant_iter_next (&iter, "{sv}", &key, &value))
716 g_hash_table_insert (proxy->priv->properties,
717 key, /* adopts string */
718 value); /* adopts value */
722 g_signal_emit (proxy, signals[PROPERTIES_CHANGED_SIGNAL],
725 invalidated_properties);
728 g_variant_unref (changed_properties);
729 g_free (invalidated_properties);
732 /* ---------------------------------------------------------------------------------------------------- */
735 g_dbus_proxy_constructed (GObject *object)
737 if (G_OBJECT_CLASS (g_dbus_proxy_parent_class)->constructed != NULL)
738 G_OBJECT_CLASS (g_dbus_proxy_parent_class)->constructed (object);
741 /* ---------------------------------------------------------------------------------------------------- */
744 subscribe_to_signals (GDBusProxy *proxy)
746 if (!(proxy->priv->flags & G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES))
748 /* subscribe to PropertiesChanged() */
749 proxy->priv->properties_changed_subscriber_id =
750 g_dbus_connection_signal_subscribe (proxy->priv->connection,
751 proxy->priv->unique_bus_name,
752 "org.freedesktop.DBus.Properties",
754 proxy->priv->object_path,
755 proxy->priv->interface_name,
756 on_properties_changed,
761 if (!(proxy->priv->flags & G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS))
763 /* subscribe to all signals for the object */
764 proxy->priv->signals_subscriber_id =
765 g_dbus_connection_signal_subscribe (proxy->priv->connection,
766 proxy->priv->unique_bus_name,
767 proxy->priv->interface_name,
769 proxy->priv->object_path,
777 /* ---------------------------------------------------------------------------------------------------- */
780 process_get_all_reply (GDBusProxy *proxy,
786 if (strcmp (g_variant_get_type_string (result), "(a{sv})") != 0)
788 g_warning ("Value for GetAll reply with type `%s' does not match `(a{sv})'",
789 g_variant_get_type_string (result));
793 proxy->priv->properties = g_hash_table_new_full (g_str_hash,
796 (GDestroyNotify) g_variant_unref);
798 g_variant_iter_init (&iter, g_variant_get_child_value (result, 0));
799 while ((item = g_variant_iter_next_value (&iter)) != NULL)
808 //g_print ("got %s -> %s\n", key, g_variant_markup_print (value, FALSE, 0, 0));
810 g_hash_table_insert (proxy->priv->properties,
812 value); /* steals value */
819 initable_init (GInitable *initable,
820 GCancellable *cancellable,
823 GDBusProxy *proxy = G_DBUS_PROXY (initable);
829 if (!(proxy->priv->flags & G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES))
831 /* load all properties synchronously */
832 result = g_dbus_connection_call_sync (proxy->priv->connection,
833 proxy->priv->unique_bus_name,
834 proxy->priv->object_path,
835 "org.freedesktop.DBus.Properties",
837 g_variant_new ("(s)", proxy->priv->interface_name),
838 G_DBUS_CALL_FLAGS_NONE,
845 process_get_all_reply (proxy, result);
847 g_variant_unref (result);
850 subscribe_to_signals (proxy);
859 initable_iface_init (GInitableIface *initable_iface)
861 initable_iface->init = initable_init;
864 /* ---------------------------------------------------------------------------------------------------- */
867 get_all_cb (GDBusConnection *connection,
871 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (user_data);
876 result = g_dbus_connection_call_finish (connection,
881 g_simple_async_result_set_from_error (simple, error);
882 g_error_free (error);
886 g_simple_async_result_set_op_res_gpointer (simple,
888 (GDestroyNotify) g_variant_unref);
891 g_simple_async_result_complete_in_idle (simple);
892 g_object_unref (simple);
896 async_initable_init_async (GAsyncInitable *initable,
898 GCancellable *cancellable,
899 GAsyncReadyCallback callback,
902 GDBusProxy *proxy = G_DBUS_PROXY (initable);
903 GSimpleAsyncResult *simple;
905 simple = g_simple_async_result_new (G_OBJECT (proxy),
910 if (!(proxy->priv->flags & G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES))
912 /* load all properties asynchronously */
913 g_dbus_connection_call (proxy->priv->connection,
914 proxy->priv->unique_bus_name,
915 proxy->priv->object_path,
916 "org.freedesktop.DBus.Properties",
918 g_variant_new ("(s)", proxy->priv->interface_name),
919 G_DBUS_CALL_FLAGS_NONE,
922 (GAsyncReadyCallback) get_all_cb,
927 g_simple_async_result_complete_in_idle (simple);
928 g_object_unref (simple);
933 async_initable_init_finish (GAsyncInitable *initable,
937 GDBusProxy *proxy = G_DBUS_PROXY (initable);
938 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (res);
944 result = g_simple_async_result_get_op_res_gpointer (simple);
947 if (!(proxy->priv->flags & G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES))
949 g_simple_async_result_propagate_error (simple, error);
955 process_get_all_reply (proxy, result);
958 subscribe_to_signals (proxy);
967 async_initable_iface_init (GAsyncInitableIface *async_initable_iface)
969 async_initable_iface->init_async = async_initable_init_async;
970 async_initable_iface->init_finish = async_initable_init_finish;
973 /* ---------------------------------------------------------------------------------------------------- */
977 * @connection: A #GDBusConnection.
978 * @object_type: Either #G_TYPE_DBUS_PROXY or the #GType for the #GDBusProxy<!-- -->-derived type of proxy to create.
979 * @flags: Flags used when constructing the proxy.
980 * @info: A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
981 * @unique_bus_name: A unique bus name or %NULL if @connection is not a message bus connection.
982 * @object_path: An object path.
983 * @interface_name: A D-Bus interface name.
984 * @cancellable: A #GCancellable or %NULL.
985 * @callback: Callback function to invoke when the proxy is ready.
986 * @user_data: User data to pass to @callback.
988 * Creates a proxy for accessing @interface_name on the remote object at @object_path
989 * owned by @unique_bus_name at @connection and asynchronously loads D-Bus properties unless the
990 * #G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. Connect to the
991 * #GDBusProxy::g-properties-changed signal to get notified about property changes.
993 * If the #G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
994 * match rules for signals. Connect to the #GDBusProxy::g-signal signal
995 * to handle signals from the remote object.
997 * This is a failable asynchronous constructor - when the proxy is
998 * ready, @callback will be invoked and you can use
999 * g_dbus_proxy_new_finish() to get the result.
1001 * See g_dbus_proxy_new_sync() and for a synchronous version of this constructor.
1006 g_dbus_proxy_new (GDBusConnection *connection,
1008 GDBusProxyFlags flags,
1009 GDBusInterfaceInfo *info,
1010 const gchar *unique_bus_name,
1011 const gchar *object_path,
1012 const gchar *interface_name,
1013 GCancellable *cancellable,
1014 GAsyncReadyCallback callback,
1017 g_return_if_fail (G_IS_DBUS_CONNECTION (connection));
1018 g_return_if_fail (g_type_is_a (object_type, G_TYPE_DBUS_PROXY));
1019 g_return_if_fail ((unique_bus_name == NULL && g_dbus_connection_get_unique_name (connection) == NULL) ||
1020 g_dbus_is_unique_name (unique_bus_name));
1021 g_return_if_fail (g_variant_is_object_path (object_path));
1022 g_return_if_fail (g_dbus_is_interface_name (interface_name));
1024 g_async_initable_new_async (object_type,
1030 "g-interface-info", info,
1031 "g-unique-bus-name", unique_bus_name,
1032 "g-connection", connection,
1033 "g-object-path", object_path,
1034 "g-interface-name", interface_name,
1039 * g_dbus_proxy_new_finish:
1040 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new().
1041 * @error: Return location for error or %NULL.
1043 * Finishes creating a #GDBusProxy.
1045 * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
1050 g_dbus_proxy_new_finish (GAsyncResult *res,
1054 GObject *source_object;
1056 source_object = g_async_result_get_source_object (res);
1057 g_assert (source_object != NULL);
1059 object = g_async_initable_new_finish (G_ASYNC_INITABLE (source_object),
1062 g_object_unref (source_object);
1065 return G_DBUS_PROXY (object);
1071 /* ---------------------------------------------------------------------------------------------------- */
1074 * g_dbus_proxy_new_sync:
1075 * @connection: A #GDBusConnection.
1076 * @object_type: Either #G_TYPE_DBUS_PROXY or the #GType for the #GDBusProxy<!-- -->-derived type of proxy to create.
1077 * @flags: Flags used when constructing the proxy.
1078 * @info: A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
1079 * @unique_bus_name: A unique bus name or %NULL if @connection is not a message bus connection.
1080 * @object_path: An object path.
1081 * @interface_name: A D-Bus interface name.
1082 * @cancellable: A #GCancellable or %NULL.
1083 * @error: Return location for error or %NULL.
1085 * Creates a proxy for accessing @interface_name on the remote object at @object_path
1086 * owned by @unique_bus_name at @connection and synchronously loads D-Bus properties unless the
1087 * #G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used.
1089 * If the #G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
1090 * match rules for signals. Connect to the #GDBusProxy::g-signal signal
1091 * to handle signals from the remote object.
1093 * This is a synchronous failable constructor. See g_dbus_proxy_new()
1094 * and g_dbus_proxy_new_finish() for the asynchronous version.
1096 * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
1101 g_dbus_proxy_new_sync (GDBusConnection *connection,
1103 GDBusProxyFlags flags,
1104 GDBusInterfaceInfo *info,
1105 const gchar *unique_bus_name,
1106 const gchar *object_path,
1107 const gchar *interface_name,
1108 GCancellable *cancellable,
1111 GInitable *initable;
1113 g_return_val_if_fail (G_IS_DBUS_CONNECTION (connection), NULL);
1114 g_return_val_if_fail (g_type_is_a (object_type, G_TYPE_DBUS_PROXY), NULL);
1115 g_return_val_if_fail ((unique_bus_name == NULL && g_dbus_connection_get_unique_name (connection) == NULL) ||
1116 g_dbus_is_unique_name (unique_bus_name), NULL);
1117 g_return_val_if_fail (g_variant_is_object_path (object_path), NULL);
1118 g_return_val_if_fail (g_dbus_is_interface_name (interface_name), NULL);
1120 initable = g_initable_new (object_type,
1124 "g-interface-info", info,
1125 "g-unique-bus-name", unique_bus_name,
1126 "g-connection", connection,
1127 "g-object-path", object_path,
1128 "g-interface-name", interface_name,
1130 if (initable != NULL)
1131 return G_DBUS_PROXY (initable);
1136 /* ---------------------------------------------------------------------------------------------------- */
1139 * g_dbus_proxy_get_connection:
1140 * @proxy: A #GDBusProxy.
1142 * Gets the connection @proxy is for.
1144 * Returns: A #GDBusConnection owned by @proxy. Do not free.
1149 g_dbus_proxy_get_connection (GDBusProxy *proxy)
1151 g_return_val_if_fail (G_IS_DBUS_PROXY (proxy), NULL);
1152 return proxy->priv->connection;
1156 * g_dbus_proxy_get_flags:
1157 * @proxy: A #GDBusProxy.
1159 * Gets the flags that @proxy was constructed with.
1161 * Returns: Flags from the #GDBusProxyFlags enumeration.
1166 g_dbus_proxy_get_flags (GDBusProxy *proxy)
1168 g_return_val_if_fail (G_IS_DBUS_PROXY (proxy), 0);
1169 return proxy->priv->flags;
1173 * g_dbus_proxy_get_unique_bus_name:
1174 * @proxy: A #GDBusProxy.
1176 * Gets the unique bus name @proxy is for.
1178 * Returns: A string owned by @proxy. Do not free.
1183 g_dbus_proxy_get_unique_bus_name (GDBusProxy *proxy)
1185 g_return_val_if_fail (G_IS_DBUS_PROXY (proxy), NULL);
1186 return proxy->priv->unique_bus_name;
1190 * g_dbus_proxy_get_object_path:
1191 * @proxy: A #GDBusProxy.
1193 * Gets the object path @proxy is for.
1195 * Returns: A string owned by @proxy. Do not free.
1200 g_dbus_proxy_get_object_path (GDBusProxy *proxy)
1202 g_return_val_if_fail (G_IS_DBUS_PROXY (proxy), NULL);
1203 return proxy->priv->object_path;
1207 * g_dbus_proxy_get_interface_name:
1208 * @proxy: A #GDBusProxy.
1210 * Gets the D-Bus interface name @proxy is for.
1212 * Returns: A string owned by @proxy. Do not free.
1217 g_dbus_proxy_get_interface_name (GDBusProxy *proxy)
1219 g_return_val_if_fail (G_IS_DBUS_PROXY (proxy), NULL);
1220 return proxy->priv->interface_name;
1224 * g_dbus_proxy_get_default_timeout:
1225 * @proxy: A #GDBusProxy.
1227 * Gets the timeout to use if -1 (specifying default timeout) is
1228 * passed as @timeout_msec in the g_dbus_proxy_call() and
1229 * g_dbus_proxy_call_sync() functions.
1231 * See the #GDBusProxy:g-default-timeout property for more details.
1233 * Returns: Timeout to use for @proxy.
1238 g_dbus_proxy_get_default_timeout (GDBusProxy *proxy)
1240 g_return_val_if_fail (G_IS_DBUS_PROXY (proxy), -1);
1241 return proxy->priv->timeout_msec;
1245 * g_dbus_proxy_set_default_timeout:
1246 * @proxy: A #GDBusProxy.
1247 * @timeout_msec: Timeout in milliseconds.
1249 * Sets the timeout to use if -1 (specifying default timeout) is
1250 * passed as @timeout_msec in the g_dbus_proxy_call() and
1251 * g_dbus_proxy_call_sync() functions.
1253 * See the #GDBusProxy:g-default-timeout property for more details.
1258 g_dbus_proxy_set_default_timeout (GDBusProxy *proxy,
1261 g_return_if_fail (G_IS_DBUS_PROXY (proxy));
1262 g_return_if_fail (timeout_msec == -1 || timeout_msec >= 0);
1264 /* TODO: locking? */
1265 if (proxy->priv->timeout_msec != timeout_msec)
1267 proxy->priv->timeout_msec = timeout_msec;
1268 g_object_notify (G_OBJECT (proxy), "g-default-timeout");
1273 * g_dbus_proxy_get_interface_info:
1274 * @proxy: A #GDBusProxy
1276 * Returns the #GDBusInterfaceInfo, if any, specifying the minimal
1277 * interface that @proxy conforms to.
1279 * See the #GDBusProxy:g-interface-info property for more details.
1281 * Returns: A #GDBusInterfaceInfo or %NULL. Do not unref the returned
1282 * object, it is owned by @proxy.
1286 GDBusInterfaceInfo *
1287 g_dbus_proxy_get_interface_info (GDBusProxy *proxy)
1289 g_return_val_if_fail (G_IS_DBUS_PROXY (proxy), NULL);
1290 return proxy->priv->expected_interface;
1294 * g_dbus_proxy_set_interface_info:
1295 * @proxy: A #GDBusProxy
1296 * @info: Minimum interface this proxy conforms to or %NULL to unset.
1298 * Ensure that interactions with @proxy conform to the given
1299 * interface. For example, when completing a method call, if the type
1300 * signature of the message isn't what's expected, the given #GError
1301 * is set. Signals that have a type signature mismatch are simply
1304 * See the #GDBusProxy:g-interface-info property for more details.
1309 g_dbus_proxy_set_interface_info (GDBusProxy *proxy,
1310 GDBusInterfaceInfo *info)
1312 g_return_if_fail (G_IS_DBUS_PROXY (proxy));
1313 if (proxy->priv->expected_interface != NULL)
1314 g_dbus_interface_info_unref (proxy->priv->expected_interface);
1315 proxy->priv->expected_interface = info != NULL ? g_dbus_interface_info_ref (info) : NULL;
1318 /* ---------------------------------------------------------------------------------------------------- */
1321 maybe_split_method_name (const gchar *method_name,
1322 gchar **out_interface_name,
1323 const gchar **out_method_name)
1328 g_assert (out_interface_name != NULL);
1329 g_assert (out_method_name != NULL);
1330 *out_interface_name = NULL;
1331 *out_method_name = NULL;
1333 if (strchr (method_name, '.') != NULL)
1338 p = g_strdup (method_name);
1339 last_dot = strrchr (p, '.');
1342 *out_interface_name = p;
1343 *out_method_name = last_dot + 1;
1353 reply_cb (GDBusConnection *connection,
1357 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (user_data);
1362 value = g_dbus_connection_call_finish (connection,
1367 g_simple_async_result_set_from_error (simple,
1369 g_error_free (error);
1373 g_simple_async_result_set_op_res_gpointer (simple,
1375 (GDestroyNotify) g_variant_unref);
1378 /* no need to complete in idle since the method GDBusConnection already does */
1379 g_simple_async_result_complete (simple);
1382 static const GDBusMethodInfo *
1383 lookup_method_info_or_warn (GDBusProxy *proxy,
1384 const gchar *method_name)
1386 const GDBusMethodInfo *info;
1388 if (proxy->priv->expected_interface == NULL)
1391 info = g_dbus_interface_info_lookup_method (proxy->priv->expected_interface, method_name);
1394 g_warning ("Trying to invoke method %s which isn't in expected interface %s",
1395 method_name, proxy->priv->expected_interface->name);
1402 validate_method_return (const char *method_name,
1404 const GDBusMethodInfo *expected_method_info,
1407 const gchar *type_string;
1414 if (value == NULL || expected_method_info == NULL)
1417 /* Shouldn't happen... */
1418 if (g_variant_classify (value) != G_VARIANT_CLASS_TUPLE)
1421 type_string = g_variant_get_type_string (value);
1422 signature = _g_dbus_compute_complete_signature (expected_method_info->out_args, TRUE);
1423 if (g_strcmp0 (type_string, signature) != 0)
1427 G_IO_ERROR_INVALID_ARGUMENT,
1428 _("Method `%s' returned signature `%s', but expected `%s'"),
1441 * g_dbus_proxy_call:
1442 * @proxy: A #GDBusProxy.
1443 * @method_name: Name of method to invoke.
1444 * @parameters: A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
1445 * @flags: Flags from the #GDBusCallFlags enumeration.
1446 * @timeout_msec: The timeout in milliseconds or -1 to use the proxy default timeout.
1447 * @cancellable: A #GCancellable or %NULL.
1448 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't
1449 * care about the result of the method invocation.
1450 * @user_data: The data to pass to @callback.
1452 * Asynchronously invokes the @method_name method on @proxy.
1454 * If @method_name contains any dots, then @name is split into interface and
1455 * method name parts. This allows using @proxy for invoking methods on
1458 * If the #GDBusConnection associated with @proxy is closed then
1459 * the operation will fail with %G_IO_ERROR_CLOSED. If
1460 * @cancellable is canceled, the operation will fail with
1461 * %G_IO_ERROR_CANCELLED. If @parameters contains a value not
1462 * compatible with the D-Bus protocol, the operation fails with
1463 * %G_IO_ERROR_INVALID_ARGUMENT.
1465 * If the @parameters #GVariant is floating, it is consumed. This allows
1466 * convenient 'inline' use of g_variant_new(), e.g.:
1468 * g_dbus_proxy_call (proxy,
1470 * g_variant_new ("(ss)",
1473 * G_DBUS_CALL_FLAGS_NONE,
1476 * (GAsyncReadyCallback) two_strings_done,
1480 * This is an asynchronous method. When the operation is finished,
1481 * @callback will be invoked in the
1482 * <link linkend="g-main-context-push-thread-default">thread-default
1483 * main loop</link> of the thread you are calling this method from.
1484 * You can then call g_dbus_proxy_call_finish() to get the result of
1485 * the operation. See g_dbus_proxy_call_sync() for the synchronous
1486 * version of this method.
1491 g_dbus_proxy_call (GDBusProxy *proxy,
1492 const gchar *method_name,
1493 GVariant *parameters,
1494 GDBusCallFlags flags,
1496 GCancellable *cancellable,
1497 GAsyncReadyCallback callback,
1500 GSimpleAsyncResult *simple;
1502 gchar *split_interface_name;
1503 const gchar *split_method_name;
1504 const GDBusMethodInfo *expected_method_info;
1505 const gchar *target_method_name;
1506 const gchar *target_interface_name;
1508 g_return_if_fail (G_IS_DBUS_PROXY (proxy));
1509 g_return_if_fail (g_dbus_is_member_name (method_name) || g_dbus_is_interface_name (method_name));
1510 g_return_if_fail (parameters == NULL || g_variant_is_of_type (parameters, G_VARIANT_TYPE_TUPLE));
1511 g_return_if_fail (timeout_msec == -1 || timeout_msec >= 0);
1513 simple = g_simple_async_result_new (G_OBJECT (proxy),
1518 was_split = maybe_split_method_name (method_name, &split_interface_name, &split_method_name);
1519 target_method_name = was_split ? split_method_name : method_name;
1520 target_interface_name = was_split ? split_interface_name : proxy->priv->interface_name;
1522 g_object_set_data_full (G_OBJECT (simple), "-gdbus-proxy-method-name", g_strdup (target_method_name), g_free);
1524 /* Just warn here */
1525 expected_method_info = lookup_method_info_or_warn (proxy, target_method_name);
1527 g_dbus_connection_call (proxy->priv->connection,
1528 proxy->priv->unique_bus_name,
1529 proxy->priv->object_path,
1530 target_interface_name,
1534 timeout_msec == -1 ? proxy->priv->timeout_msec : timeout_msec,
1536 (GAsyncReadyCallback) reply_cb,
1539 g_free (split_interface_name);
1543 * g_dbus_proxy_call_finish:
1544 * @proxy: A #GDBusProxy.
1545 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call().
1546 * @error: Return location for error or %NULL.
1548 * Finishes an operation started with g_dbus_proxy_call().
1550 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
1551 * return values. Free with g_variant_unref().
1556 g_dbus_proxy_call_finish (GDBusProxy *proxy,
1560 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (res);
1562 const char *method_name;
1563 const GDBusMethodInfo *expected_method_info;
1565 g_return_val_if_fail (G_IS_DBUS_PROXY (proxy), NULL);
1566 g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
1567 g_return_val_if_fail (error == NULL || *error == NULL, NULL);
1569 g_warn_if_fail (g_simple_async_result_get_source_tag (simple) == g_dbus_proxy_call);
1573 if (g_simple_async_result_propagate_error (simple, error))
1576 value = g_simple_async_result_get_op_res_gpointer (simple);
1577 method_name = g_object_get_data (G_OBJECT (simple), "-gdbus-proxy-method-name");
1579 /* We may not have a method name for internally-generated proxy calls like GetAll */
1580 if (value && method_name && proxy->priv->expected_interface)
1582 expected_method_info = g_dbus_interface_info_lookup_method (proxy->priv->expected_interface, method_name);
1583 if (!validate_method_return (method_name, value, expected_method_info, error))
1585 g_variant_unref (value);
1595 * g_dbus_proxy_call_sync:
1596 * @proxy: A #GDBusProxy.
1597 * @method_name: Name of method to invoke.
1598 * @parameters: A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
1599 * @flags: Flags from the #GDBusCallFlags enumeration.
1600 * @timeout_msec: The timeout in milliseconds or -1 to use the proxy default timeout.
1601 * @cancellable: A #GCancellable or %NULL.
1602 * @error: Return location for error or %NULL.
1604 * Synchronously invokes the @method_name method on @proxy.
1606 * If @method_name contains any dots, then @name is split into interface and
1607 * method name parts. This allows using @proxy for invoking methods on
1610 * If the #GDBusConnection associated with @proxy is disconnected then
1611 * the operation will fail with %G_IO_ERROR_CLOSED. If
1612 * @cancellable is canceled, the operation will fail with
1613 * %G_IO_ERROR_CANCELLED. If @parameters contains a value not
1614 * compatible with the D-Bus protocol, the operation fails with
1615 * %G_IO_ERROR_INVALID_ARGUMENT.
1617 * If the @parameters #GVariant is floating, it is consumed. This allows
1618 * convenient 'inline' use of g_variant_new(), e.g.:
1620 * g_dbus_proxy_call_sync (proxy,
1622 * g_variant_new ("(ss)",
1625 * G_DBUS_CALL_FLAGS_NONE,
1631 * The calling thread is blocked until a reply is received. See
1632 * g_dbus_proxy_call() for the asynchronous version of this
1635 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
1636 * return values. Free with g_variant_unref().
1641 g_dbus_proxy_call_sync (GDBusProxy *proxy,
1642 const gchar *method_name,
1643 GVariant *parameters,
1644 GDBusCallFlags flags,
1646 GCancellable *cancellable,
1651 gchar *split_interface_name;
1652 const gchar *split_method_name;
1653 const GDBusMethodInfo *expected_method_info;
1654 const gchar *target_method_name;
1655 const gchar *target_interface_name;
1657 g_return_val_if_fail (G_IS_DBUS_PROXY (proxy), NULL);
1658 g_return_val_if_fail (g_dbus_is_member_name (method_name) || g_dbus_is_interface_name (method_name), NULL);
1659 g_return_val_if_fail (parameters == NULL || g_variant_is_of_type (parameters, G_VARIANT_TYPE_TUPLE), NULL);
1660 g_return_val_if_fail (timeout_msec == -1 || timeout_msec >= 0, NULL);
1661 g_return_val_if_fail (error == NULL || *error == NULL, NULL);
1663 was_split = maybe_split_method_name (method_name, &split_interface_name, &split_method_name);
1664 target_method_name = was_split ? split_method_name : method_name;
1665 target_interface_name = was_split ? split_interface_name : proxy->priv->interface_name;
1667 if (proxy->priv->expected_interface)
1669 expected_method_info = g_dbus_interface_info_lookup_method (proxy->priv->expected_interface, target_method_name);
1670 if (expected_method_info == NULL)
1672 g_warning ("Trying to invoke method `%s' which isn't in expected interface `%s'",
1674 target_interface_name);
1679 expected_method_info = NULL;
1682 ret = g_dbus_connection_call_sync (proxy->priv->connection,
1683 proxy->priv->unique_bus_name,
1684 proxy->priv->object_path,
1685 target_interface_name,
1689 timeout_msec == -1 ? proxy->priv->timeout_msec : timeout_msec,
1692 if (!validate_method_return (target_method_name, ret, expected_method_info, error))
1694 g_variant_unref (ret);
1698 g_free (split_interface_name);
1703 /* ---------------------------------------------------------------------------------------------------- */
1705 #define __G_DBUS_PROXY_C__
1706 #include "gioaliasdef.c"