GDBusProxy

GDBusProxy — Client-side D-Bus interface proxy

Functions

Properties

GBusType g-bus-type Write / Construct Only
GDBusConnection * g-connection Read / Write / Construct Only
gint g-default-timeout Read / Write / Construct
GDBusProxyFlags g-flags Read / Write / Construct Only
GDBusInterfaceInfo * g-interface-info Read / Write
gchar * g-interface-name Read / Write / Construct Only
gchar * g-name Read / Write / Construct Only
gchar * g-name-owner Read
gchar * g-object-path Read / Write / Construct Only

Signals

Types and Values

Object Hierarchy

    GObject
    ╰── GDBusProxy

Implemented Interfaces

GDBusProxy implements GDBusInterface, GInitable and GAsyncInitable.

Includes

#include <gio/gio.h>

Description

GDBusProxy is a base class used for proxies to access a D-Bus interface on a remote object. A GDBusProxy can be constructed for both well-known and unique names.

By default, GDBusProxy will cache all properties (and listen to 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. If the proxy is for a well-known name, the property cache is flushed when the name owner vanishes and reloaded when a name owner appears.

If a GDBusProxy is used for a well-known name, the owner of the name is tracked and can be read from “g-name-owner”. Connect to the “notify” signal to get notified of changes. Additionally, only signals and property changes emitted from the current name owner are considered and calls are always sent to the current name owner. This avoids a number of race conditions when the name is lost by one owner and claimed by another. However, if no name owner currently exists, then calls will be sent to the well-known name which may result in the message bus launching an owner (unless G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set).

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. This example shows how this can easily be done using the gdbus-codegen tool.

A GDBusProxy instance can be used from multiple threads but note that all signals (e.g. “g-signal”, “g-properties-changed” and “notify”) are emitted in the thread-default main context of the thread where the instance was constructed.

An example using a proxy for a well-known name can be found in gdbus-example-watch-proxy.c

Functions

g_dbus_proxy_new ()

void
g_dbus_proxy_new (GDBusConnection *connection,
                  GDBusProxyFlags flags,
                  GDBusInterfaceInfo *info,
                  const gchar *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 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.

If name is a well-known name and the G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION flags aren't set and no name owner currently exists, the message bus will be requested to launch a name owner for the name.

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.

GDBusProxy is used in this example.

Parameters

connection

A GDBusConnection.

 

flags

Flags used when constructing the proxy.

 

info

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

[allow-none]

name

A bus name (well-known or unique) or NULL if connection is not a message bus connection.

[allow-none]

object_path

An object path.

 

interface_name

A D-Bus interface name.

 

cancellable

A GCancellable or NULL.

[allow-none]

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.

Parameters

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,
                       GDBusProxyFlags flags,
                       GDBusInterfaceInfo *info,
                       const gchar *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 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.

If name is a well-known name and the G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION flags aren't set and no name owner currently exists, the message bus will be requested to launch a name owner for the name.

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

GDBusProxy is used in this example.

Parameters

connection

A GDBusConnection.

 

flags

Flags used when constructing the proxy.

 

info

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

[allow-none]

name

A bus name (well-known or unique) or NULL if connection is not a message bus connection.

[allow-none]

object_path

An object path.

 

interface_name

A D-Bus interface name.

 

cancellable

A GCancellable or NULL.

[allow-none]

error

Return location for error or NULL.

[allow-none]

Returns

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

Since: 2.26


g_dbus_proxy_new_for_bus ()

void
g_dbus_proxy_new_for_bus (GBusType bus_type,
                          GDBusProxyFlags flags,
                          GDBusInterfaceInfo *info,
                          const gchar *name,
                          const gchar *object_path,
                          const gchar *interface_name,
                          GCancellable *cancellable,
                          GAsyncReadyCallback callback,
                          gpointer user_data);

Like g_dbus_proxy_new() but takes a GBusType instead of a GDBusConnection.

GDBusProxy is used in this example.

Parameters

bus_type

A GBusType.

 

flags

Flags used when constructing the proxy.

 

info

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

[allow-none]

name

A bus name (well-known or unique).

 

object_path

An object path.

 

interface_name

A D-Bus interface name.

 

cancellable

A GCancellable or NULL.

[allow-none]

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_for_bus_finish ()

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

Finishes creating a GDBusProxy.

Parameters

res

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

 

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_for_bus_sync ()

GDBusProxy *
g_dbus_proxy_new_for_bus_sync (GBusType bus_type,
                               GDBusProxyFlags flags,
                               GDBusInterfaceInfo *info,
                               const gchar *name,
                               const gchar *object_path,
                               const gchar *interface_name,
                               GCancellable *cancellable,
                               GError **error);

Like g_dbus_proxy_new_sync() but takes a GBusType instead of a GDBusConnection.

GDBusProxy is used in this example.

Parameters

bus_type

A GBusType.

 

flags

Flags used when constructing the proxy.

 

info

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

[allow-none]

name

A bus name (well-known or unique).

 

object_path

An object path.

 

interface_name

A D-Bus interface name.

 

cancellable

A GCancellable or NULL.

[allow-none]

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.

Parameters

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.

Parameters

proxy

A GDBusProxy.

 

Returns

A GDBusConnection owned by proxy . Do not free.

[transfer none]

Since: 2.26


g_dbus_proxy_get_name ()

const gchar *
g_dbus_proxy_get_name (GDBusProxy *proxy);

Gets the name that proxy was constructed for.

Parameters

proxy

A GDBusProxy.

 

Returns

A string owned by proxy . Do not free.

Since: 2.26


g_dbus_proxy_get_name_owner ()

gchar *
g_dbus_proxy_get_name_owner (GDBusProxy *proxy);

The unique name that owns the name that proxy is for or NULL if no-one currently owns that name. You may connect to the “notify” signal to track changes to the “g-name-owner” property.

Parameters

proxy

A GDBusProxy.

 

Returns

The name owner or NULL if no name owner exists. Free with g_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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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”) and property_name is referenced by it, then value is checked against the type of the property.

Parameters

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”) and property_name is referenced by it, then value is checked against the type of the property.

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

