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.

Since 2.26

g_dbus_proxy_new_finish ()

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

Finishes creating a GDBusProxy.

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.

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.

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.

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.

Since 2.26

g_dbus_proxy_get_flags ()

GDBusProxyFlags
g_dbus_proxy_get_flags (GDBusProxy *proxy);

Gets the flags that proxy was constructed with.

Since 2.26

g_dbus_proxy_get_connection ()

GDBusConnection *
g_dbus_proxy_get_connection (GDBusProxy *proxy);

Gets the connection proxy is for.

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.

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.

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.

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.

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.

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.

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.

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

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 .

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.

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.

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.

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

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.

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.

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

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.

Since 2.30

enum GDBusProxyFlags

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

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.

Since 2.26

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

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.

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.

Flags: Run Last

Since 2.26