GDBusProxy

GDBusProxy — Base class for proxies

Synopsis

#include <gio/gio.h>

enum                GDBusProxyFlags;
                    GDBusProxy;
                    GDBusProxyClass;
void                g_dbus_proxy_new                    (GDBusConnection *connection,
                                                         GType object_type,
                                                         GDBusProxyFlags flags,
                                                         GDBusInterfaceInfo *info,
                                                         const gchar *unique_bus_name,
                                                         const gchar *object_path,
                                                         const gchar *interface_name,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
GDBusProxy *        g_dbus_proxy_new_finish             (GAsyncResult *res,
                                                         GError **error);
GDBusProxy *        g_dbus_proxy_new_sync               (GDBusConnection *connection,
                                                         GType object_type,
                                                         GDBusProxyFlags flags,
                                                         GDBusInterfaceInfo *info,
                                                         const gchar *unique_bus_name,
                                                         const gchar *object_path,
                                                         const gchar *interface_name,
                                                         GCancellable *cancellable,
                                                         GError **error);
GDBusProxyFlags     g_dbus_proxy_get_flags              (GDBusProxy *proxy);
GDBusConnection *   g_dbus_proxy_get_connection         (GDBusProxy *proxy);
const gchar *       g_dbus_proxy_get_unique_bus_name    (GDBusProxy *proxy);
const gchar *       g_dbus_proxy_get_object_path        (GDBusProxy *proxy);
const gchar *       g_dbus_proxy_get_interface_name     (GDBusProxy *proxy);
gint                g_dbus_proxy_get_default_timeout    (GDBusProxy *proxy);
void                g_dbus_proxy_set_default_timeout    (GDBusProxy *proxy,
                                                         gint timeout_msec);
GVariant *          g_dbus_proxy_get_cached_property    (GDBusProxy *proxy,
                                                         const gchar *property_name);
void                g_dbus_proxy_set_cached_property    (GDBusProxy *proxy,
                                                         const gchar *property_name,
                                                         GVariant *value);
gchar **            g_dbus_proxy_get_cached_property_names
                                                        (GDBusProxy *proxy);
void                g_dbus_proxy_set_interface_info     (GDBusProxy *proxy,
                                                         GDBusInterfaceInfo *info);
GDBusInterfaceInfo * g_dbus_proxy_get_interface_info    (GDBusProxy *proxy);
void                g_dbus_proxy_call                   (GDBusProxy *proxy,
                                                         const gchar *method_name,
                                                         GVariant *parameters,
                                                         GDBusCallFlags flags,
                                                         gint timeout_msec,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
GVariant *          g_dbus_proxy_call_finish            (GDBusProxy *proxy,
                                                         GAsyncResult *res,
                                                         GError **error);
GVariant *          g_dbus_proxy_call_sync              (GDBusProxy *proxy,
                                                         const gchar *method_name,
                                                         GVariant *parameters,
                                                         GDBusCallFlags flags,
                                                         gint timeout_msec,
                                                         GCancellable *cancellable,
                                                         GError **error);

Object Hierarchy

  GObject
   +----GDBusProxy

Implemented Interfaces

GDBusProxy implements GInitable and GAsyncInitable.

Properties

  "g-connection"             GDBusConnection*      : Read / Write / Construct Only
  "g-default-timeout"        gint                  : Read / Write / Construct
  "g-flags"                  GDBusProxyFlags       : Read / Write / Construct Only
  "g-interface-info"         GDBusInterfaceInfo*   : Read / Write
  "g-interface-name"         gchar*                : Read / Write / Construct Only
  "g-object-path"            gchar*                : Read / Write / Construct Only
  "g-unique-bus-name"        gchar*                : Read / Write / Construct Only

Signals

  "g-properties-changed"                           : Run Last
  "g-signal"                                       : Run Last

Description

GDBusProxy is a base class used for proxies to access a D-Bus interface on a remote object. A GDBusProxy can only be constructed for unique name bus and does not track whether the name vanishes. Use g_bus_watch_proxy() to construct GDBusProxy proxies for owners of a well-known names.

By default, GDBusProxy will cache all properties (and listen for their changes) of the remote object, and proxy all signals that gets emitted. This behaviour can be changed by passing suitable GDBusProxyFlags when the proxy is created.

The generic "g-properties-changed" and "g-signal" signals are not very convenient to work with. Therefore, the recommended way of working with proxies is to subclass GDBusProxy, and have more natural properties and signals in your derived class. The interface_type argument of g_bus_watch_proxy() lets you obtain instances of your derived class when using the high-level API.

See Example 13, “GDBusProxy subclass example” for an example.

Details

enum GDBusProxyFlags

typedef enum
{
  G_DBUS_PROXY_FLAGS_NONE = 0,                        /*< nick=none >*/
  G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES = (1<<0), /*< nick=do-not-load-properties >*/
  G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS = (1<<1), /*< nick=do-not-connect-signals >*/
} GDBusProxyFlags;

Flags used when constructing an instance of a GDBusProxy derived class.

G_DBUS_PROXY_FLAGS_NONE

No flags set.

G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES

Don't load properties.

G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS

Don't connect to signals on the remote object.

Since 2.26


GDBusProxy

typedef struct _GDBusProxy GDBusProxy;

The GDBusProxy structure contains only private data and should only be accessed using the provided API.

Since 2.26


GDBusProxyClass

typedef struct {
  /* Signals */
  void (*g_properties_changed) (GDBusProxy          *proxy,
                                GVariant            *changed_properties,
                                const gchar* const  *invalidated_properties);
  void (*g_signal)             (GDBusProxy          *proxy,
                                const gchar         *sender_name,
                                const gchar         *signal_name,
                                GVariant            *parameters);
} GDBusProxyClass;

Class structure for GDBusProxy.

g_properties_changed ()

Signal class handler for the "g-properties-changed" signal.

g_signal ()

Signal class handler for the "g-signal" signal.

Since 2.26


g_dbus_proxy_new ()

void                g_dbus_proxy_new                    (GDBusConnection *connection,
                                                         GType object_type,
                                                         GDBusProxyFlags flags,
                                                         GDBusInterfaceInfo *info,
                                                         const gchar *unique_bus_name,
                                                         const gchar *object_path,
                                                         const gchar *interface_name,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Creates a proxy for accessing interface_name on the remote object at object_path owned by unique_bus_name at connection and asynchronously loads D-Bus properties unless the G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. Connect to the "g-properties-changed" signal to get notified about property changes.

If the G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up match rules for signals. Connect to the "g-signal" signal to handle signals from the remote object.

This is a failable asynchronous constructor - when the proxy is ready, callback will be invoked and you can use g_dbus_proxy_new_finish() to get the result.

See g_dbus_proxy_new_sync() and for a synchronous version of this constructor.

connection :

A GDBusConnection.

object_type :

Either G_TYPE_DBUS_PROXY or the GType for the GDBusProxy-derived type of proxy to create.

flags :

Flags used when constructing the proxy.

info :

A GDBusInterfaceInfo specifying the minimal interface that proxy conforms to or NULL.

unique_bus_name :

A unique bus name or NULL if connection is not a message bus connection.

object_path :

An object path.

interface_name :

A D-Bus interface name.

cancellable :

A GCancellable or NULL.

callback :

Callback function to invoke when the proxy is ready.

user_data :

User data to pass to callback.

Since 2.26


g_dbus_proxy_new_finish ()

GDBusProxy *        g_dbus_proxy_new_finish             (GAsyncResult *res,
                                                         GError **error);

Finishes creating a GDBusProxy.

res :

A GAsyncResult obtained from the GAsyncReadyCallback function passed to g_dbus_proxy_new().

error :

Return location for error or NULL.

Returns :

A GDBusProxy or NULL if error is set. Free with g_object_unref().

Since 2.26


g_dbus_proxy_new_sync ()

GDBusProxy *        g_dbus_proxy_new_sync               (GDBusConnection *connection,
                                                         GType object_type,
                                                         GDBusProxyFlags flags,
                                                         GDBusInterfaceInfo *info,
                                                         const gchar *unique_bus_name,
                                                         const gchar *object_path,
                                                         const gchar *interface_name,
                                                         GCancellable *cancellable,
                                                         GError **error);

Creates a proxy for accessing interface_name on the remote object at object_path owned by unique_bus_name at connection and synchronously loads D-Bus properties unless the G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used.

If the G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up match rules for signals. Connect to the "g-signal" signal to handle signals from the remote object.

This is a synchronous failable constructor. See g_dbus_proxy_new() and g_dbus_proxy_new_finish() for the asynchronous version.

connection :

A GDBusConnection.

object_type :

Either G_TYPE_DBUS_PROXY or the GType for the GDBusProxy-derived type of proxy to create.

flags :

Flags used when constructing the proxy.

info :

A GDBusInterfaceInfo specifying the minimal interface that proxy conforms to or NULL.

unique_bus_name :

A unique bus name or NULL if connection is not a message bus connection.

object_path :

An object path.

interface_name :

A D-Bus interface name.

cancellable :

A GCancellable or NULL.

error :

Return location for error or NULL.

Returns :

A GDBusProxy or NULL if error is set. Free with g_object_unref().

Since 2.26


g_dbus_proxy_get_flags ()

GDBusProxyFlags     g_dbus_proxy_get_flags              (GDBusProxy *proxy);

Gets the flags that proxy was constructed with.

proxy :

A GDBusProxy.

Returns :

Flags from the GDBusProxyFlags enumeration.

Since 2.26


g_dbus_proxy_get_connection ()

GDBusConnection *   g_dbus_proxy_get_connection         (GDBusProxy *proxy);

Gets the connection proxy is for.

proxy :

A GDBusProxy.

Returns :

A GDBusConnection owned by proxy. Do not free.

Since 2.26


g_dbus_proxy_get_unique_bus_name ()

const gchar *       g_dbus_proxy_get_unique_bus_name    (GDBusProxy *proxy);

Gets the unique bus name proxy is for.

proxy :

A GDBusProxy.

Returns :

A string owned by proxy. Do not free.

Since 2.26


g_dbus_proxy_get_object_path ()

const gchar *       g_dbus_proxy_get_object_path        (GDBusProxy *proxy);

Gets the object path proxy is for.

proxy :

A GDBusProxy.

Returns :

A string owned by proxy. Do not free.

Since 2.26


g_dbus_proxy_get_interface_name ()

const gchar *       g_dbus_proxy_get_interface_name     (GDBusProxy *proxy);

Gets the D-Bus interface name proxy is for.

proxy :

A GDBusProxy.

Returns :

A string owned by proxy. Do not free.

Since 2.26


g_dbus_proxy_get_default_timeout ()

gint                g_dbus_proxy_get_default_timeout    (GDBusProxy *proxy);

Gets the timeout to use if -1 (specifying default timeout) is passed as timeout_msec in the g_dbus_proxy_call() and g_dbus_proxy_call_sync() functions.

See the "g-default-timeout" property for more details.

proxy :

A GDBusProxy.

Returns :

Timeout to use for proxy.

Since 2.26


g_dbus_proxy_set_default_timeout ()

void                g_dbus_proxy_set_default_timeout    (GDBusProxy *proxy,
                                                         gint timeout_msec);

Sets the timeout to use if -1 (specifying default timeout) is passed as timeout_msec in the g_dbus_proxy_call() and g_dbus_proxy_call_sync() functions.

See the "g-default-timeout" property for more details.

proxy :

A GDBusProxy.

timeout_msec :

Timeout in milliseconds.

Since 2.26


g_dbus_proxy_get_cached_property ()

GVariant *          g_dbus_proxy_get_cached_property    (GDBusProxy *proxy,
                                                         const gchar *property_name);

Looks up the value for a property from the cache. This call does no blocking IO.

If proxy has an expected interface (see "g-interface-info"), then property_name (for existence) is checked against it.

proxy :

A GDBusProxy.

property_name :

Property name.

Returns :

A reference to the GVariant instance that holds the value for property_name or NULL if the value is not in the cache. The returned reference must be freed with g_variant_unref().

Since 2.26


g_dbus_proxy_set_cached_property ()

void                g_dbus_proxy_set_cached_property    (GDBusProxy *proxy,
                                                         const gchar *property_name,
                                                         GVariant *value);

If value is not NULL, sets the cached value for the property with name property_name to the value in value.

If value is NULL, then the cached value is removed from the property cache.

If proxy has an expected interface (see "g-interface-info"), then property_name (for existence) and value (for the type) is checked against it.

If the value GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g.

 g_dbus_proxy_set_cached_property (proxy,
                                   "SomeProperty",
                                   g_variant_new ("(si)",
                                                 "A String",
                                                 42));

Normally you will not need to use this method since proxy is tracking changes using the org.freedesktop.DBus.Properties.PropertiesChanged D-Bus signal. However, for performance reasons an object may decide to not use this signal for some properties and instead use a proprietary out-of-band mechanism to transmit changes.

As a concrete example, consider an object with a property ChatroomParticipants which is an array of strings. Instead of transmitting the same (long) array every time the property changes, it is more efficient to only transmit the delta using e.g. signals ChatroomParticipantJoined(String name) and ChatroomParticipantParted(String name).

proxy :

A GDBusProxy

property_name :

Property name.

value :

Value for the property or NULL to remove it from the cache.

Since 2.26


g_dbus_proxy_get_cached_property_names ()

gchar **            g_dbus_proxy_get_cached_property_names
                                                        (GDBusProxy *proxy);

Gets the names of all cached properties on proxy.

proxy :

A GDBusProxy.

Returns :

A NULL-terminated array of strings or NULL if proxy has no cached properties. Free the returned array with g_strfreev().

Since 2.26


g_dbus_proxy_set_interface_info ()

void                g_dbus_proxy_set_interface_info     (GDBusProxy *proxy,
                                                         GDBusInterfaceInfo *info);

Ensure that interactions with proxy conform to the given interface. For example, when completing a method call, if the type signature of the message isn't what's expected, the given GError is set. Signals that have a type signature mismatch are simply dropped.

See the "g-interface-info" property for more details.

proxy :

A GDBusProxy

info :

Minimum interface this proxy conforms to or NULL to unset.

Since 2.26


g_dbus_proxy_get_interface_info ()

GDBusInterfaceInfo * g_dbus_proxy_get_interface_info    (GDBusProxy *proxy);

Returns the GDBusInterfaceInfo, if any, specifying the minimal interface that proxy conforms to.

See the "g-interface-info" property for more details.

proxy :

A GDBusProxy

Returns :

A GDBusInterfaceInfo or NULL. Do not unref the returned object, it is owned by proxy.

Since 2.26


g_dbus_proxy_call ()

void                g_dbus_proxy_call                   (GDBusProxy *proxy,
                                                         const gchar *method_name,
                                                         GVariant *parameters,
                                                         GDBusCallFlags flags,
                                                         gint timeout_msec,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously invokes the method_name method on proxy.

If method_name contains any dots, then name is split into interface and method name parts. This allows using proxy for invoking methods on other interfaces.

If the GDBusConnection associated with proxy is closed then the operation will fail with G_IO_ERROR_CLOSED. If cancellable is canceled, the operation will fail with G_IO_ERROR_CANCELLED. If parameters contains a value not compatible with the D-Bus protocol, the operation fails with G_IO_ERROR_INVALID_ARGUMENT.

If the parameters GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g.:

 g_dbus_proxy_call (proxy,
                    "TwoStrings",
                    g_variant_new ("(ss)",
                                   "Thing One",
                                   "Thing Two"),
                    G_DBUS_CALL_FLAGS_NONE,
                    -1,
                    NULL,
                    (GAsyncReadyCallback) two_strings_done,
                    &data);

This is an asynchronous method. When the operation is finished, callback will be invoked in the thread-default main loop of the thread you are calling this method from. You can then call g_dbus_proxy_call_finish() to get the result of the operation. See g_dbus_proxy_call_sync() for the synchronous version of this method.

proxy :

A GDBusProxy.

method_name :

Name of method to invoke.

parameters :

A GVariant tuple with parameters for the signal or NULL if not passing parameters.

flags :

Flags from the GDBusCallFlags enumeration.

timeout_msec :

The timeout in milliseconds or -1 to use the proxy default timeout.

cancellable :

A GCancellable or NULL.

callback :

A GAsyncReadyCallback to call when the request is satisfied or NULL if you don't care about the result of the method invocation.

user_data :

The data to pass to callback.

Since 2.26


g_dbus_proxy_call_finish ()

GVariant *          g_dbus_proxy_call_finish            (GDBusProxy *proxy,
                                                         GAsyncResult *res,
                                                         GError **error);

Finishes an operation started with g_dbus_proxy_call().

proxy :

A GDBusProxy.

res :

A GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_proxy_call().

error :

Return location for error or NULL.

Returns :

NULL if error is set. Otherwise a GVariant tuple with return values. Free with g_variant_unref().

Since 2.26


g_dbus_proxy_call_sync ()

GVariant *          g_dbus_proxy_call_sync              (GDBusProxy *proxy,
                                                         const gchar *method_name,
                                                         GVariant *parameters,
                                                         GDBusCallFlags flags,
                                                         gint timeout_msec,
                                                         GCancellable *cancellable,
                                                         GError **error);

Synchronously invokes the method_name method on proxy.

If method_name contains any dots, then name is split into interface and method name parts. This allows using proxy for invoking methods on other interfaces.

If the GDBusConnection associated with proxy is disconnected then the operation will fail with G_IO_ERROR_CLOSED. If cancellable is canceled, the operation will fail with G_IO_ERROR_CANCELLED. If parameters contains a value not compatible with the D-Bus protocol, the operation fails with G_IO_ERROR_INVALID_ARGUMENT.

If the parameters GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g.:

 g_dbus_proxy_call_sync (proxy,
                         "TwoStrings",
                         g_variant_new ("(ss)",
                                        "Thing One",
                                        "Thing Two"),
                         G_DBUS_CALL_FLAGS_NONE,
                         -1,
                         NULL,
                         &error);

The calling thread is blocked until a reply is received. See g_dbus_proxy_call() for the asynchronous version of this method.

proxy :

A GDBusProxy.

method_name :

Name of method to invoke.

parameters :

A GVariant tuple with parameters for the signal or NULL if not passing parameters.

flags :

Flags from the GDBusCallFlags enumeration.

timeout_msec :

The timeout in milliseconds or -1 to use the proxy default timeout.

cancellable :

A GCancellable or NULL.

error :

Return location for error or NULL.

Returns :

NULL if error is set. Otherwise a GVariant tuple with return values. Free with g_variant_unref().

Since 2.26

Property Details

The "g-connection" property

  "g-connection"             GDBusConnection*      : Read / Write / Construct Only

The GDBusConnection the proxy is for.

Since 2.26


The "g-default-timeout" property

  "g-default-timeout"        gint                  : Read / Write / Construct

The timeout to use if -1 (specifying default timeout) is passed as timeout_msec in the g_dbus_proxy_call() and g_dbus_proxy_call_sync() functions.

This allows applications to set a proxy-wide timeout for all remote method invocations on the proxy. If this property is -1, the default timeout (typically 25 seconds) is used. If set to G_MAXINT, then no timeout is used.

Allowed values: >= G_MAXULONG

Default value: -1

Since 2.26


The "g-flags" property

  "g-flags"                  GDBusProxyFlags       : Read / Write / Construct Only

Flags from the GDBusProxyFlags enumeration.

Since 2.26


The "g-interface-info" property

  "g-interface-info"         GDBusInterfaceInfo*   : Read / Write

Ensure that interactions with this proxy conform to the given interface. For example, when completing a method call, if the type signature of the message isn't what's expected, the given GError is set. Signals that have a type signature mismatch are simply dropped.

Since 2.26


The "g-interface-name" property

  "g-interface-name"         gchar*                : Read / Write / Construct Only

The D-Bus interface name the proxy is for.

Default value: NULL

Since 2.26


The "g-object-path" property

  "g-object-path"            gchar*                : Read / Write / Construct Only

The object path the proxy is for.

Default value: NULL

Since 2.26


The "g-unique-bus-name" property

  "g-unique-bus-name"        gchar*                : Read / Write / Construct Only

The unique bus name the proxy is for.

Default value: NULL

Since 2.26

Signal Details

The "g-properties-changed" signal

void                user_function                      (GDBusProxy *proxy,
                                                        GVariant   *changed_properties,
                                                        GStrv      *invalidated_properties,
                                                        gpointer    user_data)                   : Run Last

Emitted when one or more D-Bus properties on proxy changes. The local cache has already been updated when this signal fires. Note that both changed_properties and invalidated_properties are guaranteed to never be NULL (either may be empty though).

This signal corresponds to the PropertiesChanged D-Bus signal on the org.freedesktop.DBus.Properties interface.

proxy :

The GDBusProxy emitting the signal.

changed_properties :

A GVariant containing the properties that changed

invalidated_properties :

A NULL terminated array of properties that was invalidated

user_data :

user data set when the signal handler was connected.

Since 2.26


The "g-signal" signal

void                user_function                      (GDBusProxy *proxy,
                                                        gchar      *sender_name,
                                                        gchar      *signal_name,
                                                        GVariant   *parameters,
                                                        gpointer    user_data)        : Run Last

Emitted when a signal from the remote object and interface that proxy is for, has been received.

proxy :

The GDBusProxy emitting the signal.

sender_name :

The sender of the signal or NULL if the connection is not a bus connection.

signal_name :

The name of the signal.

parameters :

A GVariant tuple with parameters for the signal.

user_data :

user data set when the signal handler was connected.

Since 2.26