1
2
3
4
5
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).

Parameters

proxy

A GDBusProxy

 

property_name

Property name.

 

value

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

[allow-none]

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 .

Parameters

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().

[transfer full]

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. See the “g-interface-info” property for more details.

Parameters

proxy

A GDBusProxy

 

info

Minimum interface this proxy conforms to or NULL to unset.

[allow-none]

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 interface that proxy conforms to. See the “g-interface-info” property for more details.

Parameters

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.:

1
2
3
4
5
6
7
8
9
10
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);

If proxy has an expected interface (see “g-interface-info”) and method_name is referenced by it, then the return value is checked against the return type.

This is an asynchronous method. When the operation is finished, callback will be invoked in the thread-default main context 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.

If callback is NULL then the D-Bus method call message will be sent with the G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.

Parameters

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.

[allow-none]

flags

Flags from the GDBusCallFlags enumeration.

 

timeout_msec

The timeout in milliseconds (with G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.

 

cancellable

A GCancellable or NULL.

[allow-none]

callback

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

[allow-none]

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().

Parameters

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.:

1
2
3
4
5
6
7
8
9
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.

If proxy has an expected interface (see “g-interface-info”) and method_name is referenced by it, then the return value is checked against the return type.

Parameters

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.

[allow-none]

flags

Flags from the GDBusCallFlags enumeration.

 

timeout_msec

The timeout in milliseconds (with G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.

 

cancellable

A GCancellable or NULL.

[allow-none]

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_with_unix_fd_list ()

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

Like g_dbus_proxy_call() but also takes a GUnixFDList object.

This method is only available on UNIX.

Parameters

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.

[allow-none]

flags

Flags from the GDBusCallFlags enumeration.

 

timeout_msec

The timeout in milliseconds (with G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.

 

fd_list

A GUnixFDList or NULL.

[allow-none]

cancellable

A GCancellable or NULL.

[allow-none]

callback

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

[allow-none]

user_data

The data to pass to callback .

 

Since: 2.30


g_dbus_proxy_call_with_unix_fd_list_finish ()

GVariant *
g_dbus_proxy_call_with_unix_fd_list_finish
                               (GDBusProxy *proxy,
                                GUnixFDList **out_fd_list,
                                GAsyncResult *res,
                                GError **error);

Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list().

Parameters

proxy

A GDBusProxy.

 

out_fd_list

Return location for a GUnixFDList or NULL.

[out][allow-none]

res

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

 

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.30


g_dbus_proxy_call_with_unix_fd_list_sync ()

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

Like g_dbus_proxy_call_sync() but also takes and returns GUnixFDList objects.

This method is only available on UNIX.

Parameters

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.

[allow-none]

flags

Flags from the GDBusCallFlags enumeration.

 

timeout_msec

The timeout in milliseconds (with G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.

 

fd_list

A GUnixFDList or NULL.

[allow-none]

out_fd_list

Return location for a GUnixFDList or NULL.

[out][allow-none]

cancellable

A GCancellable or NULL.

[allow-none]

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.30

Types and Values

enum GDBusProxyFlags

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

Members

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.

 

G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START

If the proxy is for a well-known name, do not ask the bus to launch an owner during proxy initialization or a method call. This flag is only meaningful in proxies for well-known names.

 

G_DBUS_PROXY_FLAGS_GET_INVALIDATED_PROPERTIES

If set, the property value for any <emphasis>invalidated property</emphasis> will be (asynchronously) retrieved upon receiving the <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.htmlstandard-interfaces-properties">PropertiesChanged</ulink> D-Bus signal and the property will not cause emission of the “g-properties-changed” signal. When the value is received the “g-properties-changed” signal is emitted for the property along with the retrieved value. Since 2.32.

 

G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION

If the proxy is for a well-known name, do not ask the bus to launch an owner during proxy initialization, but allow it to be autostarted by a method call. This flag is only meaningful in proxies for well-known names, and only if G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is not also specified.

 

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


struct GDBusProxyClass

struct GDBusProxyClass {
  /* 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);
};

Class structure for GDBusProxy.

Members

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

Property Details

The “g-bus-type” property

  “g-bus-type”               GBusType

If this property is not G_BUS_TYPE_NONE, then “g-connection” must be NULL and will be set to the GDBusConnection obtained by calling g_bus_get() with the value of this property.

Flags: Write / Construct Only

Default value: G_BUS_TYPE_NONE

Since: 2.26


The “g-connection” property

  “g-connection”             GDBusConnection *

The GDBusConnection the proxy is for.

Flags: Read / Write / Construct Only

Since: 2.26


The “g-default-timeout” property

  “g-default-timeout”        gint

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.

Flags: Read / Write / Construct

Allowed values: >= -1

Default value: -1

Since: 2.26


The “g-flags” property

  “g-flags”                  GDBusProxyFlags

Flags from the GDBusProxyFlags enumeration.

Flags: Read / Write / Construct Only

Since: 2.26


The “g-interface-info” property

  “g-interface-info”         GDBusInterfaceInfo *

Ensure that interactions with this proxy conform to the given interface. This is mainly to ensure that malformed data received from the other peer is ignored. The given GDBusInterfaceInfo is said to be the "expected interface".

The checks performed are:

Note that these checks are never done on methods, signals and properties that are not referenced in the given GDBusInterfaceInfo, since extending a D-Bus interface on the service-side is not considered an ABI break.

Flags: Read / Write

Since: 2.26


The “g-interface-name” property

  “g-interface-name”         gchar *

The D-Bus interface name the proxy is for.

Flags: Read / Write / Construct Only

Default value: NULL

Since: 2.26


The “g-name” property

  “g-name”                   gchar *

The well-known or unique name that the proxy is for.

Flags: Read / Write / Construct Only

Default value: NULL

Since: 2.26


The “g-name-owner” property

  “g-name-owner”             gchar *

The unique name that owns “g-name” or NULL if no-one currently owns that name. You may connect to “notify” signal to track changes to this property.

Flags: Read

Default value: NULL

Since: 2.26


The “g-object-path” property

  “g-object-path”            gchar *

The object path the proxy is for.

Flags: Read / Write / Construct Only

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)

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).

If the proxy has the flag G_DBUS_PROXY_FLAGS_GET_INVALIDATED_PROPERTIES set, then invalidated_properties will always be empty.

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

Parameters

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.

 

Flags: Run Last

Since: 2.26


The “g-signal” signal

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

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

Parameters

proxy

The GDBusProxy emitting the signal.

 

sender_name

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

[allow-none]

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.

 

Flags: Run Last

Since: 2.26